# 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.

<Callout variant="warning" title="BETA">
Esta API está em BETA. Inter Empresas está disponível hoje; veja [Instituições suportadas](#supported-institutions) para o que está ativo e o que está por vir.
</Callout>

## 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.

```mermaid
graph LR
  subgraph Uma vez por cliente
    A[Item<br/>conta bancária conectada] --> B[Conexão de Boleto]
    A2[Credenciais brutas] --> B
  end
  subgraph Muitas vezes
    B --> C[Boleto #1]
    B --> D[Boleto #2]
    B --> E[Boleto #3]
  end
```

Você pode criar uma conexão a partir de um [Item](/docs/connect-widget/introduction) existente — o mesmo objeto que você já usa para dados — ou enviando [credenciais diretamente](/reference/boleto-connection-create) 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`.

```mermaid
stateDiagram-v2
  [*] --> ABERTO: criado
  ABERTO --> PAGO: pagador quita
  ABERTO --> VENCIDO: data de vencimento passa
  ABERTO --> CANCELADO: você cancela
  VENCIDO --> PAGO: pago atrasado
  VENCIDO --> PROTESTADO: enviado para protesto
  VENCIDO --> CANCELADO: você cancela
  PROTESTADO --> PAGO: quitado após protesto
  PROTESTADO --> CANCELADO: você cancela
  PAGO --> [*]
  CANCELADO --> [*]
```

| 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. |

<Callout variant="info" title="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.
</Callout>

## O fluxo de ponta a ponta

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

```mermaid
sequenceDiagram
  autonumber
  participant Você as Seu sistema
  participant Pluggy
  participant Banco
  actor Pagador

  Você->>Pluggy: POST /boletos
  Pluggy->>Banco: registrar a cobrança
  Banco-->>Pluggy: nossoNumero, código de barras, linha digitável
  Pluggy-->>Você: 201 { id, status: ABERTO, ... }

  Note over Você,Pagador: você entrega o boleto como preferir

  Pagador->>Banco: paga o boleto
  Banco->>Pluggy: notificação de quitação
  Pluggy->>Você: webhook boleto/atualizado
  Você->>Pluggy: GET /boletos/{id}
  Pluggy-->>Você: { status: PAGO, amountPaid, paymentOrigin }
```

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

<StepList>
<Step title="Obter uma chave de API">
Chame [POST /auth](/reference/auth-create) com as credenciais do seu aplicativo.

```json
{
  "clientId": "{YOUR-CLIENT-ID}",
  "clientSecret": "{YOUR-CLIENT-SECRET}"
}
```
</Step>

<Step title="Criar uma Conexão de Boleto">
A partir de um Item existente, com [POST /boleto-connections/from-item](/reference/boleto-connection-create-from-item):

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

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

```json
{
  "id": "dc3537ad-13b4-4770-b248-e4578983899c",
  "connectorId": 225,
  "createdAt": "2023-01-01T00:00:00.000Z",
  "updatedAt": "2023-01-01T00:00:00.000Z"
}
```
</Step>

<Step title="Emitir um boleto">
[POST /boletos](/reference/boleto-create). `amount` está em reais, `dueDate` é `YYYY-MM-DD`:

```json
{
  "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.
</Step>

<Step title="Entregar ao seu pagador">
A resposta inclui tudo que um pagador precisa:

```json
{
  "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.
</Step>

<Step title="Escutar pelo pagamento">
Inscreva-se em `boleto/atualizado` em [webhooks](/docs/developer-tools/webhooks-ref) e você receberá:

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

Então [GET /boletos/{id}](/reference/boleto-get). Um boleto quitado lê:

```json
{
  "id": "158b9f04-acf0-4a9b-8f0c-a87feb9f19b3",
  "status": "PAGO",
  "amount": 2.5,
  "amountPaid": 2.5,
  "paymentOrigin": "PIX",
  "seuNumero": "1234567891"
}
```
</Step>
</StepList>

Você pode retirar um boleto não pago a qualquer momento com [POST /boletos/{id}/cancel](/reference/boleto-cancel).

## 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](/docs/boleto/coverage).

## 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.