Boletos bancários (bank billets)

Boletos bancários representam o registro do boleto no banco associado a uma cobrança. Uma cobrança (billing) pode ter vários boletos ao longo do tempo (re-emissões, mudança de banco, etc.); a API expõe todos.

Os endpoints são somente leitura e sempre aninhados sob uma cobrança da conta autenticada.

Veja conventions.md para paginação, autenticação, erros, rate limit e isolamento entre contas.

Modelo

Status

Valor	Significado
`issued`	Boleto emitido localmente, ainda não enviado ao banco
`pending_remittance`	Pronto para ser remetido ao banco
`remitting`	Remessa em andamento
`remittanced`	Remessa entregue ao banco, aguardando confirmação
`opened`	Registrado no banco, aguardando pagamento
`rejected`	Banco recusou o registro (ver `bank_rejection` para a mensagem)
`paid`	Pago via banco
`discharged`	Baixado
`canceled`	Cancelado
`protested`	Em protesto

Campos retornados

Campo	Tipo	Observações
`id`	int
`status`	string	Ver tabela acima
`bank_symbol`	string	Símbolo do banco (`bb`, `afpay`, `pagseguro`, etc.)
`amount`	decimal	Valor original do boleto
`due_date`	date	Vencimento
`barcode`	string \| null	Código de barras (44 dígitos)
`digitable_line`	string \| null	Linha digitável formatada
`pix_qr_code`	string \| null	EMV BR Code para pagamento via Pix (quando suportado pelo banco)
`our_number`	string \| null	"Nosso número" atribuído pelo banco
`our_sequential_number`	int	Sequencial interno por (conta, convênio)
`uuid`	string \| null	Identificador único do boleto
`agreement_code`, `bank_billet_account`	string \| null	Códigos do convênio bancário
`agency_number`, `agency_digit`	string	Agência do beneficiário
`account_number`, `account_digit`	string	Conta corrente do beneficiário
`recipient_full_name`, `recipient_document`, `recipient_full_address`	string	Beneficiário (sua conta) — congelado no momento da emissão
`payer_full_name`, `payer_document`	string	Pagador (contato) — congelado no momento da emissão
`payer_address_postal_code`, `payer_address_street`, `payer_address_district`, `payer_address_city`, `payer_address_state`	string	Endereço do pagador — congelado no momento da emissão
`paid_amount`	decimal	Valor efetivamente pago
`paid_at`	date \| null	Data do pagamento
`net_amount`	decimal	Valor líquido (já descontadas tarifas)
`discount`	decimal	Desconto aplicado pelo banco
`interest`	decimal	Juros aplicados
`bank_rate`	decimal	Tarifa do banco
`credit_at`	date \| null	Data prevista de crédito
`discharged_at`	date \| null	Data da baixa
`remittanced_at`	date \| null	Data da entrega da remessa
`provider_id`	string \| null	ID do boleto no provedor externo (AFPAY, etc.)
`provider_status`	string \| null	Status reportado pelo provedor externo
`bank_rejection`	string \| null	Mensagem de rejeição do banco (presente quando `status="rejected"`)
`days_overdue`	int	Dias em atraso (negativo se ainda não venceu)
`overdue`	boolean	`true` se `days_overdue > 0` e o status ainda permite cobrar
`editable`	boolean	`true` se o boleto pode ser alterado (`issued`, `pending_remittance` ou `rejected`)
`created_at`, `updated_at`	ISO-8601

Os campos recipient_* e payer_* são snapshots do momento da emissão. Atualizar o contato não propaga para boletos já emitidos.

Endpoints

GET`/v1/billings/:billing_id/bank_billets`

Lista todos os boletos da cobrança, ordenados por id DESC (mais recente primeiro).

Exemplo cURL:

curl -X GET 'https://api.sacador.com.br/v1/billings/5001/bank_billets?page=1&per_page=25' \
  -H 'Authorization: Bearer sct_seu_token_aqui'

Resposta 200 OK:

{
  "bank_billets": [
    {
      "id": 9001,
      "status": "opened",
      "bank_symbol": "bb",
      "amount": "150.00",
      "due_date": "2026-06-10",
      "barcode": "00190000000000010000000000000000000000000000",
      "digitable_line": "00190.00009 00000.000009 00000.000009 0 00000000000000",
      "pix_qr_code": null,
      "our_number": "1234567",
      "our_sequential_number": 42,
      "uuid": null,
      "agreement_code": "1234567",
      "bank_billet_account": null,
      "agency_number": "1234",
      "agency_digit": "5",
      "account_number": "123456",
      "account_digit": "7",
      "recipient_full_name": "Empresa Exemplo Ltda",
      "recipient_document": "12345678000190",
      "recipient_full_address": "Av. Paulista, 1000 - Bela Vista - SP",
      "payer_full_name": "Maria Silva",
      "payer_document": "12345678901",
      "payer_address_postal_code": "01310-100",
      "payer_address_street": "Avenida Paulista",
      "payer_address_district": "Bela Vista",
      "payer_address_city": "São Paulo",
      "payer_address_state": "SP",
      "paid_amount": "0.0",
      "paid_at": null,
      "net_amount": "0.0",
      "discount": "0.0",
      "interest": "0.0",
      "bank_rate": "0.0",
      "credit_at": null,
      "discharged_at": null,
      "remittanced_at": "2026-05-11",
      "provider_id": null,
      "provider_status": null,
      "bank_rejection": null,
      "days_overdue": -30,
      "overdue": false,
      "editable": false,
      "created_at": "2026-05-11T10:00:00.000Z",
      "updated_at": "2026-05-11T10:05:00.000Z"
    }
  ]
}

Headers X-Total-Count, X-Page, X-Per-Page, X-Total-Pages conforme conventions.md.

Erros: - 404 — billing_id inexistente ou pertencente a outra conta.

GET`/v1/billings/:billing_id/bank_billets/:id`

Retorna um boleto específico.

Exemplo cURL:

curl -X GET 'https://api.sacador.com.br/v1/billings/5001/bank_billets/9001' \
  -H 'Authorization: Bearer sct_seu_token_aqui'

Resposta 200 OK: objeto idêntico ao item da listagem.

Erros: - 404 — o boleto não existe, pertence a outra cobrança da mesma conta, ou a cobrança/boleto pertence a outra conta.

Como aparece dentro de GET`/v1/billings/:id`

Para evitar uma chamada extra quando você já está consultando a cobrança, o GET/v1/billings/:id (assim como as respostas de POST, PATCH/v1/billings/:id e dos endpoints cancel/pay_off) já embute os boletos no campo bank_billets, com o mesmo formato dos endpoints acima.

{
  "id": 123,
  "code": "ABC123",
  "...": "...",
  "bank_billets": [
    { "id": 9001, "status": "opened", "...": "..." }
  ]
}

O GET/v1/billings (listagem) não inclui bank_billets — para evitar payloads pesados em consultas de muitos registros, use o endpoint dedicado quando precisar dos boletos durante uma listagem.