Consultar Boleto

Visão Geral

Consulte informações detalhadas de um boleto bancário utilizando o ID da transação ou seu externalId. Este endpoint retorna dados completos sobre o status, valores, pagador e metadados do boleto.

Use este endpoint para verificar se um boleto foi pago, cancelado ou ainda está aguardando pagamento.

Parâmetros da URL

string

required

ID do boleto ou externalId fornecido na criação

Exemplo de Requisição

curl --request GET \
  --url 'https://api-gateway.firebanking.com.br/bank-slip/v1/payment/<id>' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <sua-chave-api>'

Exemplo de Resposta

{
    "amount": "850.75",
    "description": "Pagamento referente à fatura de serviços prestados no mês de março",
    "dueDate": "2025-04-10",
    "externalId": "EXT987654321",
    "id": "a7b8c9d0-1234-5678-abcd-efghijklmnop",
    "paymentDate": "2023-08-15T09:30:00.000Z",
    "status": "PAID",
    "barcode": "34198103400001850700125005310145678965430000",
    "slipLine": "34191090090518507634567890000003810290000850750",
    "issuingBank": "bradesco",
    "pixCode": "00020101021226980014br.gov.bcb.pix2576qrcode-h.pix.celcoin.com.br/pixqrcode/v2/cobv/9e30b4fcb8ef234b1c5a7e9f6dff62214000053039865802BR5924Servicos Exemplares Ltda6007SaoPaulo62070503***6304DEFG",
    "transactions": [
        {
            "id": "b8d7e6a5-1234-5678-abcd-9876543210fe",
            "status": "PENDING"
        },
        {
            "id": "d4f5e6a7-89b0-1234-cdef-1234567890ab",
            "status": "WAITING_PAYMENT"
        },
        {
            "id": "a1b2c3d4-5678-1234-e567-8901234567cd",
            "status": "PAID"
        }
    ],
    "instructions": {
        "fine": {
            "type": "PERCENTAGE",
            "value": "0.5"
        },
        "interest": {
            "type": "PERCENTAGE",
            "value": "12"
        }
    },
    "pdfUrl": "https://s3.us-east-1.amazonaws.com/dev...",
    "payer": {
        "city": "SAO PAULO",
        "name": "JULIANO PEREIRA SILVA",
        "document": "12345678901",
        "neighborhood": "PONTE GRANDE",
        "number": "2500",
        "postalCode": "03367010",
        "publicArea": "AV. RIO DAS PEDRAS",
        "state": "SP"
    }
}

Status do Boleto

Estados Possíveis

registered

Descrição: Boleto registrado no banco, aguardando pagamento
Ações possíveis: Cancelar, gerar PDF, aguardar pagamento
Próximo status: paid, expired, cancelled

paid

Descrição: Boleto pago com sucesso
Dados adicionais: Valor pago, data de pagamento, banco pagador
Status final: Transação concluída

expired

Descrição: Boleto expirou (90 dias após vencimento)
Ação: Não é mais possível pagar
Status final: Criar novo boleto se necessário

cancelled

Descrição: Boleto cancelado pelo lojista
Ação: Não é mais possível pagar
Status final: Cancelamento irreversível

Implementação Frontend

Verificar Status Automaticamente

class BoletoStatusChecker {
  constructor(boletoId) {
    this.boletoId = boletoId;
    this.checkInterval = null;
    this.maxChecks = 120; // 2 horas (verificar a cada 60s)
    this.currentCheck = 0;
  }

  start() {
    this.checkInterval = setInterval(() => {
      this.checkStatus();
    }, 60000); // Verificar a cada 1 minuto

    // Primeira verificação imediata
    this.checkStatus();
  }

  async checkStatus() {
    try {
      const response = await fetch(`/api/boleto/${this.boletoId}/status`);
      const boleto = await response.json();

      this.handleStatusUpdate(boleto);

      // Parar verificação se pago ou expirado
      if (['paid', 'expired', 'cancelled'].includes(boleto.status)) {
        this.stop();
      }

      // Parar após limite de verificações
      this.currentCheck++;
      if (this.currentCheck >= this.maxChecks) {
        this.stop();
      }
    } catch (error) {
      console.error('Erro ao verificar status:', error);
    }
  }

  handleStatusUpdate(boleto) {
    switch (boleto.status) {
      case 'paid':
        this.showPaymentSuccess(boleto);
        break;
      case 'expired':
        this.showBoletoExpired(boleto);
        break;
      case 'cancelled':
        this.showBoletoCancelled(boleto);
        break;
      default:
        this.updateStatusDisplay(boleto.status);
    }
  }

  showPaymentSuccess(boleto) {
    document.getElementById('boleto-status').innerHTML = `
      <div class="alert alert-success">
        <h4>✅ Pagamento Confirmado!</h4>
        <p>Boleto pago em ${formatDate(boleto.paid_at)}</p>
        <p>Valor pago: ${formatCurrency(boleto.paid_amount)}</p>
      </div>
    `;

    // Redirecionar ou processar próximos passos
    setTimeout(() => {
      window.location.href = '/pedido/confirmado';
    }, 3000);
  }

  showBoletoExpired(boleto) {
    document.getElementById('boleto-status').innerHTML = `
      <div class="alert alert-warning">
        <h4>⏰ Boleto Expirado</h4>
        <p>Este boleto expirou e não pode mais ser pago.</p>
        <button onclick="generateNewBoleto()">Gerar Novo Boleto</button>
      </div>
    `;
  }

  stop() {
    if (this.checkInterval) {
      clearInterval(this.checkInterval);
      this.checkInterval = null;
    }
  }
}

// Uso
const statusChecker = new BoletoStatusChecker('bol_1234567890123456');
statusChecker.start();

Exibir Dados do Boleto

<div id="boleto-details">
  <div class="boleto-header">
    <h3>Boleto Bancário</h3>
    <span class="status-badge" id="status-badge">Aguardando Pagamento</span>
  </div>

  <div class="boleto-info">
    <div class="info-group">
      <label>Valor:</label>
      <span id="boleto-amount" class="amount">R$ 250,00</span>
    </div>

    <div class="info-group">
      <label>Vencimento:</label>
      <span id="boleto-due-date">15/02/2024</span>
    </div>

    <div class="info-group">
      <label>Código de Barras:</label>
      <div class="barcode-input">
        <input type="text" id="barcode" readonly>
        <button onclick="copyBarcode()">📋</button>
      </div>
    </div>
  </div>

  <div class="boleto-actions">
    <a href="#" id="pdf-link" class="btn btn-primary" target="_blank">
      📄 Visualizar PDF
    </a>
    <button onclick="checkPayment()" class="btn btn-secondary">
      🔄 Verificar Pagamento
    </button>
  </div>

  <div id="payment-details" style="display: none;">
    <!-- Detalhes do pagamento aparecerão aqui quando pago -->
  </div>
</div>

Funções de Utilidade

function formatCurrency(amount) {
  return (amount / 100).toLocaleString('pt-BR', {
    style: 'currency',
    currency: 'BRL'
  });
}

function formatDate(dateString) {
  return new Date(dateString).toLocaleDateString('pt-BR');
}

function updateBoletoDisplay(boleto) {
  document.getElementById('boleto-amount').textContent = formatCurrency(boleto.amount);
  document.getElementById('boleto-due-date').textContent = formatDate(boleto.due_date);
  document.getElementById('barcode').value = boleto.digitable_line;
  document.getElementById('pdf-link').href = boleto.pdf_url;

  updateStatusBadge(boleto.status);

  if (boleto.status === 'paid') {
    showPaymentDetails(boleto);
  }
}

function updateStatusBadge(status) {
  const badge = document.getElementById('status-badge');
  const statusMap = {
    'registered': { text: 'Aguardando Pagamento', class: 'status-pending' },
    'paid': { text: 'Pago', class: 'status-success' },
    'expired': { text: 'Expirado', class: 'status-error' },
    'cancelled': { text: 'Cancelado', class: 'status-error' }
  };

  const statusInfo = statusMap[status] || { text: status, class: 'status-default' };
  badge.textContent = statusInfo.text;
  badge.className = `status-badge ${statusInfo.class}`;
}

function showPaymentDetails(boleto) {
  const detailsDiv = document.getElementById('payment-details');
  detailsDiv.innerHTML = `
    <div class="payment-success">
      <h4>✅ Pagamento Confirmado</h4>
      <div class="payment-info">
        <p><strong>Valor Pago:</strong> ${formatCurrency(boleto.paid_amount)}</p>
        <p><strong>Data do Pagamento:</strong> ${formatDate(boleto.paid_at)}</p>
        <p><strong>Banco:</strong> ${boleto.payment_info.bank_name}</p>
        ${boleto.fees.total_fees > 0 ?
          `<p><strong>Multa/Juros:</strong> ${formatCurrency(boleto.fees.total_fees)}</p>` :
          ''
        }
      </div>
    </div>
  `;
  detailsDiv.style.display = 'block';
}

Casos de Uso

Dashboard Administrativo

async function loadBoletosDashboard() {
  const boletos = await fetch('/api/boletos/recent').then(r => r.json());

  const statusCounts = boletos.reduce((acc, boleto) => {
    acc[boleto.status] = (acc[boleto.status] || 0) + 1;
    return acc;
  }, {});

  displayDashboardMetrics(statusCounts);
}

function displayDashboardMetrics(statusCounts) {
  document.getElementById('total-registered').textContent = statusCounts.registered || 0;
  document.getElementById('total-paid').textContent = statusCounts.paid || 0;
  document.getElementById('total-expired').textContent = statusCounts.expired || 0;
}

Reconciliação Financeira

async function generateReconciliationReport(startDate, endDate) {
  const response = await fetch(`/api/boletos/paid?start=${startDate}&end=${endDate}`);
  const paidBoletos = await response.json();

  const report = {
    total_transactions: paidBoletos.length,
    gross_amount: paidBoletos.reduce((sum, b) => sum + b.paid_amount, 0),
    fees_amount: paidBoletos.reduce((sum, b) => sum + b.reconciliation.firebanking_fee, 0),
    net_amount: paidBoletos.reduce((sum, b) => sum + b.reconciliation.net_amount, 0)
  };

  return report;
}

Próximos Passos

Gerar PDF

Baixe o arquivo PDF do boleto

Cancelar Boleto

Cancele boletos não pagos

Webhooks

Configure notificações automáticas

Relatórios

Gere relatórios de boletos

Authorizations

x-api-key

string

header

required

Chave de API para autenticação

Path Parameters

string

required

ID do boleto ou externalId

Response

Detalhes do boleto

amount

string

Valor do boleto em reais

Example:

"850.75"

description

string

Descrição do boleto

Example:

"Pagamento referente à fatura de serviços prestados no mês de março"

dueDate

string<date>

Data de vencimento

Example:

"2025-04-10"

externalId

string

Seu identificador único do boleto

Example:

"EXT987654321"

string

ID único do boleto no FireBanking

Example:

"a7b8c9d0-1234-5678-abcd-efghijklmnop"

paymentDate

string<date-time>

Data de pagamento

Example:

"2023-08-15T09:30:00.000Z"

status

enum<string>

Status atual do boleto

Opções disponíveis:

PENDING,

CONFIRMED,

PAID,

EXPIRED,

CANCELLED

Example:

"PAID"

barcode

string

Código de barras do boleto

Example:

"34198103400001850700125005310145678965430000"

slipLine

string

Linha digitável do boleto

Example:

"34191090090518507634567890000003810290000850750"

issuingBank

string

Banco emissor do boleto

Example:

"bradesco"

pixCode

string

Código PIX do boleto

Example:

"00020101021226980014br.gov.bcb.pix2576qrcode-h.pix.celcoin.com.br/pixqrcode/v2/cobv/9e30b4fcb8ef234b1c5a7e9f6dff62214000053039865802BR5924Servicos Exemplares Ltda6007SaoPaulo62070503***6304DEFG"

transactions

object[]

Lista de transações relacionadas ao boleto

Mostrar atributos filhos

transactions.id

string

ID da transação

Example:

"b8d7e6a5-1234-5678-abcd-9876543210fe"

transactions.status

enum<string>

Status da transação

Opções disponíveis:

PENDING,

WAITING_PAYMENT,

PAID,

CANCELLED

Example:

"PENDING"

instructions

object

Instruções de multa e juros

Mostrar atributos filhos

instructions.fine

object

Mostrar atributos filhos

instructions.fine.type

enum<string>

Tipo de multa

Opções disponíveis:

PERCENTAGE,

FIXED

Example:

"PERCENTAGE"

instructions.fine.value

string

Valor da multa

Example:

"0.5"

instructions.interest

object

Mostrar atributos filhos

instructions.interest.type

enum<string>

Tipo de juros

Opções disponíveis:

PERCENTAGE,

FIXED

Example:

"PERCENTAGE"

instructions.interest.value

string

Valor dos juros

Example:

"12"

pdfUrl

string<uri>

URL para download do PDF do boleto

Example:

"https://s3.us-east-1.amazonaws.com/dev..."

payer

object

Dados do pagador

Mostrar atributos filhos

payer.city

string

Cidade

Example:

"SAO PAULO"

payer.name

string

Nome do pagador

Example:

"JULIANO PEREIRA SILVA"

payer.document

string

Documento do pagador

Example:

"12345678901"

payer.neighborhood

string

Bairro

Example:

"PONTE GRANDE"

payer.number

string

Número do endereço

Example:

"2500"

payer.postalCode

string

CEP

Example:

"03367010"

payer.publicArea

string

Logradouro

Example:

"AV. RIO DAS PEDRAS"

payer.state

string

Estado

Example:

"SP"

Visão Geral

Fluxo de Integração

Emissão de Boletos

Pagamento de Boletos

Gestão

Webhooks

Visão Geral

Parâmetros da URL

Exemplo de Requisição

Exemplo de Resposta

Status do Boleto

Estados Possíveis

Implementação Frontend

Verificar Status Automaticamente

Exibir Dados do Boleto

Funções de Utilidade

Casos de Uso

Dashboard Administrativo

Reconciliação Financeira

Próximos Passos

Gerar PDF

Cancelar Boleto

Webhooks

Relatórios

Authorizations

Path Parameters

Response

Visão Geral

Fluxo de Integração

Emissão de Boletos

Pagamento de Boletos

Gestão

Webhooks

​Visão Geral

​Parâmetros da URL

​Exemplo de Requisição

​Exemplo de Resposta

​Status do Boleto

​Estados Possíveis

​Implementação Frontend

​Verificar Status Automaticamente

​Exibir Dados do Boleto

​Funções de Utilidade

​Casos de Uso

​Dashboard Administrativo

​Reconciliação Financeira

​Próximos Passos

Gerar PDF

Cancelar Boleto

Webhooks

Relatórios

Authorizations

Path Parameters

Response

Visão Geral

Parâmetros da URL

Exemplo de Requisição

Exemplo de Resposta

Status do Boleto

Estados Possíveis

Implementação Frontend

Verificar Status Automaticamente

Exibir Dados do Boleto

Funções de Utilidade

Casos de Uso

Dashboard Administrativo

Reconciliação Financeira

Próximos Passos