Como funciona o boleto-híbrido (Bolecode / Boleto+Pix) no Odoo

Você manda um boleto para um cliente e ele paga no terceiro dia útil. Você manda um QR Code Pix e ele paga em 30 segundos. E se o mesmo papel tivesse os dois? É exatamente isso que o boleto-híbrido — ou Bolecode, no jargão do Itaú; “Boleto+Pix” em outros bancos — faz. E é uma das integrações de maior ROI imediato para PMEs no Odoo.

Este post explica o que é, como funciona por dentro, qual a diferença para o boleto tradicional, e como ele se encaixa no Odoo.

O que é um boleto-híbrido

Um boleto-híbrido é um único documento de cobrança que contém:

• A linha digitável e o código de barras do boleto tradicional (compensação bancária via FEBRABAN).
• Um QR Code Pix Cobrança com vencimento (/cobv) com o mesmo valor, mesmo txid único, e mesma data de vencimento.

O cliente recebe o PDF (ou e-mail, ou WhatsApp) e escolhe como pagar:

1. Pelo QR Code Pix — pagamento instantâneo, em segundos, qualquer dia da semana, qualquer hora, com confirmação imediata via webhook.
2. Pela linha digitável do boleto — pelo internet banking ou caixa eletrônico, no fluxo tradicional, com compensação em D+1.

Independentemente da escolha do cliente, o pagamento é único: assim que ele paga por um dos canais, o outro é automaticamente baixado. Não existe risco de pagamento duplicado.

Como funciona por dentro

Quando sua empresa cria uma cobrança no banco via API, são criados (em uma só chamada, na maioria dos bancos):

• Um registro de boleto no sistema FEBRABAN, com nosso número, vencimento e linha digitável.
• Uma cobrança Pix com vencimento (/cobv), com txid (de 26–35 caracteres), valor exato, multa/juros/desconto opcional, expiração e mensagem para o pagador.
• Um QR Code estático ou dinâmico EMV apontando para essa cobrança Pix.
• Um webhook registrado para notificar a sua aplicação quando o pagamento ocorrer.

Quando o cliente paga, qualquer que seja o canal:

• Pix: o banco envia um POST ao seu webhook em segundos com o endToEndId, txid e valor.
• Boleto: o banco emite o registro de liquidação CNAB ou via webhook próprio do banco, em D+1.

Em ambos os casos, a outra “metade” da cobrança é automaticamente cancelada — você nunca recebe o pagamento duas vezes.

Por que ele converte mais

Os números de mercado mostram que boletos com QR Code Pix têm taxa de conversão substancialmente maior que boletos tradicionais, principalmente em três cenários:

• Cobrança recorrente sem cartão (mensalidade, plano, condomínio).
• Cliente fora do horário bancário (sábado, domingo, à noite).
• Cliente que não tem conta corrente PJ no banco emissor — Pix é universal, boleto exige internet banking.

E o ganho não é só no recebimento. A conciliação fica mais barata: o webhook Pix entra em segundos, sua fatura no Odoo baixa imediatamente, sua área financeira não precisa esperar o CNAB Retorno do dia seguinte. Detalhamos esse efeito em Conciliação bancária em tempo real: webhooks vs CNAB.

Quais bancos brasileiros oferecem

Praticamente todos os grandes oferecem alguma forma de boleto-híbrido em 2026:

• Itaú (Bolecode) — combinação boleto+Pix com txid único.
• Bradesco — Pix CobV combinado com Boleto Cobrança.
• Banco do Brasil — Cobrança com Pix integrado (e Boleto+Pix Automático para recorrência).
• Santander — boleto com QR Code Pix.
• Inter — Cobrança com Pix híbrido nativo na mesma chamada.
• BTG — Pix Cobrança integrada com boleto.
• Sicredi — Boleto Híbrido.
• Sicoob — Cobrança Bancária V3 com Pix.
• Caixa — Cobrança Bancária Híbrida (boleto + Pix).
• C6 Bank — boleto com vencimento, multa, desconto e QR Code Pix.

Cada banco tem nome comercial próprio, mas o conceito é o mesmo. O pagamento Pix segue o padrão Bacen (/cobv), o boleto segue padrão FEBRABAN. Para uma comparação detalhada de cada API, veja nosso comparativo das 12 principais APIs bancárias.

Custo

O custo do boleto-híbrido é tipicamente a tarifa do canal pelo qual o cliente pagou:

• Cliente pagou por Pix → tarifa de liquidação Pix Cobrança (R$ 0,01 a R$ 0,10).
• Cliente pagou por boleto → tarifa de liquidação de boleto (R$ 0,90 a R$ 3,50, varia muito por banco).

Em outras palavras, a empresa economiza toda vez que o cliente prefere o Pix, e mantém o boleto como fallback para clientes que ainda preferem o canal tradicional. Em volumes altos, a economia em tarifa de liquidação paga a integração rapidamente.

Como funciona no Odoo

No Odoo Brasil, a localização OCA já tem o esqueleto:

• l10n_br_account_payment_order já modela payment.order, payment.mode, e códigos de instrução por banco — onde tradicionalmente a empresa manda CNAB Remessa.
• payment_bacen_pix começa a tratar QR Codes Pix EMV.
• l10n_br_account_payment_brcobranca gera o boleto via micro-serviço.

O que faltava — e é exatamente o que a integração da KMEE entrega — é o glue: um adapter por banco que, na hora de emitir uma fatura no Odoo, faz uma chamada de API que cria, em uma só transação, o boleto registrado e o Pix Cobrança com vencimento, traz de volta a linha digitável + QR Code + URL do PDF, e registra o webhook.

Na prática, o fluxo no Odoo fica:

1. Você cria uma fatura em account.move.
2. No campo payment.mode, escolhe “Boleto + Pix Itaú” (ou Inter, BB, etc.).
3. Confirma a fatura. O Odoo chama a API do banco e devolve a linha digitável e o QR Code.
4. O Odoo gera o PDF do boleto-híbrido (com QR Code embutido) e anexa à fatura.
5. O e-mail/WhatsApp para o cliente já vai com o PDF.
6. Quando o cliente paga, o webhook do banco bate em /webhook/pix/<bank>/<token>, e o Odoo registra o pagamento via account.payment.register, reconciliando automaticamente com a fatura. Em D+1, se o cliente preferiu o boleto, o CNAB Retorno faz a mesma reconciliação.

Pegadinhas a evitar

• Idempotência do txid: o txid Pix tem que ter 26 a 35 caracteres alfanuméricos e ser único por cobrança. Se você reaproveitar txid, o banco devolve erro. Use UUID v4 sem hífens, prefixado pelo tenant.
• Webhook obrigatório para tempo real: alguns bancos (Bradesco, por exemplo) só notificam Pix em tempo real se você tiver webhook configurado. Sem webhook, vira polling horário.
• Reativação de webhook: BTG exige reautenticação do webhook a cada 24h.
• Multa, juros e desconto: configure com cuidado no Pix CobV; alguns bancos têm regras específicas por tipo de produto.
• Cancelamento e baixa: use a API; não tente cancelar manualmente no internet banking se a integração estiver ativa, porque o estado dos dois lados pode ficar inconsistente.

Vale a pena para todo mundo?

Para PMEs com mais de 50 boletos/mês emitidos, sim, sem dúvida. O ganho de conversão por Pix paga a integração em meses, e a redução de trabalho na conciliação é sentida no segundo mês.

Para volumes baixos (menos de 20 boletos/mês), pode fazer mais sentido começar com Pix Cobrança puro (sem boleto) e adicionar o boleto-híbrido depois, conforme a base de clientes pedir.

Quer ver isso rodando no seu Odoo, com seu banco? Conheça nossa oferta de Integração Bancária para Odoo — a gente faz um piloto em duas semanas. Você passa a emitir boleto-híbrido no Odoo no mesmo dia da virada.

---

Especificação Pix CobV: bacen/pix-api. Bolecode é nome comercial do Itaú; o conceito é coberto também por Bradesco, BB, Santander, Inter, BTG, Sicredi, Sicoob, Caixa e C6 com nomenclaturas próprias.