API de Gerenciamento de Boleto

Um boleto é o comprovante de pagamento emitido por bancos no Brasil: você registra uma cobrança com um banco, o banco retorna um código de barras e uma linha digitável, e seu pagador o quita em qualquer banco, caixa eletrônico ou aplicativo. Registrar um normalmente significa integrar-se com cada banco separadamente — diferentes autenticações, diferentes nomes de campos, diferentes noções de como um boleto "pago" se parece.

A API de Gerenciamento de Boletos é uma interface uniforme sobre todos eles. Você registra uma cobrança uma vez, em uma forma, e nós a traduzimos para a instituição com a qual seu cliente tem conta.

BETA

Esta API está em BETA. Inter Empresas está disponível hoje; veja Instituições suportadas para o que está ativo e o que está por vir.

Como tudo se encaixa #

Dois objetos. Uma Conexão de Boleto contém as credenciais que nos permitem agir em uma instituição em nome do seu cliente, e é criada uma vez. Cada Boleto é então emitido contra essa conexão.

Você pode criar uma conexão a partir de um Item existente — o mesmo objeto que você já usa para dados — ou enviando credenciais diretamenteAPI quando não há Item para reutilizar.

O ciclo de vida de um boleto #

Um boleto começa ABERTO e se move em uma direção. PAGO e CANCELADO são terminais: nada sai deles, e um boleto nunca retorna a ABERTO.

Status	O que significa
`ABERTO`	Registrado no banco e pagável.
`PAGO`	Quitado. `amountPaid` e `paymentOrigin` estão preenchidos.
`VENCIDO`	Atrasado e ainda pagável — a maioria dos bancos aceita pagamento atrasado.
`CANCELADO`	Retirado por você. Não pode mais ser pago.
`PROTESTADO`	Enviado para protesto após não ser pago. Ainda pode ser quitado.

Pagamentos parciais

amountPaid é o que o pagador realmente pagou, e pode diferir de amount — um pagador pode quitar um boleto com desconto, ou com multa e juros aplicados após a data de vencimento. Sempre concilie contra amountPaid, nunca contra o valor que você solicitou.

O fluxo de ponta a ponta #

Emitir um boleto é uma única chamada. Saber que ele foi pago é um webhook — você não faz polling.

O webhook informa que algo mudou, não o que. Ele carrega o id do boleto, e você busca o boleto para ver seu novo estado. Isso mantém a notificação pequena e significa que um webhook que você recebe duas vezes é inofensivo.

Começando #

Obter uma chave de API

Chame POST /authAPI com as credenciais do seu aplicativo.

{
  "clientId": "{YOUR-CLIENT-ID}",
  "clientSecret": "{YOUR-CLIENT-SECRET}"
}

Criar uma Conexão de Boleto

A partir de um Item existente, com POST /boleto-connections/from-itemAPI:

{
  "itemId": "{YOUR-ITEM-ID}"
}

A resposta traz o id contra o qual você emitirá:

{
  "id": "dc3537ad-13b4-4770-b248-e4578983899c",
  "connectorId": 225,
  "createdAt": "2023-01-01T00:00:00.000Z",
  "updatedAt": "2023-01-01T00:00:00.000Z"
}

Emitir um boleto

POST /boletosAPI. amount está em reais, dueDate é YYYY-MM-DD:

{
  "boletoConnectionId": "{YOUR-BOLETO-CONNECTION-ID}",
  "boleto": {
    "seuNumero": "1234567891",
    "amount": 2.5,
    "dueDate": "2025-03-01",
    "payer": {
      "taxNumber": "1234567890",
      "name": "Nome de exemplo",
      "addressState": "SP",
      "addressZipCode": "01239030",
      "addressCity": "Não informado",
      "addressStreet": "Não informado"
    }
  }
}

seuNumero é sua referência para a cobrança — um número de fatura, um id de pedido. Ele retorna em cada leitura e na notificação de quitação, então use algo que você possa conciliar.

Entregar ao seu pagador

A resposta inclui tudo que um pagador precisa:

{
  "id": "158b9f04-acf0-4a9b-8f0c-a87feb9f19b3",
  "boletoConnectionId": "91d4d8d8-8477-423e-9888-0bbbde2da64a",
  "amount": 2.5,
  "status": "ABERTO",
  "seuNumero": "1234567891",
  "dueDate": "2025-03-01",
  "pixQr": "00020126490014br.gov.bcb.pix0108dict-key...",
  "digitableLine": "01120001161117012359902128847071234570777000110",
  "nossoNumero": "10000004701",
  "barcode": "01120001161117012359902128847071234570",
  "amountPaid": null,
  "paymentOrigin": null
}

digitableLine é o número de 47 dígitos que um pagador digita em seu aplicativo bancário, barcode é o que um scanner lê, e pixQr é um payload PIX para a mesma cobrança — a maioria dos bancos agora emite boletos pagáveis de qualquer forma.

Escutar pelo pagamento

Inscreva-se em boleto/atualizado em webhooks e você receberá:

{
  "boletoId": "158b9f04-acf0-4a9b-8f0c-a87feb9f19b3",
  "eventId": "71e0b4db-4e8c-401d-8ad8-5ab3ecd1f3d0",
  "event": "boleto/updated"
}

Então GET /boletos/API. Um boleto quitado lê:

{
  "id": "158b9f04-acf0-4a9b-8f0c-a87feb9f19b3",
  "status": "PAGO",
  "amount": 2.5,
  "amountPaid": 2.5,
  "paymentOrigin": "PIX",
  "seuNumero": "1234567891"
}

Você pode retirar um boleto não pago a qualquer momento com POST /boletos//cancelAPI.

Instituições suportadas #

Inter Empresas está disponível hoje; Bradesco e o conector Sandbox estão sendo construídos. Quais instituições estão ativas, como cada uma autoriza uma conexão e os comportamentos que vale a pena conhecer por banco estão todos em um só lugar: Cobertura.

Antes de você entrar em produção #

Concilie em amountPaid, não em amount. Multas, juros e descontos significam que eles diferem.
Trate webhooks como pelo menos uma vez. O mesmo boletoId pode chegar duas vezes; eventId identifica a entrega se você quiser deduplicar.
Armazene seuNumero do seu lado. É sua única ligação entre um boleto e o que quer que ele esteja pagando.
Não analise nossoNumero para significado. Seu formato é do banco e difere entre instituições.

Como tudo se encaixa#

O ciclo de vida de um boleto#

O fluxo de ponta a ponta#

Começando#