Conciliação bancária em tempo real no Odoo: webhooks vs CNAB

Pergunta básica para quem trabalha em contas a receber: quanto tempo passa entre seu cliente pagar uma fatura e o sistema mostrar isso? Em uma operação tradicional Brasil-2020, a resposta é “de manhã, no dia seguinte”. Em uma operação 2026 com a integração que entregamos no Odoo, a resposta é “em segundos”.

Este post explica a diferença concreta entre conciliar por CNAB Retorno e conciliar por webhook, por que essa diferença é mais que velocidade, e como ela funciona no Odoo da sua empresa.

O modelo CNAB: conciliação em batch

CNAB é o padrão FEBRABAN para troca de arquivos entre empresas e bancos. No fluxo de cobrança:

• Sua empresa envia um CNAB Remessa registrando os boletos a emitir.
• O banco processa, registra os boletos e devolve um CNAB Retorno (240 ou 400 posições).
• Quando algum cliente paga, o banco gera outro CNAB Retorno com os pagamentos, normalmente uma vez por dia (de madrugada).
• Sua empresa importa esse arquivo no ERP, parseia, e dá baixa nas faturas.

É um modelo robusto, padronizado e que funcionou bem por décadas. Mas tem uma característica: ele é batch. Mesmo que o cliente pague no caixa eletrônico às 10h da manhã, sua empresa só vê isso na manhã seguinte.

E aqui surge o custo invisível desse modelo.

O custo invisível do batch

No financeiro:

• Seu fluxo de caixa do dia está sempre 24h atrasado. Decisões de aplicação de saldo, pagamento de fornecedor, antecipação — todas tomam decisões baseadas em saldos que já mudaram.
• Conciliação manual no fim do mês ainda é necessária (porque o CNAB tem inconsistências, débitos sem código, tarifas).

No atendimento ao cliente:

• Cliente liga reclamando que pagou e não consta. “Pagou ontem? Olha, ainda não chegou no nosso sistema.”
• Cliente em régua de cobrança recebe e-mail/SMS cobrando algo que ele já pagou — e fica irritado, com razão.

Nas operações de crédito:

• Aprovação de pedido com base em “se o cliente pagou as últimas N faturas” trava sem informação atualizada.
• Régua de bloqueio (suspender serviço SaaS, parar produção) opera em janela errada.

No marketing e expansão:

• “Cliente PIX-fast” do BTG/Inter/PicPay valoriza confirmação imediata. CNAB de madrugada perde a expectativa.

O modelo webhook: conciliação em tempo real

No modelo webhook, a relação se inverte. Em vez do seu sistema ir buscar (pull/batch), o banco notifica seu sistema (push) assim que algo acontece.

Quando um cliente paga uma cobrança Pix, em segundos:

1. O Bacen confirma o Pix.
2. O banco do recebedor (sua empresa) emite um POST HTTPS para um endpoint da sua aplicação (/webhook/pix/<bank>/<token>), com txid, endToEndId, valor, horário, dados do pagador.
3. Sua aplicação valida a assinatura, dedupplica por (banco, txid, endToEndId) e registra o pagamento.
4. A fatura no ERP é baixada automaticamente.
5. Tudo isso em segundos.

Para boletos com webhook (oferecidos por Itaú, Bradesco, BB, Inter, BTG, Sicoob, Sicredi e outros), o fluxo é o mesmo, com latência maior (segue o ciclo de compensação bancária, que tem janelas), mas ainda muito superior ao CNAB.

O que muda concretamente

Indicador	CNAB Retorno	Webhook
Latência de baixa	12 a 24h (next morning)	Segundos a minutos
Trabalho manual de importação	Diário	Zero
Detecção de pagamento duplicado	Eventual reconciliação manual	Idempotência por txid
Visibilidade de fluxo de caixa	D+1	Tempo real
Régua de cobrança	Falsos positivos comuns	Quase eliminados
Atendimento ao cliente “já paguei”	Travado	Resolvido
Custo de operação financeiro	Alto em horas-pessoa	Baixo

Como entregamos isso no Odoo

A integração da KMEE no Odoo já operacionaliza tudo isso:

• Adapters de webhook para Itaú, Bradesco, Banco do Brasil, Santander, Inter, BTG, Sicoob, Sicredi, Caixa e C6. Cada banco tem suas particularidades (formato de assinatura, headers, política de retry), todas tratadas pelo adapter correspondente.
• Endpoint Odoo /webhook/pix/<bank>/<token> com validação de assinatura (HMAC ou JWS conforme o banco), idempotência via tabela bank.webhook.event com unique constraint em (bank, txid, endToEndId).
• Reconciliação automática com account.move.line por valor + txid + parceiro. Quando o match é único, baixa direto via account.payment.register. Quando há ambiguidade, fica em fila de revisão na interface do Odoo, com um clique para aprovar.
• Fallback de polling (cron horário) para cobrir webhooks perdidos por instabilidade do banco. Detectado via diferença entre /cob?status=CONCLUIDA e o que está registrado.
• Compatibilidade com CNAB: a integração coexiste com l10n_br_account_payment_order. Quem ainda precisa enviar CNAB Remessa para boletos de bancos que não suportam API plena, continua usando o fluxo OCA padrão. Webhook é aditivo, não substitutivo.

Como ficam as métricas operacionais

Com a integração rodando, as métricas que mudam para uma PME típica:

• Tempo médio de baixa de Pix: de 12h para menos de 1 minuto.
• Tempo médio de baixa de boleto: de 24h para a janela do banco (minutos a poucas horas, dependendo do banco).
• Trabalho de importação CNAB: cai a quase zero (CNAB vira fallback de exceção).
• Tickets de suporte “já paguei e não consta”: caem 80–95%.
• Régua de cobrança: deixa de mandar mensagem para clientes que pagaram nas últimas 12h.

Pegadinhas que a integração resolve por você

Webhook em produção tem armadilhas que parecem pequenas mas viram problema sério em volume. A nossa integração trata cada uma:

• Idempotência: o banco pode reenviar o mesmo webhook (especialmente em retry após timeout). A unique constraint em (bank, txid, endToEndId) evita pagamento duplicado.
• Reativação periódica: alguns bancos (BTG) exigem reautenticar o webhook a cada 24h. Cron job cuida.
• Política de retry do banco: se você responder lento (>5–10s), o banco assume falha e retenta. Endpoint Odoo otimizado para responder 2xx em milissegundos, processamento async via queue_job.
• TLS e mTLS: alguns bancos exigem mTLS no caminho de volta também. Configuração tratada por adapter.
• Janela de manutenção: erros 503 do banco são tratados com backoff exponencial mais espaçado (5min, 30min, 1h).

E se eu já tenho CNAB rodando?

A integração não pede que você jogue fora o CNAB. Ela convive com ele. O recomendado em projetos de migração:

1. Mês 1: webhook ligado no banco principal, em paralelo com CNAB. Ambos batem na conciliação. CNAB serve como reconciliador de checagem.
2. Mês 2: confiança nos webhooks medida; CNAB começa a ser fallback (importado, mas não usado para baixar — só para auditar).
3. Mês 3: CNAB Retorno passa a ser opcional; só é importado para bancos que ainda não têm webhook estável (Caixa em alguns produtos, por exemplo).

Para boletos antigos, registrados antes do webhook estar ativo, o CNAB Retorno continua sendo o caminho. Não há quebra de continuidade.

Conclusão

Conciliação em tempo real não é luxo de banco digital — é o novo piso operacional. Para PMEs no Odoo, a diferença entre CNAB e webhook é a diferença entre “fim do mês” e “agora”. Nossa integração entrega isso pronto: webhooks dos 10 principais bancos brasileiros, reconciliação automática, idempotência, e CNAB convivendo como fallback.

Quer ver, em 30 minutos, como a sua próxima fatura paga vai aparecer no seu Odoo em segundos? Conheça nossa oferta de Integração Bancária para Odoo ou marque uma demo. A gente entra com sandbox do seu banco principal e mostra o fluxo completo, da emissão à baixa.

---

A integração suporta os 10 bancos com API plena (Itaú, Bradesco, BB, Santander, Inter, BTG, Sicoob, Sicredi, Caixa, C6). Para Nubank PJ e Safra, conciliação por webhook é entregue via Open Finance regulado, com agregador parceiro autorizado pelo BCB.