Guia de Testes - Documentação da API FireBanking

Ambientes de Teste

O FireBanking oferece ambientes separados para teste e produção, garantindo desenvolvimento e integração seguros.

Ambiente Sandbox

Base URL: https://api-gateway.firebanking.devTestes seguros com dados e números de cartão fictícios

Ambiente de Produção

Base URL: https://api-gateway.firebanking.com.brAmbiente real para transações efetivas

Credenciais de Teste

Tokens da API Sandbox

x-api-key: SUA_CHAVE_DE_API

Dados de Teste por Produto

Cartão de Crédito

Como testar cobranças de cartão em sandbox:

Cartão	Autorizado?	Status	Exemplo
Final 0, 1 ou 4	SIM	Aprovado	5186 8825 4989 5601
Final 2	NÃO	Não autorizado	5465 4157 3697 6082
Final 3	NÃO	Cartão expirado	5112 9708 0010 5403
Final 5	NÃO	Cartão bloqueado	5528 4303 3551 3025
Final 6	NÃO	Timeout	5186 8825 4989 5601
Final 7	NÃO	Cartão cancelado	5325 8272 3667 3227
Final 8	Aleatório SIM/NÃO	Aprovado / Timeout	5397 5499 7073 5078

Em sandbox, para testar os cenários acima, o CVV sempre deve ser um número de 3 dígitos terminado em zero (Ex: 220). Um número de CVV diferente de zero, irá resultar em falha na geração da transação.

Exemplo de Cartão Completo para Teste

Cartão de Teste

{
  "holderName": "JOSE DAS NEVES TEST",
  "number": "5383638854408981",
  "cvv": 220,
  "expiration": "12/2030"
}

PIX

Para testar o PIX em sandbox: Chaves PIX de Teste:

CPF: Use qualquer CPF válido (ex: 11144477735)
Email: Use emails fictícios (ex: [email protected])
Telefone: Use números fictícios (ex: +5511999999999)
Chave Aleatória: Use UUIDs fictícios (ex: 123e4567-e89b-12d3-a456-426614174000)

Comportamento de Pagamento:

Todos os QR Codes gerados são válidos para teste
O pagamento é simulado automaticamente após 5-30 segundos
Use valores pequenos para teste (ex: R$ 1,00 a R$ 100,00)

Exemplo de Dados PIX de Teste

PIX de Teste

{
  "transaction": {
    "value": 10.00,
    "description": "Cobrança de teste PIX",
    "externalId": "test-pix-001"
  },
  "payer": {
    "fullName": "João da Silva Teste",
    "document": "11144477735"
  }
}

Boleto Bancário

Para testar boletos em sandbox: Dados do Pagador:

Use CPFs/CNPJs válidos mas fictícios
Use endereços realistas mas não reais
CEPs válidos do Brasil (ex: 01000-000, 04038-001)

Comportamento de Pagamento:

Boletos são gerados mas não são registrados no sistema bancário
O pagamento é simulado automaticamente após 1-24 horas
Use valores entre R$ 10,00 e R$ 5.000,00 para teste

Exemplo de Dados Boleto de Teste

Boleto de Teste

{
  "amount": 50.00,
  "dueDate": "2024-12-31",
  "description": "Cobrança de teste boleto",
  "externalId": "test-boleto-001",
  "payer": {
    "name": "João da Silva Teste",
    "document": "11144477735",
    "city": "São Paulo",
    "state": "SP",
    "number": "123",
    "postalCode": "01000000",
    "neighborhood": "Centro",
    "publicArea": "Rua das Flores"
  }
}

Dados de Comprador de Teste

Use dados de comprador realistas mas fictícios para testes:

Números de CPF Válidos para Teste

Comprador Teste

{
  "name": "João da Silva Teste",
  "document": "11144477735", // CPF válido para testes
  "email": "[email protected]",
  "phone": "11999999999",
  "countryCode": "+55",
  "address": {
    "country": "BR",
    "state": "SP",
    "city": "São Paulo",
    "district": "Centro",
    "street": "Rua das Flores",
    "zipCode": "01000000",
    "number": "123"
  }
}

Números de CNPJ Válidos para Teste

Comprador Empresa Teste

{
  "name": "Empresa Teste LTDA",
  "document": "11222333000181", // CNPJ válido para testes
  "email": "[email protected]",
  "phone": "1133334444",
  "countryCode": "+55"
}

Cenários de Teste por Produto

Cartão de Crédito

Fluxo Básico de Pagamento

Pagamento Teste

curl -X POST "https://api-gateway.firebanking.dev/credit-card/v1/payment" \
  -H "x-api-key: SUA_CHAVE_DE_API" \
  -H "Content-Type: application/json" \
  -d '{
    "purchaseValue": 10000,
    "installments": 1,
    "externalId": "test-payment-001",
    "purchaseTitle": "Compra Teste",
    "payment": {
      "chargeType": "FEE_TO_CUSTOMER",
      "capture": true,
      "card": {
        "name": "João da Silva Teste",
        "number": "5186882549895601",
        "expiration": "12/2025",
        "securityCode": "220"
      }
    },
    "buyer": {
      "name": "João da Silva Teste",
      "document": "11144477735",
      "email": "[email protected]",
      "phone": "11999999999",
      "countryCode": "+55",
      "address": {
        "country": "BR",
        "state": "SP",
        "city": "São Paulo",
        "district": "Centro",
        "street": "Rua das Flores",
        "zipCode": "01000000",
        "number": "123"
      }
    }
  }'

Testando Tokenização de Cartão

Criação de Token Teste

curl -X POST "https://api-gateway.firebanking.dev/credit-card/v1/payment/token" \
  -H "x-api-key: SUA_CHAVE_DE_API" \
  -H "Content-Type: application/json" \
  -d '{
    "card": {
      "name": "João da Silva Teste",
      "number": "5186882549895601",
      "expiration": "12/25",
      "securityCode": "123"
    },
    "buyer": {
      "name": "João da Silva Teste",
      "document": "11144477735",
      "email": "[email protected]",
      "phone": "11999999999",
      "countryCode": "+55",
      "address": {
        "country": "BR",
        "state": "SP",
        "city": "São Paulo",
        "district": "Centro",
        "street": "Rua das Flores",
        "zipCode": "01000000",
        "number": "123"
      }
    },
    "checkZeroDollar": true
  }'

Testando Criação de Assinatura

Assinatura Teste

curl -X POST "https://api-gateway.firebanking.dev/credit-card/v1/subscription" \
  -H "x-api-key: SUA_CHAVE_DE_API" \
  -H "Content-Type: application/json" \
  -d '{
    "basicValue": {
      "type": "MONTHLY",
      "valuePerMonth": 2999
    },
    "payment": {
      "method": "CREDIT_CARD",
      "card": {
        "name": "João da Silva Teste",
        "number": "5186882549895601",
        "expiration": "12/2025",
        "securityCode": "220"
      }
    },
    "buyer": {
      "name": "João da Silva Teste",
      "document": "11144477735",
      "email": "[email protected]",
      "phone": "11999999999",
      "countryCode": "+55"
    },
    "startDate": "2024-02-01",
    "description": "Assinatura Mensal Teste"
  }'

Teste de Erros

Testar Requisições Inválidas:

Valor Inválido

curl -X POST "https://api-gateway.firebanking.dev/credit-card/v1/payment" \
  -H "x-api-key: SUA_CHAVE_DE_API" \
  -H "Content-Type: application/json" \
  -d '{
    "purchaseValue": -100,
    "installments": 0
  }'

Testar Erros de Autenticação:

Token Inválido

curl -X POST "https://api-gateway.firebanking.dev/credit-card/v1/payment" \
  -H "x-api-key: token_invalido" \
  -H "Content-Type: application/json" \
  -d '{...}'

PIX

Fluxo Básico de Cobrança PIX

Cobrança PIX Teste

curl -X POST "https://api-gateway.firebanking.dev/pix/v2/payment" \
  -H "x-api-key: SUA_CHAVE_DE_API" \
  -H "Content-Type: application/json" \
  -d '{
    "transaction": {
      "value": 10.00,
      "description": "Cobrança PIX de teste",
      "externalId": "test-pix-001"
    },
    "payer": {
      "fullName": "João da Silva Teste",
      "document": "11144477735"
    }
  }'

Testando QR Code Dinâmico

QR Code Dinâmico

curl -X POST "https://api-gateway.firebanking.dev/pix/v2/payment" \
  -H "x-api-key: SUA_CHAVE_DE_API" \
  -H "Content-Type: application/json" \
  -d '{
    "transaction": {
      "value": 25.00,
      "description": "QR Code dinâmico teste",
      "expirationTime": 3600,
      "externalId": "test-qr-dynamic-001"
    },
    "payer": {
      "fullName": "Maria Silva Teste",
      "document": "22255588844"
    }
  }'

Teste de Erros PIX

Valor Inválido:

Valor PIX Inválido

curl -X POST "https://api-gateway.firebanking.dev/pix/v2/payment" \
  -H "x-api-key: SUA_CHAVE_DE_API" \
  -H "Content-Type: application/json" \
  -d '{
    "transaction": {
      "value": -1.00,
      "description": "Teste valor negativo"
    }
  }'

Boleto Bancário

Fluxo Básico de Emissão

Boleto Teste

curl -X POST "https://api-gateway.firebanking.dev/bank-slip/v1/payment" \
  -H "x-api-key: SUA_CHAVE_DE_API" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 50.00,
    "dueDate": "2024-12-31",
    "description": "Cobrança boleto de teste",
    "externalId": "test-boleto-001",
    "payer": {
      "name": "João da Silva Teste",
      "document": "11144477735",
      "city": "São Paulo",
      "state": "SP",
      "number": "123",
      "postalCode": "01000000",
      "neighborhood": "Centro",
      "publicArea": "Rua das Flores"
    }
  }'

Testando Boleto com Multa e Juros

Boleto com Acréscimos

curl -X POST "https://api-gateway.firebanking.dev/bank-slip/v1/payment" \
  -H "x-api-key: SUA_CHAVE_DE_API" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 100.00,
    "dueDate": "2025-01-15",
    "description": "Boleto com multa e juros",
    "externalId": "test-boleto-with-fees-001",
    "instructions": {
      "fine": {
        "type": "PERCENTAGE",
        "value": 2.0
      },
      "interest": {
        "type": "PERCENTAGE",
        "value": 0.033
      }
    },
    "payer": {
      "name": "Empresa Teste LTDA",
      "document": "11222333000181",
      "city": "São Paulo",
      "state": "SP",
      "number": "456",
      "postalCode": "01000000",
      "neighborhood": "Centro",
      "publicArea": "Avenida Paulista"
    }
  }'

Teste de Erros Boleto

Data de Vencimento Inválida:

Vencimento Inválido

curl -X POST "https://api-gateway.firebanking.dev/bank-slip/v1/payment" \
  -H "x-api-key: SUA_CHAVE_DE_API" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 5000,
    "dueDate": "2023-01-01",
    "description": "Data no passado"
  }'

Teste de Webhooks

Configurando Webhooks de Teste

Use ferramentas como ngrok para testar webhooks localmente:

Configuração do Ngrok

# Instalar ngrok
npm install -g ngrok

# Expor porta local
ngrok http 3000

# Use a URL HTTPS na configuração do webhook
# https://abc123.ngrok.io/webhooks/firebanking

Manipulador de Webhook de Teste

Manipulador Webhook Express.js

const express = require("express");
const app = express();

app.use(express.json());

app.post("/webhooks/firebanking", (req, res) => {
  console.log("Webhook recebido:", req.body);

  const { eventType, data } = req.body;

  // Manipula diferentes tipos de evento
  switch (eventType) {
    case "PAYMENT_COMPLETED":
      console.log("Pagamento concluído:", data.paymentId);
      break;
    case "PAYMENT_FAILED":
      console.log("Pagamento falhou:", data.paymentId);
      break;
    default:
      console.log("Tipo de evento desconhecido:", eventType);
  }

  // Sempre retorna 200 para confirmar recebimento
  res.status(200).json({ received: true });
});

app.listen(3000, () => {
  console.log("Servidor webhook rodando na porta 3000");
});

Testando Entrega de Webhooks

Você pode disparar webhooks de teste manualmente usando ferramentas online:

Webhook.site

URL: webhook.site Capture e inspecione payloads de webhook

RequestBin

URL: requestbin.com Criação de endpoints temporários de webhook

Checklist de Testes

Testes Pré-Integração

Autenticação

Testar validação de token
Testar respostas de erro
Verificar separação de ambientes

Operações Básicas

Endpoint de verificação de saúde
Recuperação de saldo da conta
Tratamento de erros

Teste de Cartão de Crédito

Teste de PIX

Teste de Boleto Bancário

Teste de Tratamento de Erros

Tratamento de timeouts de rede
Respostas de limite de taxa
Tratamento de erros de servidor (500)
Respostas de JSON inválido
Falhas de autenticação
Requisições malformadas

Teste de Webhook

Configuração e acessibilidade do endpoint webhook
Autenticação (se necessário)
Processamento de eventos para todos os tipos de evento
Idempotência (tratamento de eventos duplicados)
Teste do mecanismo de retry
Tratamento de resposta de erro

Ferramentas de Teste

Ferramentas de Teste de API

Postman

Uso: Teste interativo de API e gerenciamento de coleções

Insomnia

Uso: Cliente REST com gerenciamento de ambiente

curl

Uso: Teste via linha de comando e automação

HTTPie

Uso: Cliente HTTP de linha de comando amigável

Testes Automatizados

Exemplo de Teste Jest

const request = require("supertest");

describe("API FireBanking", () => {
  const apiToken = process.env.FIREBANKING_TEST_TOKEN;
  const baseURL = "https://api-gateway.firebanking.dev";

  test("deve criar pagamento com sucesso", async () => {
    const paymentData = {
      purchaseValue: 10000,
      installments: 1,
      externalId: `test-${Date.now()}`,
      payment: {
        chargeType: "FEE_TO_CUSTOMER",
        capture: true,
        card: {
          name: "João da Silva Teste",
          number: "5186882549895601",
          expiration: "12/25",
          securityCode: "123",
        },
      },
      buyer: {
        name: "João da Silva Teste",
        document: "11144477735",
        email: "[email protected]",
        phone: "11999999999",
        countryCode: "+55",
        address: {
          country: "BR",
          state: "SP",
          city: "São Paulo",
          district: "Centro",
          street: "Rua das Flores",
          zipCode: "01000000",
          number: "123",
        },
      },
    };

    const response = await request(`${baseURL}/credit-card/v1`)
      .post("/payment")
      .set("x-api-key", ` ${apiToken}`)
      .send(paymentData)
      .expect(200);

    expect(response.body).toHaveProperty("id");
    expect(response.body.status).toMatch(/processing|completed/);
    expect(response.body.amount).toBe(10000);
  });

  test("deve tratar cartão recusado", async () => {
    const paymentData = {
      purchaseValue: 10000,
      installments: 1,
      payment: {
        chargeType: "FEE_TO_CUSTOMER",
        card: {
          name: "João da Silva Teste",
          number: "4000000000000002", // Sempre recusado
          expiration: "12/25",
          securityCode: "123",
        },
      },
      // ... resto dos dados de pagamento
    };

    const response = await request(`${baseURL}/credit-card/v1`)
      .post("/payment")
      .set("x-api-key", ` ${apiToken}`)
      .send(paymentData)
      .expect(400);

    expect(response.body.error).toBeDefined();
  });
});

Indo para Produção

Checklist Pré-Produção

Antes de mudar para produção:

Testes abrangentes concluídos no sandbox
Tratamento de erros implementado e testado
Endpoints de webhook protegidos e testados
Credenciais de produção obtidas e protegidas
Tratamento de limite de taxa implementado
Monitoramento e logging configurados
Revisão de segurança concluída

Migração para Produção

Atualizar URL base para https://api-gateway.firebanking.com.br
Substituir credenciais de teste por credenciais de produção
Atualizar URLs de webhook para endpoints de produção
Verificar processamento de cartão real com valores pequenos
Monitorar transações de perto inicialmente
Configurar alertas para erros e falhas

Comece com valores pequenos de transação em produção para verificar se tudo funciona corretamente antes de processar pagamentos maiores.

Pronto para começar a testar? Escolha seu método de pagamento e comece a integrar:

🚀 PIX

Instantâneo • 24/7 • Taxa baixaIdeal para começar - mais simples de integrar

💳 Cartão de Crédito

Parcelamento • Assinaturas • GlobalPara e-commerce e pagamentos recorrentes

🏦 Boleto Bancário

Universal • Taxa fixa • ComprovantePara valores altos e clientes sem cartão

Ou comece com a configuração de autenticação para entender os fundamentos da API.

Início

Conceitos Principais

Guias de Integração

​Ambientes de Teste

Ambiente Sandbox

Ambiente de Produção

​Credenciais de Teste

​Tokens da API Sandbox

​Dados de Teste por Produto

​Cartão de Crédito

​Exemplo de Cartão Completo para Teste

​PIX

​Exemplo de Dados PIX de Teste

​Boleto Bancário

​Exemplo de Dados Boleto de Teste

​Dados de Comprador de Teste

​Números de CPF Válidos para Teste

​Números de CNPJ Válidos para Teste

​Cenários de Teste por Produto

​Cartão de Crédito

​Fluxo Básico de Pagamento

​Testando Tokenização de Cartão

​Testando Criação de Assinatura

​Teste de Erros

​PIX

​Fluxo Básico de Cobrança PIX

​Testando QR Code Dinâmico

​Teste de Erros PIX

​Boleto Bancário

​Fluxo Básico de Emissão

​Testando Boleto com Multa e Juros

​Teste de Erros Boleto

​Teste de Webhooks

​Configurando Webhooks de Teste

​Manipulador de Webhook de Teste

​Testando Entrega de Webhooks

Webhook.site

RequestBin

​Checklist de Testes

​Testes Pré-Integração

Autenticação

Operações Básicas

​Teste de Cartão de Crédito

​Teste de PIX

​Teste de Boleto Bancário

​Teste de Tratamento de Erros

​Teste de Webhook

​Ferramentas de Teste

​Ferramentas de Teste de API

Postman

Insomnia

curl

HTTPie

​Testes Automatizados

​Indo para Produção

​Checklist Pré-Produção

​Migração para Produção

🚀 PIX

💳 Cartão de Crédito

🏦 Boleto Bancário

Ambientes de Teste

Credenciais de Teste

Tokens da API Sandbox

Dados de Teste por Produto

Cartão de Crédito

Exemplo de Cartão Completo para Teste

PIX

Exemplo de Dados PIX de Teste

Boleto Bancário

Exemplo de Dados Boleto de Teste

Dados de Comprador de Teste

Números de CPF Válidos para Teste

Números de CNPJ Válidos para Teste

Cenários de Teste por Produto

Cartão de Crédito

Fluxo Básico de Pagamento

Testando Tokenização de Cartão

Testando Criação de Assinatura

Teste de Erros

PIX

Fluxo Básico de Cobrança PIX

Testando QR Code Dinâmico

Teste de Erros PIX

Boleto Bancário

Fluxo Básico de Emissão

Testando Boleto com Multa e Juros

Teste de Erros Boleto

Teste de Webhooks

Configurando Webhooks de Teste

Manipulador de Webhook de Teste

Testando Entrega de Webhooks

Checklist de Testes

Testes Pré-Integração

Teste de Cartão de Crédito

Teste de PIX

Teste de Boleto Bancário

Teste de Tratamento de Erros

Teste de Webhook

Ferramentas de Teste

Ferramentas de Teste de API

Testes Automatizados

Indo para Produção

Checklist Pré-Produção

Migração para Produção