Pular para conteúdo

Baixa automática BB (webhook + consulta)

Tela do Telvora ERP — Baixa automática BB (webhook + consulta)

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

Módulo: Financeiro
Menu: Auxiliares → Carteiras de cobrança · Ferramentas → Agenda de tarefas
Público: Gestor financeiro / TI
Status: Publicado
Atualizado: 2026-09-04
Refs técnicas: ADR-019 (BB-3) · 01-ARQUITETURA/65-banking-providers-api-cnab.md

O que faz

Quando o cliente paga o boleto no Banco do Brasil, o Telvora pode baixar o título sozinho:

  1. Webhook — o BB avisa na hora (evento Baixa Operacional)
  2. Consulta periódica — rede de segurança a cada X minutos (tarefa na Agenda)

Pré-requisitos

  • Carteira com classe API bancária, banco 001, convênio/carteira/variação corretos e perfil Produção
  • Credenciais BB_PROD_* no servidor
  • Título já registrado (com nosso número / linha digitável)

Passo a passo — Webhook

  1. Abra Auxiliares → Carteiras de cobrança → carteira BB → aba Bancário.
  2. Em Usar webhook BB, escolha Sim (o sistema gera a URL callback).
  3. Salve a carteira.
  4. Copie a URL callback exibida.
  5. No Developers BB, abra a aplicação de produção:
  6. Menu Webhook → Eventos → Cadastrar evento
  7. API Cobranças, convênio da carteira, tipo Baixa Operacional
  8. Cole a URL callback e um e-mail de contato
  9. Em URLs, confirme a mesma callback
  10. Pague um boleto de teste e confira se o título ficou Pago no Contas a receber.

Passo a passo — Consulta automática (backup)

  1. Abra Ferramentas → Agenda de tarefas.
  2. Localize Consulta pagamentos BB (API) (CONSULT_BB_PAYMENTS).
  3. Deixe habilitada (intervalo sugerido: 30 minutos).
  4. Use Executar agora para testar.

Mesmo com webhook ativo, a consulta evita título perdido se o BB atrasar ou falhar o POST.

Regras importantes

  • A baixa é idempotente: se o título já estiver pago, o webhook responde OK sem duplicar.
  • O sistema consulta a API após o webhook para confirmar liquidação (código 6 etc.) antes de baixar.
  • Data de crédito: usa dataCredito do BB; se não vier, soma os Dias crédito boleto da carteira.
  • Conta/caixa do recebimento = conta vinculada à carteira.

Erros / avisos comuns

Mensagem / situação O que fazer
Webhook não reconhecido Token da URL diferente do salvo na carteira — reabra a carteira e recadastre a URL no portal BB
Título não encontrado Confira se o NN do boleto está no título Telvora (external_nn)
Boleto ainda não liquidado Webhook antecipou; a tarefa de consulta deve baixar quando o BB confirmar
Informe a conta/caixa… Vincule conta bancária ACTIVE na carteira

Relacionados

Referências