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

# Boleto

> Gere boletos de forma instantânea

O **Boleto** permite que você gere cobranças através de boletos bancários registrados. Ideal para clientes que não utilizam PIX, pagamentos programados, recorrências simples ou cobranças com vencimento futuro.

O boleto pode ser pago em bancos, lotéricas ou internet banking até a data de vencimento.

## 🚀 Como Funciona

O Boleto funciona através da criação de um título de cobrança vinculado ao CPF ou CNPJ do pagador. Após a geração, um boleto bancário é criado e disponibilizado em formato PDF e linha digitável para pagamento.

<CardGroup cols={2}>
  <Card title="📱 Boleto emitido" color="#ff7e00" icon="qrcode">
    Você gera um boleto com valor específico através da API
  </Card>

  <Card title="💳 Cliente Paga" color="#ff7e00" icon="credit-card">
    Cliente escaneia o codigo de barras apresentando no PDF utilizando o app do banco
  </Card>

  <Card title="⚡ Confirmação em instantes" color="#ff7e00" icon="bolt">
    Você recebe confirmação por email assim que o pagamento for validado
  </Card>

  <Card title="💰 Valor Disponível" color="#ff7e00" icon="money-bill">
    Valor fica disponível imediatamente em sua conta
  </Card>
</CardGroup>

## 🛠️ Implementação Rápida

### 1. Gerar boleto

## ⚠️ Validação do valor total da transação

O campo `amountInCents` enviado fora do array `items` representa o **valor total da cobrança**.

Para que a requisição seja aceita, esse valor **deve ser exatamente igual** à soma do valor de cada item multiplicado por sua respectiva quantidade.

Em outras palavras:

> O total da transação precisa corresponder ao somatório de `amountInCents × quantity` de todos os itens informados.

```bash theme={null}
curl -X POST 'https://api.avanttifinance.com/v1/boleto' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <seu_token>' \
  -d '{
  "amountInCents": 10000,
  "description": "Descrição opcional",
  "postbackUrl": "https://seu-dominio.com/webhook",
  "customer": {
    "name": "Nome do Cliente",
    "email": "cliente@email.com",
    "documentType": "cpf",
    "document": "12345678909",
    "phone": "+5511999999999"
  },
  "items": [
    {
      "title": "Produto",
      "tangible": true,
      "quantity": 1,
      "amountInCents": 10000
    }
  ],
  "seller": {
    "name": "Vendedor",
    "documentType": "cpf",
    "document": "12345678909"
  }
}'
```

### 2. Resposta com QR Code

```json theme={null}
{
  "success": true,
  "message": "Transação criada com sucesso",
  "data": {
    "id": "uuid-da-transacao",
    "boleto": {
      "url": "https://...",
      "barcode": "...",
      "digitableLine": "...",
      "dueAt": "2025-02-25T..."
    },
    "status": "pending",
    "fees": 0
  }
```

## 📊 Parâmetros Detalhados

### Campos Obrigatórios

| Campo                     | Tipo     | Descrição                                    |
| ------------------------- | -------- | -------------------------------------------- |
| `amountInCents`           | `number` | Valor em centavos (ex: 10000 = R\$ 100,00)   |
| `customer`                | `object` | Dados do cliente pagador                     |
| `customer.name`           | `string` | Nome completo do cliente                     |
| `customer.email`          | `string` | Email do cliente                             |
| `customer.documentType`   | `string` | Tipo do documento (`cpf` ou `cnpj`)          |
| `customer.phone`          | `string` | Telefone do cliente                          |
| `customer.billingAddress` | `object` | Endereço de cobrança                         |
| `customer.document`       | `string` | Número do documento (apenas números)         |
| `items`                   | `array`  | Lista de itens da compra                     |
| `description`             | `string` | Descrição da transação (máx. 140 caracteres) |

### Campos Opcionais

| Campo         | Tipo     | Descrição                                    |
| ------------- | -------- | -------------------------------------------- |
| `postbackUrl` | `string` | URL específica para webhooks desta transação |
| `seller`      | `object` | informações sobre vendedor                   |

### Exemplo Completo

```json theme={null}
{
  "amountInCents": 10000,
  "description": "Descrição opcional",
  "postbackUrl": "https://seu-dominio.com/webhook",
  "customer": {
    "name": "Nome do Cliente",
    "email": "cliente@email.com",
    "documentType": "cpf",
    "document": "12345678909",
    "phone": "+5511999999999"
  },
  "items": [
    {
      "title": "Produto",
      "tangible": true,
      "quantity": 1,
      "amountInCents": 10000
    }
  ],
  "seller": {
    "name": "Vendedor",
    "documentType": "cpf",
    "document": "12345678909"
  }
}
```

## 📡 Recebendo Confirmações

### Via Webhook

Configure um webhook para receber confirmações automáticas:

```json theme={null}
{
  "id": "uuid-do-dispatch",
  "type": "transaction",
  "event": "transaction_paid",
  "scope": "postback",
  "transaction": {
    "id": "cuid_da_transacao",
    "amount": 10000,
    "status": "paid",
    "pix": null
  }
}
```

## 📋 Status das Transações

| Status     | Descrição            | Próximo Passo                    |
| ---------- | -------------------- | -------------------------------- |
| `pending`  | Aguardando pagamento | Mostrar QR Code para cliente     |
| `paid`     | Pago com sucesso     | Liberar produto/serviço          |
| `canceled` | Cancelado            | Gerar novo QR Code se necessário |
| `refunded` | Estornado            | Valor devolvido ao pagador       |

## 🛡️ Boas Práticas

### Segurança

<AccordionGroup>
  <Accordion title="🔒 Validação de Dados" icon="shield-check">
    * Sempre valide CPF/CNPJ antes de enviar
    * Sanitize dados de entrada
    * Verifique valores mínimos e máximos
    * Use HTTPS obrigatoriamente
  </Accordion>

  <Accordion title="🔄 Idempotência" icon="arrows-rotate">
    * Use IDs únicos para cada transação
    * Implemente verificação de duplicatas
    * Mantenha referências internas
    * Trate reenvios de webhook adequadamente
  </Accordion>

  <Accordion title="📊 Monitoramento" icon="chart-line">
    * Monitore taxa de conversão
    * Acompanhe tempos de pagamento
    * Verifique abandono de carrinho
    * Alerte sobre falhas de webhook
  </Accordion>
</AccordionGroup>

### Performance

* **Timeout**: Configure timeouts adequados para requisições
* **Retry**: Implemente retry para chamadas falhadas
* **Batch**: Agrupe operações quando possível

***

## 🎯 Próximos Passos

<CardGroup cols={2}>
  <Card title="📝 Criar QR Code" color="#ff7e00" icon="plus" href="/pages/pix-in/create-qrcode">
    Guia detalhado para criar QR Codes PIX
  </Card>

  <Card title="🔗 Configurar Webhooks" color="#ff7e00" icon="webhook" href="/webhook">
    Configure notificações automáticas
  </Card>

  <Card title="🚀 PIX OUT" color="#ff7e00" icon="paper-plane" href="/pages/pix-out/overview">
    Aprenda a enviar transferências PIX
  </Card>

  <Card title="📊 Relatórios" color="#ff7e00" icon="chart-bar" href="/pages/reference/status-codes">
    Monitore suas transações
  </Card>
</CardGroup>