Evitar Boletos Duplicados

Como Evitar Boletos Duplicados

Em sistemas de produção, problemas de rede, timeouts ou retentativas podem causar a criação de boletos duplicados. O Boleto Cloud oferece um mecanismo de idempotência para evitar esse problema.

O Problema

┌─────────────────────────────────────────────────────────────┐
│  Cenário sem idempotência:                                  │
│                                                             │
│  1. Sistema envia requisição para criar boleto              │
│  2. Boleto é criado com sucesso                             │
│  3. Timeout na resposta (rede lenta)                        │
│  4. Sistema não recebe confirmação                          │
│  5. Sistema reenvia a requisição                            │
│  6. NOVO boleto é criado (DUPLICADO!)                       │
│                                                             │
└─────────────────────────────────────────────────────────────┘

A Solução: Token de Controle

Use o campo boleto.tokenControleUsuario com um valor único para cada boleto. Se a requisição for reenviada com o mesmo token, o Boleto Cloud retorna o boleto existente ao invés de criar um novo.

┌─────────────────────────────────────────────────────────────┐
│  Cenário com idempotência:                                  │
│                                                             │
│  1. Sistema envia requisição com tokenControleUsuario=ABC   │
│  2. Boleto é criado com sucesso                             │
│  3. Timeout na resposta (rede lenta)                        │
│  4. Sistema não recebe confirmação                          │
│  5. Sistema reenvia com MESMO tokenControleUsuario=ABC      │
│  6. API detecta duplicidade e retorna boleto existente      │
│                                                             │
└─────────────────────────────────────────────────────────────┘

Exemplo de Requisição

cURL

curl -X POST "https://sandbox.boletocloud.com/api/v1/boletos" \
  -u "api-key_SUA-API-KEY:token" \
  -d "boleto.conta.token=TOKEN_DA_CONTA" \
  -d "boleto.tokenControleUsuario=pedido-12345-parcela-1" \
  -d "boleto.emissao=2024-01-15" \
  -d "boleto.vencimento=2024-01-30" \
  -d "boleto.documento=PED-12345" \
  -d "boleto.titulo=DM" \
  -d "boleto.valor=299.90" \
  -d "boleto.pagador.nome=Marcos Silva" \
  -d "boleto.pagador.cprf=000.000.000-00" \
  -d "boleto.pagador.endereco.cep=00000-000" \
  -d "boleto.pagador.endereco.uf=SP" \
  -d "boleto.pagador.endereco.localidade=São Paulo" \
  -d "boleto.pagador.endereco.bairro=Vila Mariana" \
  -d "boleto.pagador.endereco.logradouro=Rua Domingos de Morais" \
  -d "boleto.pagador.endereco.numero=500" \
  -o boleto.pdf

Java

Response response = ClientBuilder.newClient()
    .target("https://sandbox.boletocloud.com/api/v1/boletos")
    .register(HttpAuthenticationFeature.basic("api-key_SUA-API-KEY", "token"))
    .request(WILDCARD)
    .post(Entity.form(new Form()
        .param("boleto.conta.token", "TOKEN_DA_CONTA")
        .param("boleto.tokenControleUsuario", "pedido-12345-parcela-1")
        .param("boleto.emissao", "2024-01-15")
        .param("boleto.vencimento", "2024-01-30")
        .param("boleto.documento", "PED-12345")
        .param("boleto.titulo", "DM")
        .param("boleto.valor", "299.90")
        .param("boleto.pagador.nome", "Marcos Silva")
        .param("boleto.pagador.cprf", "000.000.000-00")
        .param("boleto.pagador.endereco.cep", "00000-000")
        .param("boleto.pagador.endereco.uf", "SP")
        .param("boleto.pagador.endereco.localidade", "São Paulo")
        .param("boleto.pagador.endereco.bairro", "Vila Mariana")
        .param("boleto.pagador.endereco.logradouro", "Rua Domingos de Morais")
        .param("boleto.pagador.endereco.numero", "500")));

Python

import requests
from requests.auth import HTTPBasicAuth

response = requests.post(
    'https://sandbox.boletocloud.com/api/v1/boletos',
    auth=HTTPBasicAuth('api-key_SUA-API-KEY', 'token'),
    data={
        'boleto.conta.token': 'TOKEN_DA_CONTA',
        'boleto.tokenControleUsuario': 'pedido-12345-parcela-1',
        'boleto.emissao': '2024-01-15',
        'boleto.vencimento': '2024-01-30',
        'boleto.documento': 'PED-12345',
        'boleto.titulo': 'DM',
        'boleto.valor': '299.90',
        'boleto.pagador.nome': 'Marcos Silva',
        'boleto.pagador.cprf': '000.000.000-00',
        'boleto.pagador.endereco.cep': '00000-000',
        'boleto.pagador.endereco.uf': 'SP',
        'boleto.pagador.endereco.localidade': 'São Paulo',
        'boleto.pagador.endereco.bairro': 'Vila Mariana',
        'boleto.pagador.endereco.logradouro': 'Rua Domingos de Morais',
        'boleto.pagador.endereco.numero': '500'
    }
)

if response.status_code in [200, 201]:
    with open('boleto.pdf', 'wb') as f:
        f.write(response.content)

Boas Práticas para o Token

Prática	Exemplo
Usar ID do pedido	pedido-12345
Incluir parcela	pedido-12345-parcela-1
Usar UUID	550e8400-e29b-41d4-a716-446655440000
Combinar dados	cliente-789-fatura-2024-01

Comportamento da API

Cenário	Status HTTP	Comportamento
Primeira requisição	201 Created	Boleto criado normalmente
Requisição duplicada	200 OK	Retorna o boleto existente

Identificando Duplicidade

Quando a API retorna 200 OK ao invés de 201 Created, significa que o boleto já existia e foi retornado. Isso permite que seu sistema saiba se está recebendo um boleto novo ou existente.

Token Único

O token de controle deve ser único por conta bancária. Dois boletos com o mesmo token são considerados duplicados, mesmo que tenham dados diferentes.

Veja Também

• Idempotência - Documentação completa sobre idempotência
• Criar Boleto - Referência completa de criação de boletos
• Status & Erros - Códigos de status HTTP da API
• Campos do Boleto - Todos os campos disponíveis