Skip to main content
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.

📱 Boleto emitido

Você gera um boleto com valor específico através da API

💳 Cliente Paga

Cliente escaneia o codigo de barras apresentando no PDF utilizando o app do banco

⚡ Confirmação em instantes

Você recebe confirmação por email assim que o pagamento for validado

💰 Valor Disponível

Valor fica disponível imediatamente em sua conta

​
🛠️ 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. 
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

{
  "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

CampoTipoDescrição
amountInCentsnumberValor em centavos (ex: 10000 = R$ 100,00)
customerobjectDados do cliente pagador
customer.namestringNome completo do cliente
customer.emailstringEmail do cliente
customer.documentTypestringTipo do documento (cpf ou cnpj)
customer.phonestringTelefone do cliente
customer.billingAddressobjectEndereço de cobrança
customer.documentstringNúmero do documento (apenas números)
itemsarrayLista de itens da compra
descriptionstringDescrição da transação (máx. 140 caracteres)

​
Campos Opcionais

CampoTipoDescrição
postbackUrlstringURL específica para webhooks desta transação
sellerobjectinformações sobre vendedor

​
Exemplo Completo

{
  "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: 
{
  "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

StatusDescriçãoPróximo Passo
pendingAguardando pagamentoMostrar QR Code para cliente
paidPago com sucessoLiberar produto/serviço
canceledCanceladoGerar novo QR Code se necessário
refundedEstornadoValor devolvido ao pagador

​
🛡️ Boas Práticas

​
Segurança

  • Sempre valide CPF/CNPJ antes de enviar
  • Sanitize dados de entrada
  • Verifique valores mínimos e máximos
  • Use HTTPS obrigatoriamente
  • Use IDs únicos para cada transação
  • Implemente verificação de duplicatas
  • Mantenha referências internas
  • Trate reenvios de webhook adequadamente
  • Monitore taxa de conversão
  • Acompanhe tempos de pagamento
  • Verifique abandono de carrinho
  • Alerte sobre falhas de webhook

​
Performance

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

​
🎯 Próximos Passos

📝 Criar QR Code

Guia detalhado para criar QR Codes PIX

🔗 Configurar Webhooks

Configure notificações automáticas

🚀 PIX OUT

Aprenda a enviar transferências PIX

📊 Relatórios

Monitore suas transações