Integração Boleto Bancário - Documentação da API FireBanking

Visão Geral

O Boleto Bancário é um dos métodos de pagamento mais tradicionais e amplamente aceitos no Brasil. Ideal para clientes que preferem não usar cartão ou para transações de valores altos.

Emissão Simples

Gere boletos com dados completos e código de barras

Pagamento Universal

Aceito em qualquer banco, lotérica ou app bancário

Gestão Flexível

Configure vencimentos, multas e prorrogações

PDF Automático

Gere PDFs prontos para impressão ou envio

Características do Boleto

Vantagens

🏦 Ampla aceitação: Pagável em qualquer banco brasileiro
💰 Taxa fixa: Custo previsível independente do valor
📄 Comprovante físico: Cliente recebe comprovante oficial
⏰ Prazo flexível: Configure vencimento conforme necessário
🔒 Segurança: Código de barras único e verificável

Características

⏳ Tempo de compensação: 1-3 dias úteis
💸 Valor mínimo: R$ 10,00
💰 Ideal para: Valores acima de R$ 200,00
📋 Sem conta necessária: Cliente não precisa ter conta bancária
🏪 Múltiplos canais: Bancos, lotéricas, apps, internet banking

Fluxo de Integração

Configuração de Credenciais

Configure suas chaves de API para boletos

Primeiro Boleto

Emita um boleto de teste com dados válidos

Geração de PDF

Configure geração automática de PDF

Webhooks

Configure notificações para pagamentos confirmados

Gestão de Vencimentos

Implemente lógica para multas e prorrogações

Ambientes e Credenciais

URLs dos Ambientes

Sandbox Boleto

Base URL: https://api-gateway.firebanking.dev/bank-slip/v1Use para testes e desenvolvimento

Produção Boleto

Base URL: https://api-gateway.firebanking.com.br/bank-slip/v1Use apenas após validação completa

Autenticação

O boleto usa as mesmas credenciais das outras APIs:

Headers de Autenticação

x-api-key: SUA_CHAVE_DE_API
Content-Type: application/json

Emitindo seu Primeiro Boleto

Estrutura da Requisição

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": 150.75,
    "description": "Pagamento de serviços - Janeiro 2024",
    "externalId": "boleto-001",
    "dueDate": "2024-02-15",
    "payer": {
      "name": "João da Silva Santos",
      "document": "11144477735",
      "city": "São Paulo",
      "state": "SP",
      "number": "123",
      "postalCode": "01000000",
      "neighborhood": "Centro",
      "publicArea": "Rua das Flores"
    },
    "instructions": {
      "fine": {
        "type": "PERCENTAGE",
        "value": 2.0
      },
      "interest": {
        "type": "PERCENTAGE",
        "value": 1.0
      }
    }
  }'

Resposta da Emissão

Exemplo de Resposta

{
  "boletoId": "boleto_abc123def456",
  "externalId": "boleto-001",
  "status": "REGISTERED",
  "amount": 150.75,
  "dueDate": "2024-02-15",
  "barCode": "34191234567890123456789012345678901234567890",
  "digitable": "34191.23456 78901.234567 89012.345678 9 123456789012345",
  "bankNumber": "341",
  "bankName": "Itaú Unibanco",
  "nossoNumero": "12345678901",
  "documentNumber": "boleto-001",
  "created_at": "2024-01-15T10:30:00Z",
  "registeredAt": "2024-01-15T10:30:05Z",
  "pdfUrl": "https://storage.firebanking.dev/boletos/boleto_abc123def456.pdf"
}

Parâmetros do Boleto

Configurações de Vencimento

Data de Vencimento

dueDate: Data limite para pagamento sem multa/juros

Formato: YYYY-MM-DD
Mínimo: Data atual + 1 dia
Máximo: Data atual + 365 dias

Multa por Atraso

fineRate: Percentual de multa após vencimento

Valor: 0% a 10%
Aplicada uma única vez
Calculada sobre valor original

Juros de Mora

interestRate: Percentual mensal de juros

Valor: 0% a 20% ao mês
Aplicado proporcionalmente aos dias
Calculado após a multa

Desconto

discount: Desconto para pagamento antecipado

Tipos: FIXED (valor) ou PERCENTAGE (%)
limitDate: Data limite para desconto
Aplicado antes de multas/juros

Instruções Personalizadas

Exemplos de Instruções

{
  "instructions": [
    "Pagamento referente ao contrato 123/2024",
    "Não receber após 30 dias do vencimento",
    "Dúvidas: (11) 1234-5678",
    "Email: [email protected]"
  ]
}

Geração de PDF

PDF Automático

Por padrão, todo boleto gera automaticamente um PDF:

curl -X POST "https://api-gateway.firebanking.dev/bank-slip/v1/payment/boleto_abc123def456/generate-pdf" \\
  -H "x-api-key: SUA_CHAVE_DE_API" \\
  -H "Content-Type: application/json"

PDF Personalizado

Configure layout e informações personalizadas:

Configuração de PDF

{
  "pdfConfig": {
    "logo": "https://sua-empresa.com/logo.png",
    "companyName": "Sua Empresa LTDA",
    "theme": "blue", // blue, green, red, purple
    "hideInstructions": false,
    "additionalInfo": "Informações extras no PDF"
  }
}

Consultando Status

curl -X GET "https://api-gateway.firebanking.dev/bank-slip/v1/payment/boleto_abc123def456" \\
  -H "x-api-key: SUA_CHAVE_DE_API" \\
  -H "Content-Type: application/json"

Status do Boleto

Status	Descrição	Ação
`PENDING`	Aguardando registro no banco	Aguardar confirmação
`REGISTERED`	Registrado e disponível para pagamento	Enviar para cliente
`PAID`	Pago e confirmado	Liberar produto/serviço
`EXPIRED`	Vencido sem pagamento	Gerar novo boleto
`CANCELLED`	Cancelado manualmente	Confirmar cancelamento

Webhooks para Boleto

Configure notificações automáticas para mudanças de status:

Eventos Disponíveis

Evento	Descrição
`boleto.registered`	Boleto registrado no banco
`boleto.paid`	Boleto pago e confirmado
`boleto.expired`	Boleto venceu sem pagamento
`boleto.cancelled`	Boleto foi cancelado

Payload do Webhook

Exemplo - Boleto Pago

{
  "event": "boleto.paid",
  "boletoId": "boleto_abc123def456",
  "externalId": "boleto-001",
  "timestamp": "2024-02-14T14:30:00Z",
  "data": {
    "boletoId": "boleto_abc123def456",
    "status": "PAID",
    "amount": 150.75,
    "paidAmount": 145.75, // Com desconto
    "paidAt": "2024-02-14T14:30:00Z",
    "bankReceiptNumber": "123456789",
    "paymentMethod": "BANK_AGENCY",
    "discount": 5.00,
    "fine": 0.00,
    "interest": 0.00
  }
}

Configurando Webhooks

curl -X POST "https://api-gateway.firebanking.dev/v1/webhooks/configure" \\
  -H "x-api-key: SUA_CHAVE_DE_API" \\
  -H "Content-Type: application/json" \\
  -d '{
    "url": "https://sua-api.com/webhooks/boleto",
    "events": ["boleto.paid", "boleto.expired"],
    "active": true
  }'

Gestão de Boletos

Cancelamento

curl -X PATCH "https://api-gateway.firebanking.dev/bank-slip/v1/payment/boleto_abc123def456/cancel" \\
  -H "x-api-key: SUA_CHAVE_DE_API" \\
  -H "Content-Type: application/json"

Prorrogação de Vencimento

curl -X PATCH "https://api-gateway.firebanking.dev/bank-slip/v1/boleto_abc123def456" \\
  -H "x-api-key: SUA_CHAVE_DE_API" \\
  -H "Content-Type: application/json" \\
  -d '{
    "newDueDate": "2024-03-15",
    "reason": "Prorrogação solicitada pelo cliente"
  }'

Dados de Teste

Informações Válidas para Sandbox

Cliente de Teste

{
  "payer": {
    "name": "João Testador Boleto",
    "document": "11144477735",
    "city": "São Paulo",
    "state": "SP",
    "number": "123",
    "postalCode": "01000000",
    "neighborhood": "Centro",
    "publicArea": "Rua de Teste"
  }
}

Simulando Pagamentos

curl -X POST "https://api-gateway.firebanking.dev/bank-slip/v1/boleto_abc123def456/simulate-payment" \\
  -H "x-api-key: SUA_CHAVE_DE_API" \\
  -H "Content-Type: application/json" \\
  -d '{
    "paidAmount": 145.75,
    "paymentDate": "2024-02-14",
    "bankReceiptNumber": "123456789"
  }'

Casos de Uso Comuns

E-commerce

const createEcommerceBoleto = async (orderId, customerData, amount) => {
  const boletoData = {
    amount: amount,
    description: `Pedido #${orderId}`,
    externalId: `order-${orderId}`,
    dueDate: getDueDatePlusDays(7), // 7 dias para pagamento
    fineRate: 2.0,
    interestRate: 1.0,
    instructions: [
      `Pagamento do pedido #${orderId}`,
      "Prazo de 7 dias para pagamento",
      "Após vencimento: multa de 2% + juros de 1% a.m."
    ],
    buyer: customerData,
    discount: {
      type: "PERCENTAGE",
      value: 5, // 5% desconto até 3 dias antes
      limitDate: getDueDatePlusDays(4)
    }
  };

  return createBoleto(boletoData);
};

Cobrança Recorrente Manual

Boleto Recorrente

const createRecurringBoleto = async (subscriptionId, month) => {
  const dueDate = getLastDayOfMonth(month);

  const boletoData = {
    amount: 99.90,
    description: `Assinatura ${subscriptionId} - ${month}`,
    externalId: `subscription-${subscriptionId}-${month}`,
    dueDate: dueDate,
    fineRate: 2.0,
    interestRate: 1.0,
    instructions: [
      `Mensalidade da assinatura ${subscriptionId}`,
      `Referente ao mês: ${month}`,
      "Pagamento mensal"
    ],
    buyer: await getSubscriberData(subscriptionId)
  };

  return createBoleto(boletoData);
};

Tratamento de Erros

Erros Comuns

Data de Vencimento Inválida (400)

{
  "error": {
    "code": "INVALID_DUE_DATE",
    "message": "Data de vencimento deve ser no futuro",
    "dueDate": "2024-01-10"
  }
}

Solução: Usar data futura (mínimo: hoje + 1 dia)

Valor Abaixo do Mínimo (422)

{
  "error": {
    "code": "AMOUNT_TOO_LOW",
    "message": "Valor mínimo para boleto é R$ 10,00",
    "minimum": 10.00,
    "requested": 5.00
  }
}

Solução: Usar valor igual ou maior que R$ 10,00

CPF/CNPJ Inválido (422)

{
  "error": {
    "code": "INVALID_DOCUMENT",
    "message": "CPF/CNPJ inválido",
    "document": "12345678900"
  }
}

Solução: Validar CPF/CNPJ antes de enviar

Limites e Valores

Limites Operacionais

Aspecto	Limite
Valor mínimo	R$ 10,00
Valor máximo	R$ 100.000,00
Prazo mínimo	1 dia
Prazo máximo	365 dias
Multa máxima	10%
Juros máximos	20% ao mês

Horários de Processamento

Registro: Imediato (24h/7 dias)
Compensação: 1-3 dias úteis
Webhooks: Tempo real
Cancelamento: Até 1 dia antes do vencimento

Migração para Produção

Validar Testes

Teste emissão, pagamento e cancelamento no sandbox

Configurar Webhooks

URLs de produção validadas e seguras

Obter Credenciais

Solicite chaves de produção via dashboard

Atualizar URLs

Mude para ambiente de produção

Validar Compliance

Verifique requisitos regulatórios

Checklist de Produção

Emissão de boletos testada
Webhooks configurados e funcionando
PDFs sendo gerados corretamente
Tratamento de erros implementado
Validação de dados completa
Monitoramento de status ativo
Processo de cancelamento validado

Próximos Passos

Webhooks Boleto

Configure notificações para pagamentos

API Reference

Documentação completa dos endpoints

Integração PIX

Combine boleto com PIX para maior conversão

Melhores Práticas

Otimize sua integração de boletos

📋 Pronto! Sua integração de boleto bancário está completa e pronta para receber pagamentos.

Início

Conceitos Principais

Guias de Integração

​Visão Geral

Emissão Simples

Pagamento Universal

Gestão Flexível

PDF Automático

​Características do Boleto

​Vantagens

​Características

​Fluxo de Integração

​Ambientes e Credenciais

​URLs dos Ambientes

Sandbox Boleto

Produção Boleto

​Autenticação

​Emitindo seu Primeiro Boleto

​Estrutura da Requisição

​Resposta da Emissão

​Parâmetros do Boleto

​Configurações de Vencimento

​Instruções Personalizadas

​Geração de PDF

​PDF Automático

​PDF Personalizado

​Consultando Status

​Status do Boleto

​Webhooks para Boleto

​Eventos Disponíveis

​Payload do Webhook

​Configurando Webhooks

​Gestão de Boletos

​Cancelamento

​Prorrogação de Vencimento

​Dados de Teste

​Informações Válidas para Sandbox

​Simulando Pagamentos

​Casos de Uso Comuns

​E-commerce

​Cobrança Recorrente Manual

​Tratamento de Erros

​Erros Comuns

​Limites e Valores

​Limites Operacionais

​Horários de Processamento

​Migração para Produção

​Checklist de Produção

​Próximos Passos

Webhooks Boleto

API Reference

Integração PIX

Melhores Práticas

Visão Geral

Características do Boleto

Vantagens

Características

Fluxo de Integração

Ambientes e Credenciais

URLs dos Ambientes

Autenticação

Emitindo seu Primeiro Boleto

Estrutura da Requisição

Resposta da Emissão

Parâmetros do Boleto

Configurações de Vencimento

Instruções Personalizadas

Geração de PDF

PDF Automático

PDF Personalizado

Consultando Status

Status do Boleto

Webhooks para Boleto

Eventos Disponíveis

Payload do Webhook

Configurando Webhooks

Gestão de Boletos

Cancelamento

Prorrogação de Vencimento

Dados de Teste

Informações Válidas para Sandbox

Simulando Pagamentos

Casos de Uso Comuns

E-commerce

Cobrança Recorrente Manual

Tratamento de Erros

Erros Comuns

Limites e Valores

Limites Operacionais

Horários de Processamento

Migração para Produção

Checklist de Produção

Próximos Passos