> ## Documentation Index
> Fetch the complete documentation index at: https://docs.alphagateway.com.br/llms.txt
> Use this file to discover all available pages before exploring further.

# Boletos

> Emissão, vencimento, juros e multa.

Emita boletos bancários registrados para seus clientes. O boleto é gerado com código de barras, linha digitável e QR Code (PIX do boleto), pronto para pagamento em qualquer banco.

> Multa, juros e desconto são aplicados automaticamente conforme a configuração da sua organização no painel.

## Como funciona

1. **Emita o boleto** — Informe o valor, os dados do pagador (incluindo endereço) e, opcionalmente, a data de vencimento. A resposta já retorna `barcode`, `linhaDigitavel`, `qrcode` e `dueDate`
2. **Apresente ao cliente** — Compartilhe a linha digitável / QR Code, ou baixe o PDF do boleto pelo endpoint de segunda via
3. **Teste em homologação** — No ambiente de testes, use o endpoint de efetivar pagamento para confirmar o boleto manualmente
4. **Receba a confirmação** — Cadastre um endpoint de webhook assinando os eventos `boleto.paid`, `boleto.canceled` e `boleto.refunded` para receber notificações automáticas de mudança de status
5. **Consulte ou cancele quando precisar** — Verifique o status a qualquer momento, ou cancele (dê baixa) em um boleto ainda não pago

> O endpoint de emissão exige que o escopo `BOLETO` esteja liberado na API Key. A emissão e o cancelamento só funcionam com as transações habilitadas para a organização.

## Data de vencimento e expiração

* `dueDate` (opcional) — Data de vencimento do boleto no formato `YYYY-MM-DD`. Se omitida, é aplicado o vencimento padrão da organização.
* `expirationDate` (opcional) — Data limite para pagamento após o vencimento, no formato `YYYY-MM-DD`.
* `boletoType` (opcional) — Tipo do boleto: `OTHER` (padrão) ou `PROPOSAL`.

## Status do Boleto

| Status | Descrição |
| - | - |
| `CREATED` | Boleto registrado, aguardando pagamento |
| `PROCESSING` | Pagamento em processamento pelo banco |
| `PAID` | Pagamento confirmado |
| `CANCELED` | Boleto cancelado / baixado antes do pagamento |
| `REFUNDED` | Pagamento estornado após ter sido pago |

## Webhook de Boleto

Quando o status de um boleto muda, você recebe uma notificação nos endpoints que assinam os eventos `boleto.paid`, `boleto.canceled` e `boleto.refunded`.

**Exemplo de payload:**

```json theme={null}
{
  "event": "BOLETO_UPDATE",
  "method": "BOLETO",
  "status": "PAID",
  "transactionId": "01961234-abcd-7000-8000-000000000010",
  "idempotency": "boleto-12345",
  "value": 150.00,
  "valueFee": 3.50,
  "valueLiquid": 146.50,
  "boleto": {
    "barcode": "34191790010104351004791020150008998770000015000",
    "linhaDigitavel": "34191.79001 01043.510047 91020.150008 9 98770000015000",
    "qrcode": "00020126580014br.gov.bcb.pix...",
    "dueDate": "2025-04-10",
    "payment": {
      "paidValue": 150.00,
      "paidAt": "2025-04-08T13:20:00.000Z",
      "receiptUrl": "https://.../comprovante.pdf"
    }
  },
  "payer": {
    "fullName": "João da Silva",
    "document": "12345678900"
  }
}
```

> A URL do endpoint deve ser publicamente acessível (HTTPS recomendado) e retornar HTTP 200 para confirmar o recebimento. Veja [Configurar webhooks](https://docs.alphagateway.com.br/webhooks/configurar.md) para detalhes de eventos e validação da assinatura HMAC.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.