Pular para o conteúdo principal
POST
/
bank-slip
/
v1
/
payment
Criar Boleto
curl --request POST \
  --url https://api-gateway.firebanking.dev/bank-slip/v1/payment \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "amount": 1899.75,
  "dueDate": "2025-04-15",
  "payer": {
    "name": "CARLOS EDUARDO MENDES",
    "document": "315.472.689-01",
    "city": "SÃO PAULO",
    "state": "SP",
    "number": "1024",
    "postalCode": "04119001",
    "neighborhood": "VILA MARIANA",
    "publicArea": "RUA DOMINGOS DE MORAIS"
  },
  "externalId": "a7c1e3b5-8f42-45d6-9b3c-1d5f98a0d123",
  "description": "Pagamento referente à mensalidade do serviço contratado",
  "instructions": {
    "interest": {
      "type": "PERCENTAGE",
      "value": 10
    },
    "fine": {
      "type": "PERCENTAGE",
      "value": 0.2
    }
  },
  "callback_url": "<string>",
  "metadata": {}
}
'
{
    "id": "3f73ad66-04cb-4c2d-9520-e41e41c576cc"
}

Visão Geral

Crie um boleto bancário registrado para recebimento de pagamentos. O boleto será registrado automaticamente no banco e ficará disponível para pagamento em toda rede bancária nacional.

Parâmetros da Requisição

amount
integer
required
Valor do boleto em reais (ex: 100.00, 25.50). Mínimo: 2.50
dueDate
string
required
Data de vencimento do boleto (formato: YYYY-MM-DD). Máximo 90 dias após emissão
description
string
required
Descrição da cobrança (máximo 200 caracteres)
externalId
string
required
Identificador único da transação em seu sistema
payer
object
required
Dados completos do pagador
instructions
object
Configurações de multa e juros para pagamento após vencimento
metadata
object
Dados adicionais da transação (chave-valor)

Exemplo de Requisição

curl -X POST "https://api-gateway.firebanking.com.br/bank-slip/v1/payment" \
  -H "x-api-key: SUA_CHAVE_DE_API" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 1899.75,
    "payer": {
        "name": "CARLOS EDUARDO MENDES",
        "document": "315.472.689-01",
        "city": "SÃO PAULO",
        "state": "SP",
        "number": "1024",
        "postalCode": "04119001",
        "neighborhood": "VILA MARIANA",
        "publicArea": "RUA DOMINGOS DE MORAIS"
    },
    "dueDate": "2025-04-15",
    "description": "Pagamento referente à mensalidade do serviço contratado",
    "externalId": "a7c1e3b5-8f42-45d6-9b3c-1d5f98a0d123",
    "instructions": {
        "interest": {
            "type": "PERCENTAGE",
            "value": 10
        },
        "fine": {
            "type": "PERCENTAGE",
            "value": 0.20
        }
    }
  }'

Exemplo de Resposta

{
    "id": "3f73ad66-04cb-4c2d-9520-e41e41c576cc"
}

Campos de Resposta

id
string
ID único do boleto no FireBanking

Implementação Frontend

Exibir Boleto Criado

<div class="boleto-success">
  <h2>✅ Boleto Gerado com Sucesso!</h2>
  
  <div class="boleto-details">
    <div class="detail-row">
      <strong>Valor:</strong>
      <span id="boleto-amount">R$ 250,00</span>
    </div>
    <div class="detail-row">
      <strong>Vencimento:</strong>
      <span id="boleto-due-date">15/02/2024</span>
    </div>
    <div class="detail-row">
      <strong>Código de Barras:</strong>
      <input type="text" id="boleto-barcode" readonly>
      <button onclick="copyBarcode()" title="Copiar código">📋</button>
    </div>
  </div>
  
  <div class="boleto-actions">
    <a href="#" id="boleto-pdf" class="btn btn-primary" target="_blank">
      📄 Visualizar Boleto
    </a>
    <button onclick="sendByEmail()" class="btn btn-secondary">
      📧 Enviar por Email
    </button>
    <button onclick="shareWhatsApp()" class="btn btn-success">
      📱 Compartilhar WhatsApp
    </button>
  </div>
  
  <div class="boleto-info">
    <h4>📋 Como Pagar:</h4>
    <ul>
      <li><strong>Internet Banking:</strong> Use o código de barras ou linha digitável</li>
      <li><strong>App do Banco:</strong> Escaneie o código de barras</li>
      <li><strong>Agência Bancária:</strong> Leve o boleto impresso</li>
      <li><strong>Lotérica:</strong> Apresente o código de barras</li>
    </ul>
  </div>
</div>

Funções JavaScript

let currentBoleto = null;

function displayBoleto(boletoData) {
  currentBoleto = boletoData;
  
  // Formatar e exibir dados
  document.getElementById('boleto-amount').textContent = 
    boletoData.amount.toLocaleString('pt-BR', {
      style: 'currency',
      currency: 'BRL'
    });
  
  document.getElementById('boleto-due-date').textContent = 
    new Date(boletoData.due_date).toLocaleDateString('pt-BR');
  
  document.getElementById('boleto-barcode').value = boletoData.digitable_line;
  document.getElementById('boleto-pdf').href = boletoData.pdf_url;
}

function copyBarcode() {
  const barcodeInput = document.getElementById('boleto-barcode');
  barcodeInput.select();
  navigator.clipboard.writeText(barcodeInput.value);
  
  // Feedback visual
  alert('📋 Código copiado! Cole no app do seu banco para pagar.');
}

function sendByEmail() {
  const email = currentBoleto.buyer.email;
  const subject = 'Seu Boleto - ' + currentBoleto.description;
  const body = `Olá!\n\nSeu boleto está pronto para pagamento:\n\n` +
    `Valor: R$ ${currentBoleto.amount.toFixed(2)}\n` +
    `Vencimento: ${new Date(currentBoleto.due_date).toLocaleDateString('pt-BR')}\n\n` +
    `Link do boleto: ${currentBoleto.payment_link}\n\n` +
    `Você pode pagar em qualquer banco, app bancário ou lotérica.\n\n` +
    `Att,\nEquipe de Cobrança`;
  
  const mailtoLink = `mailto:${email}?subject=${encodeURIComponent(subject)}&body=${encodeURIComponent(body)}`;
  window.location.href = mailtoLink;
}

function shareWhatsApp() {
  const phone = currentBoleto.buyer.phone;
  const message = `🧾 *Boleto Disponível*\n\n` +
    `💰 Valor: R$ ${currentBoleto.amount.toFixed(2)}\n` +
    `📅 Vencimento: ${new Date(currentBoleto.due_date).toLocaleDateString('pt-BR')}\n\n` +
    `🔗 Link do boleto:\n${currentBoleto.payment_link}\n\n` +
    `📱 Você pode pagar pelo app do seu banco ou em qualquer agência/lotérica`;
  
  const whatsappLink = `https://wa.me/55${phone}?text=${encodeURIComponent(message)}`;
  window.open(whatsappLink, '_blank');
}

Verificar Status do Boleto

async function checkBoletoStatus(boletoId) {
  try {
    const response = await fetch(`https://api-gateway.firebanking.com.br/bank-slip/v1/payment/${boletoId}`, {
      headers: {
        'x-api-key': 'SUA_CHAVE_DE_API'
      }
    });
    
    const boleto = await response.json();
    
    if (boleto.status === 'paid') {
      showPaymentConfirmed(boleto);
    } else if (boleto.status === 'expired') {
      showBoletoExpired(boleto);
    }
    
    return boleto.status;
  } catch (error) {
    console.error('Erro ao verificar status do boleto:', error);
  }
}

function showPaymentConfirmed(boleto) {
  const notification = document.createElement('div');
  notification.className = 'alert alert-success';
  notification.innerHTML = `
    <h4>✅ Pagamento Confirmado!</h4>
    <p>O boleto foi pago em ${new Date(boleto.paid_at).toLocaleDateString('pt-BR')}</p>
    <p>Valor pago: ${boleto.paid_amount.toLocaleString('pt-BR', {style: 'currency', currency: 'BRL'})}</p>
  `;
  
  document.body.prepend(notification);
}

Validações Importantes

CPF/CNPJ

function validateDocument(document) {
  // Remove caracteres não numéricos
  const cleanDoc = document.replace(/\D/g, '');
  
  if (cleanDoc.length === 11) {
    return validateCPF(cleanDoc);
  } else if (cleanDoc.length === 14) {
    return validateCNPJ(cleanDoc);
  }
  
  return false;
}

function validateCPF(cpf) {
  // Implementar validação de CPF
  // (algoritmo padrão de validação)
  return true; // Simplificado
}

function validateCNPJ(cnpj) {
  // Implementar validação de CNPJ
  // (algoritmo padrão de validação)
  return true; // Simplificado
}

CEP

async function validateAndFillAddress(cep) {
  const cleanCep = cep.replace(/\D/g, '');
  
  if (cleanCep.length !== 8) {
    throw new Error('CEP deve ter 8 dígitos');
  }
  
  try {
    const response = await fetch(`https://viacep.com.br/ws/${cleanCep}/json/`);
    const address = await response.json();
    
    if (address.erro) {
      throw new Error('CEP não encontrado');
    }
    
    return {
      street: address.logradouro,
      district: address.bairro,
      city: address.localidade,
      state: address.uf,
      zip_code: cleanCep
    };
  } catch (error) {
    throw new Error('Erro ao consultar CEP: ' + error.message);
  }
}

Códigos de Erro

CódigoDescrição
INVALID_AMOUNTValor inválido (mín: R2,50,maˊx:R 2,50, máx: R 50.000,00)
INVALID_DUE_DATEData de vencimento inválida (máximo 90 dias)
INVALID_DOCUMENTCPF ou CNPJ inválido
INVALID_EMAILEmail inválido ou não fornecido
INVALID_ADDRESSEndereço incompleto ou inválido
INVALID_CEPCEP inválido (deve ter 8 dígitos)
EXTERNAL_ID_EXISTSExternalId já usado em boleto ativo
REGISTRATION_FAILEDFalha no registro bancário

Boas Práticas

Dados do Pagador

  • Valide CPF/CNPJ: Use algoritmos de validação antes de enviar
  • CEP obrigatório: Endereço completo é exigido pelos bancos
  • Email válido: Necessário para envio automático do boleto
  • Nome completo: Evite abreviações ou apelidos

Gestão de Vencimentos

  • Prazo adequado: 7-15 dias para e-commerce, 30 dias para B2B
  • Considere fins de semana: Evite vencimento em sábados/domingos
  • Planeje feriados: Considere feriados nacionais e locais
  • Margem de segurança: Dê tempo para processamento bancário

Experiência do Cliente

  • Instruções claras: Explique como pagar o boleto
  • Múltiplos formatos: Ofereça PDF, código de barras e linha digitável
  • Compartilhamento fácil: Facilite envio por email/WhatsApp
  • Status em tempo real: Informe quando o pagamento foi confirmado

Próximos Passos

Authorizations

x-api-key
string
header
required

Chave de API para autenticação

Body

application/json
amount
number
required

Valor do boleto em reais

Intervalo obrigatório: x >= 0.01
Example:

1899.75

dueDate
string<date>
required

Data de vencimento do boleto (YYYY-MM-DD)

Example:

"2025-04-15"

payer
object
required
externalId
string

Identificador único do boleto em seu sistema

Example:

"a7c1e3b5-8f42-45d6-9b3c-1d5f98a0d123"

description
string

Descrição do boleto/finalidade do pagamento

Example:

"Pagamento referente à mensalidade do serviço contratado"

instructions
object

Configurações de multa e juros

Example:
{
"interest": { "type": "PERCENTAGE", "value": 10 },
"fine": { "type": "PERCENTAGE", "value": 0.2 }
}
callback_url
string<uri>

URL para receber webhooks específicos deste boleto

metadata
object

Dados adicionais do boleto

Response

Boleto criado com sucesso

id
string
required

ID único do boleto no FireBanking

Example:

"3f73ad66-04cb-4c2d-9520-e41e41c576cc"