Pular para conteúdo

Registrar boleto Banco do Brasil (API)

Tela do Telvora ERP — Registrar boleto Banco do Brasil (API)

Captura do Telvora ERP em ambiente autorizado. Valores de tabelas e formulários foram ocultados para privacidade.

Módulo: Financeiro
Menu: Financeiro → Contas a receber → (abrir título) → Registrar boleto BB
Público: Operador | Gestor financeiro
Status: Publicado
Atualizado: 2026-09-04
Refs técnicas: ADR-019 · 01-ARQUITETURA/65-banking-providers-api-cnab.md

O que faz

Registra um título em aberto diretamente na API de cobranças do Banco do Brasil e grava no sistema o nosso número, a linha digitável, código de barras e (quando houver) dados PIX do boleto.

Quem pode usar

  • Registrar boleto: finance.receivable.update
  • Configurar carteira: auxiliary.collection_wallet.update
  • Revelar credenciais na tela (olho): auxiliary.collection_wallet.secret.read

Pré-requisitos

  1. Conta bancária cadastrada com código do banco 001 (Banco do Brasil), agência/conta corretas.
  2. Carteira de cobrança vinculada a essa conta, com:
  3. Classe de integração = API bancária
  4. Número do convênio preenchido
  5. Carteira (ex.: 17), variação (ex.: 19), modalidade (ex.: 1)
  6. Tipo convênio (NN) = 4 — Cliente numera
  7. Perfil credencial API = Homologação ou Produção
  8. Credenciais API preenchidas na própria carteira (homolog e/ou produção): App Key, Client ID, Client Secret (Basic opcional)
  9. Título em status Aberto ou Parcial, com a carteira acima.

Atenção — convênio

Se o convênio informado já estiver em uso por outro sistema (ERP legado, CNAB paralelo etc.), o BB pode rejeitar ou gerar conflito de numeração. Prefira um convênio dedicado só para a API Telvora.

Passo a passo — credenciais na carteira

  1. Em Auxiliares → Carteiras de cobrança, abra a carteira BB.
  2. Aba Configurações bancárias.
  3. Em Credenciais API — Homologação e Produção, preencha App Key, Client ID e Client Secret (valores do portal Developers BB).
  4. Os campos aparecem mascarados (••••). Com a permissão de revelar segredos, use o olho para conferir o valor.
  5. Campo deixado em branco no Salvar mantém o que já estava gravado.
  6. Escolha Perfil credencial API (Homologação ou Produção) conforme o ambiente desejado.
  7. Salve a carteira.

Após liberar a permissão auxiliary.collection_wallet.secret.read no grupo do usuário, saia e entre de novo para o menu de permissões atualizar.

Passo a passo — registrar boleto

  1. Confirme a carteira (API + convênio + perfil + credenciais).
  2. Abra o título em Contas a receber.
  3. Clique em Registrar boleto BB.
  4. Confira na aba Informações o nosso número e a linha digitável.

Em homologação, o pagador usa CPF/CNPJ fictício exigido pelo BB (ex.: CPF 96050176876), independentemente do documento real do cliente.

Para produção, use o perfil Produção na carteira e o convênio real vinculado à aplicação no portal Developers BB (api.bb.com.br). Homologação (api.hm.bb.com.br) usa o convênio de teste 3128557 e não gera boleto cobrável de verdade.

Regras importantes

  • Operação idempotente: se o título já tiver linha digitável registrada, a API devolve o mesmo resultado sem novo registro.
  • O sistema avança o nosso número da carteira a cada tentativa; se o BB disser que o NN já existe, tenta o próximo automaticamente (comum no convênio de homolog compartilhado).
  • Remessa CNAB continua disponível em carteiras MANUAL_CNAB; esta fatia cobre só API.
  • Credenciais ficam criptografadas na carteira; não aparecem em listagem nem em logs de auditoria em claro.

Erros / avisos comuns

Mensagem / situação O que fazer
Carteira precisa ter classe de integração API… Ajuste a carteira para API bancária.
Registro via API BB exige conta… código 001 Vincule conta BB (001) à carteira.
Informe o número do convênio… Preencha convênio na aba Bancário.
Credenciais BB incompletas… Preencha App Key / Client ID / Secret na aba Bancário da carteira (perfil homolog ou prod).
Convênio/Carteira/Variação não cadastrado Em produção use a variação da conta real (ex.: 19), não a de homolog (35). Confira também se o convênio está vinculado à app de produção no Developers BB.
Solicitação não permitida… convênio … vinculado a esse cliente No Developers BB, abra a aplicação de produção cujas credenciais estão na carteira e vincule o convênio. Sem esse vínculo a API rejeita o registro.
Nosso Número já incluído… O sistema tenta o próximo NN sozinho; se persistir, aumente o contador na aba Bancário da carteira.
Somente títulos em aberto… Título pago/cancelado não registra boleto.

Relacionados

Referências