Pular para o conteúdo principal

​
Visão Geral

Este guia apresenta o fluxo completo de integração para processar boletos bancários, desde a criação até o recebimento de pagamentos. O fluxo é composto por 6 etapas principais que garantem uma experiência completa e segura.

​
Fluxo de Etapas

1

Criação do Boleto

Envio dos dados do boleto para API FireBanking
2

Processamento e Registro

Sistema valida dados e envia para banco emissor
3

Confirmação do Registro

Banco confirma registro - Webhook WAITING_PAYMENT enviado
4

Disponibilização para Pagamento

Boleto disponível em toda rede bancária + QR Code PIX
5

Pagamento pelo Cliente

Cliente paga via banco, app, lotérica ou PIX
6

Confirmação de Pagamento

Banco confirma pagamento - Webhook PAID enviado

​
Fluxo Detalhado

​
1. Criação do Boleto

Inicie o processo criando um boleto através da API: 
curl --request POST \
  --url https://api-gateway.firebanking.com.br/bank-slip/v1/payment \
  --header 'x-api-key: sua_chave_api' \
  --header 'Content-Type: application/json' \
  --data '{
    "amount": 150.00,
    "dueDate": "2025-12-31",
    "description": "Pagamento do pedido #12345",
    "externalId": "pedido-12345",
    "payer": {
      "name": "João Silva",
      "document": "12345678901",
      "city": "São Paulo",
      "state": "SP",
      "number": "123",
      "postalCode": "01000000",
      "neighborhood": "Centro",
      "address": "Rua das Flores"
    }
  }'
Resposta da API: 
{
  "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "externalId": "pedido-12345",
  "status": "PENDING",
  "description": "Pagamento do pedido #12345",
  "amount": 150.00,
  "dueDate": "2025-12-31",
  "createdAt": "2025-04-07T15:23:45.678Z"
}

​
2. Processamento e Registro

Após a criação, o boleto é enviado automaticamente para o banco emissor para registro:
  • ⏳ Status inicial: PENDING - Boleto criado, aguardando processamento
  • 🔄 Processamento: Sistema valida dados e envia para o banco
  • ⚡ Tempo médio: 5-10 segundos para confirmação
Durante esta etapa, o sistema FireBanking valida todas as informações e estabelece comunicação com o banco emissor para garantir que o boleto seja registrado corretamente.

​
3. Confirmação do Registro

Quando o banco confirma o registro do boleto com sucesso: Webhook Enviado - WAITING_PAYMENT: 
{
  "product": "BOLETO",
  "paymentId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "status": "WAITING_PAYMENT",
  "externalId": "pedido-12345",
  "processedAt": "2025-04-07T15:23:45.678Z",
  "additionalInfo": {
    "pdfUrl": "https://firebanking.com.br/boletos/f47ac10b-58cc-4372-a567-0e02b2c3d479.pdf",
    "pixCode": "00020101021226830014br.gov.bcb.pix2561firebanking.com.br/qr/v2/f47ac10b-58cc-4372-a567-0e02b2c3d4790000000000",
    "barcode": "03399876543210000025000001234567890123456789012",
    "slipLine": "03399.87654 32100.000025 00000.123456 7 89012345678901",
    "issuingBank": "Banco Inter S.A."
  }
}
Ações recomendadas nesta etapa:
  • ✅ Atualizar status do pedido para “aguardando pagamento”
  • 📧 Enviar boleto por email para o cliente
  • 💾 Salvar dados do boleto (código de barras, linha digitável, PDF)

​
4. Disponibilização para Pagamento

Com o registro confirmado, o boleto fica disponível em toda rede bancária:
  • 🏪 Lotéricas: Aceita pagamento com código de barras
  • 🏦 Bancos: Internet banking e agências físicas
  • 📱 Apps bancários: Escaneamento do código de barras
  • 💳 PIX: Código PIX gerado automaticamente
O boleto pode ser pago mesmo após o vencimento, respeitando as regras de juros e multa configuradas na criação.

​
5. Pagamento pelo Cliente

O cliente pode pagar o boleto através de diversos canais: Opções de pagamento:
  • Aplicativo bancário: Escanear código de barras ou QR Code PIX
  • Internet banking: Copiar linha digitável
  • Agência bancária: Apresentar boleto impresso
  • Lotérica: Apresentar código de barras
  • PIX: Usar o código PIX gerado automaticamente

​
6. Confirmação de Pagamento

Quando o pagamento é processado pelo banco, o webhook final é enviado: Webhook Enviado - PAID: 
{
  "product": "BOLETO",
  "amount": 150.00,
  "paymentId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "status": "PAID",
  "externalId": "pedido-12345",
  "processedAt": "2025-04-07T16:45:23.456Z",
  "additionalInfo": {
    "amount": 150.00,
    "paymentType": 1,
    "paymentDate": "2025-04-07T16:45:23.456Z"
  }
}
Ações finais:
  • ✅ Confirmar pagamento no seu sistema
  • 📦 Liberar produto/serviço para o cliente
  • 📊 Atualizar relatórios financeiros
  • 🎉 Enviar confirmação de pagamento para o cliente

​
Estados do Boleto

StatusDescriçãoAção do Sistema
PENDINGBoleto criado, aguardando registroAguardar confirmação
WAITING_PAYMENTRegistrado e disponível para pagamentoDisponibilizar para cliente
PAIDPagamento confirmadoLiberar produto/serviço
EXPIREDBoleto vencido sem pagamentoGerar novo boleto se necessário
CANCELEDBoleto canceladoInformar cliente sobre cancelamento

​
Tratamento de Webhooks

Implemente um endpoint robusto para receber os webhooks: 
app.post('/webhooks/boleto', express.raw({type: 'application/json'}), (req, res) => {
  try {
    const payload = JSON.parse(req.body);

    // Verificar assinatura do webhook
    if (!verifyWebhookSignature(req.headers, req.body)) {
      return res.status(401).send('Unauthorized');
    }

    // Processar webhook baseado no status
    switch (payload.status) {
      case 'WAITING_PAYMENT':
        // Boleto confirmado - enviar para cliente
        handleBoletoConfirmed(payload);
        break;

      case 'PAID':
        // Pagamento confirmado - liberar produto
        handlePaymentConfirmed(payload);
        break;

      case 'CANCELED':
        // Boleto cancelado - atualizar status
        handleBoletoCanceled(payload);
        break;
    }

    res.status(200).send('OK');
  } catch (error) {
    console.error('Erro processando webhook:', error);
    res.status(500).send('Internal Server Error');
  }
});

​
Monitoramento e Logs

Para uma integração robusta, monitore:
  • 📊 Taxa de conversão: PENDING → WAITING_PAYMENT
  • ⏱️ Tempo de processamento: Criação até confirmação
  • 💰 Taxa de pagamento: WAITING_PAYMENT → PAID
  • 🚫 Boletos expirados: WAITING_PAYMENT → EXPIRED
  • ⚠️ Falhas de webhook: Logs de entrega

​
Próximos Passos

API Reference - Criar Boleto

Documentação completa da API de criação

Webhooks - Boleto Confirmado

Implementar recebimento de confirmações

Webhooks - Boleto Pago

Processar confirmações de pagamento

Sandbox - Ambiente de Testes

Teste sua integração completa