Multi-banco, multi-empresa: arquitetura segura no Odoo para holdings

Quando uma empresa cresce além de um CNPJ, a integração bancária deixa de ser um problema técnico e vira um problema organizacional. A holding tem 4 empresas operacionais. Cada uma tem 2 bancos. Cada banco exige credenciais por CNPJ, certificado próprio, webhook próprio. Multiplicando, são 16 conjuntos de credenciais que precisam coexistir, sem se misturar, e com auditoria de quem fez o quê em qual conta.

Este post explica como nossa integração resolve isso no Odoo: o modelo de dados, o gerenciamento de certificados, o isolamento entre empresas, e a parte de compliance que nenhuma planilha de senhas consegue cobrir.

Os três modelos possíveis

Antes da arquitetura, vale entender os três modelos que existem no mercado para multi-empresa em ERP:

Modelo A — Multi-empresa em uma única base Odoo. Uma instância, uma base PostgreSQL, várias res.company. Adequado para holdings com governança financeira centralizada e pouco apetite para isolar tecnicamente as empresas. É o que mais empresas brasileiras usam.

Modelo B — Uma base Odoo por empresa. Cada CNPJ tem sua própria base. Isolamento total no nível de banco de dados. Adequado para grupos onde as empresas operam de forma muito independente (por exemplo, M&A com integração lenta), ou para consultorias contábeis que hospedam vários clientes.

Modelo C — Hub central + Odoos consumidores. Um serviço HTTP separado (FastAPI, Node, ou outro) centraliza os adapters bancários, e cada Odoo consome via API interna. Adequado para SaaS multi-tenant verdadeiro e operações de grande escala.

Nossa integração suporta os três modelos. Cada um tem trade-offs diferentes em segurança, custo de operação e complexidade. Em uma reunião de diagnóstico, alinhamos qual deles faz sentido para o seu caso.

O modelo de dados (independente do modelo escolhido)

Independentemente do modelo, a integração no Odoo gira em torno de três objetos principais:

• l10n_br.bank.api.config: a credencial. Chave única (company_id, bank_id, environment). Armazena referências aos secrets (não os secrets em si), endpoints, escopos, validade.
• l10n_br.bank.api.transaction.log: o log auditável. Cada chamada à API de banco (request, response, latência, status, x-fapi-interaction-id, hash do payload) fica registrada por no mínimo 5 anos. Sem PII bruta nem tokens em claro.
• l10n_br.bank.webhook.event: cada webhook recebido. Unique constraint em (bank, txid, endToEndId) para idempotência. Estado de processamento. Reentrância segura.

Em um cenário multi-empresa, cada res.company carrega seu conjunto de bank.api.config, totalmente isolado. A consulta de saldo de uma empresa não pode, por construção, atingir credenciais de outra.

Onde os certificados moram (não no Odoo)

Esse é o ponto onde a maioria das integrações mal-feitas falha. Certificados ICP-Brasil A1 (.pfx, .pem, .key) e client_secrets não devem ficar em campos de texto no Odoo. Mesmo cifrados em coluna, ficam vulneráveis a leituras administrativas indevidas, a backup vazado, a vazamento por SQL injection.

Nossa integração suporta três modelos de armazenamento, em ordem de robustez:

1. Módulo keychain da OCA — abstração que suporta backends. Aceitável para PMEs menores em on-premise.

2. Secrets manager externo — AWS Secrets Manager, HashiCorp Vault, GCP Secret Manager, Azure Key Vault. O Odoo lê o secret por env-var ou via SDK, na inicialização do worker. Configuração padrão para PMEs sérias e holdings.

3. Volume montado read-only com chave protegida — em deploys Docker/Kubernetes, o .pem fica em volume, com permissão 600, e o .key é cifrado com chave vinda do secrets manager. Padrão recomendado para grupos com time de DevOps.

Em todos os modelos:

• O log de transação não imprime client_secret, access_token, certificado ou CPF/CNPJ bruto. Tudo mascarado.
• O acesso ao secret é restrito ao processo do Odoo na inicialização; não há endpoint que devolva o segredo para o usuário.
• A rotação de certificados ICP-Brasil A1 é automática: 30 dias antes do vencimento, alerta para o time de operações.

Multi-tenant real: como evitamos vazamento entre empresas

Em multi-empresa Odoo (Modelo A), o controle clássico do Odoo (res.company + multi_company) já protege a maior parte. Mas integração bancária tem três pontos críticos onde reforçamos:

1. Endpoint de webhook por tenant + token. Cada bank.api.config tem um webhook_token único. A URL é /webhook/pix/<bank>/<webhook_token>. Sem o token correto, o banco não consegue entregar o webhook na empresa errada — e mesmo que tentasse, validação de assinatura cruzada com a credencial da empresa derruba a tentativa.

2. Resolução do txid por escopo de empresa. Quando o webhook chega, dedupplicamos por (company_id, bank, txid). Não há possibilidade de um pagamento de uma empresa baixar fatura de outra mesmo que o txid colidisse (o que, sendo UUID v4, é estatisticamente impossível, mas adoramos defesa em camadas).

3. Rate limit por tenant. Cada banco tem um limite global por client_id (Itaú: ~600 req/min). Em multi-empresa que compartilha um único client_id de banco, distribuímos o rate via token bucket no Odoo. Empresas pequenas não são impactadas por uma empresa grande do mesmo grupo que faria spike.

Auditoria e LGPD

O regime regulatório brasileiro exige rastreabilidade. Resolução BCB para incidentes: 24h ao BCB. Resolução CD/ANPD nº 15/2024: 3 dias úteis à ANPD. Para suportar isso, a integração entrega:

• Trilha completa de chamadas: usuário Odoo → endpoint do banco → request/response (mascarado) → latência → status. Filtrável por empresa, banco, período. Exportável como CSV/JSON.
• Trilha de consentimento Open Finance: ID do consentimento, escopo, validade, eventos de revogação. Importante para a parte regulada (extrato consolidado).
• Retenção de logs por 5 anos (boas práticas + LGPD/BCB). Particionamento por mês para queries rápidas.
• Log estruturado em JSON para integração com ELK, Datadog, Sentry, Grafana. Sem PII bruta.
• Alertas operacionais: certificado vencendo, taxa de erro 5xx alta, webhook reativação falhou, rate limit batendo.

O caso da holding: um exemplo concreto

Pense em uma holding que opera 4 empresas: uma indústria, uma distribuidora, uma loja de varejo e uma SaaS B2B. Cada empresa tem CNPJ próprio, e tem 2 bancos cada uma — Itaú e BTG na indústria, BB e Inter na distribuidora, Santander e Sicoob no varejo, BTG e Inter na SaaS.

Sem integração unificada:

• 8 logins em internet bankings.
• 8 conjuntos de credenciais espalhadas (planilha de TI? gerente financeiro?).
• Conciliação descentralizada em 4 planilhas, ou nem isso.
• Visão de caixa consolidada da holding: trabalho mensal.

Com a nossa integração:

• 8 bank.api.config no Odoo, cada uma escopada para sua res.company.
• Secrets em Vault, com rotação automática.
• 8 webhooks ativos. Cada Pix, cada boleto pago, cada extrato — entra em segundos no Odoo.
• Visão de caixa consolidada da holding: tela única, atualizada em tempo real.
• Auditoria: cada chamada, cada usuário, cada empresa. Filtrável.

E se eu sou consultoria contábil hospedando vários clientes Odoo?

Esse é o caso típico do Modelo B (uma base por cliente) ou Modelo C (hub central + Odoos finos). Em ambos, isolamento é absoluto: a credencial de um cliente nunca toca a base de outro. Os secrets vivem em namespaces separados (Vault path por cliente, ou Secret Manager por cliente).

A integração, especificamente para esse cenário, oferece:

• Provisionamento padronizado de novo cliente (uma chamada cria a base, configura o adapter, pluga o webhook).
• Bilhetagem por chamadas/banco/cliente, para você cobrar dos seus clientes pelo uso real.
• Painel de operações centralizado para o seu time de NOC monitorar todos os clientes em uma tela.

Conclusão

Multi-empresa e multi-banco no Odoo, feitos certo, não são complexidade extra — são organização. A integração que entregamos cuida do isolamento, dos certificados, do compliance e da auditoria. Seu time financeiro vê a holding inteira; seu time de TI dorme tranquilo.

Sua empresa tem 2 ou mais CNPJs e 2 ou mais bancos? Conheça nossa oferta de Integração Bancária para Odoo ou marque uma conversa de 30 minutos. A gente desenha o modelo (A, B ou C), mapeia os riscos, e entrega um plano de implementação realista.

---

Os padrões de armazenamento de secrets seguem boas práticas de mercado e o Manual de Segurança do BCB. Resolução CD/ANPD nº 15/2024 dispõe sobre comunicação de incidentes em 3 dias úteis. Reportes ao BCB em 24h conforme normativos vigentes.