Numeração de Boletos (NIB)

Numeração de Boletos

O Número Identificador Bancário (NIB), definido pelo banco como “Nosso Número”, é o identificador único de cada boleto dentro de uma conta/carteira bancária. Este número é essencial para o registro e controle do boleto no sistema bancário.

A API oferece dois métodos para definir o NIB:

Método 1 - Número Sequencial

Campo: boleto.sequencial (integer)

Forneça números sequenciais únicos (1, 2, 3, etc.) para gerar o Número Identificador Bancário (NIB). A API trata o formato e as regras de validação.

-d boleto.sequencial="1"

Vantagens

• Mais simples de implementar
• API calcula automaticamente o dígito verificador
• Não precisa conhecer as regras específicas do banco

Exemplo

curl -v "https://sandbox.boletocloud.com/api/v1/boletos" \
  -X "POST" \
  -u "api-key_TOKEN:token" \
  -d boleto.sequencial="12345" \
  # ... outros parâmetros

Método 2 - NIB Direto

Campo: boleto.numero (string)

Forneça o NIB pré-gerado já formatado conforme os requisitos do banco.

-d boleto.numero="00123456789-4"

Vantagens

• Controle total sobre a numeração
• Permite integração com sistemas de numeração existentes

Requisitos

• Deve seguir o formato específico do banco
• Deve incluir o dígito verificador correto
• Deve ser único para a conta/carteira

Exemplo

curl -v "https://sandbox.boletocloud.com/api/v1/boletos" \
  -X "POST" \
  -u "api-key_TOKEN:token" \
  -d boleto.numero="00123456789-4" \
  # ... outros parâmetros

Comparação dos Métodos

Aspecto	Sequencial	NIB Direto
Complexidade	Baixa	Alta
Controle	API	Desenvolvedor
Dígito Verificador	Automático	Manual
Formato	Automático	Manual

Atenção

Você deve usar apenas um dos métodos por requisição. Não informe ambos boleto.sequencial e boleto.numero na mesma requisição.

---

Numeração Automática

Os campos boleto.numero e boleto.sequencial são opcionais. Quando não informados, o comportamento depende do tipo de carteira da conta bancária:

Tipo de Carteira	Comportamento
Cliente numera	O Boleto Cloud gera automaticamente o NIB (Nosso Número) e envia ao banco
Banco numera	O campo é enviado vazio e o NIB é atribuído pelo banco na resposta do registro

Recomendação

Na maioria dos casos, você pode simplesmente omitir esses campos e deixar a numeração ser gerenciada automaticamente. Isso simplifica a integração e evita conflitos de numeração.

Nota

Se estiver usando a nova forma de geração de boletos com token da conta, a numeração é controlada automaticamente pela conta e você não precisa informar nenhum dos dois campos.