Toda integração entre uma plataforma vertical e um ERP começa parecida: uma consulta pontual, um relatório que o time comercial pediu, uma automação pequena que economiza alguns minutos por dia. O problema raramente aparece nessa primeira integração. Ele aparece na quinta, na décima, quando várias partes diferentes do sistema já dependem de acesso direto ao mesmo banco transacional, cada uma com sua própria suposição sobre o que aquele dado significa.
Nesse ponto, qualquer mudança de schema no ERP vira um evento de risco distribuído. Qualquer consulta mal otimizada pode degradar o sistema que registra vendas, estoque e produção. E quando um agente de IA entra nesse cenário como “mais um consumidor” do mesmo banco, o problema não é a IA — é que a superfície de acesso já não tinha fronteira nenhuma antes dela chegar.
Este artigo detalha o raciocínio arquitetural que aplicamos para evitar esse cenário: como conectar inteligência operacional, analytics e agentes de IA a um ERP sem transformar o banco transacional em uma API pública de uso irrestrito. O OpenPharma, produto da Codelevel para farmácias de manipulação, aparece aqui como aplicação real desse raciocínio — não como anúncio comercial.
1. O problema: integrações que começam simples e terminam acopladas
Um ERP de farmácia de manipulação — como o sistema transacional que registra fórmulas, requisições, orçamentos e movimentações fiscais — não foi desenhado para ser consultado livremente por múltiplos sistemas externos ao mesmo tempo. Ele foi desenhado para sustentar a operação diária com consistência transacional.
Quando uma plataforma vertical de analytics, PCP ou um agente conversacional precisa desses dados, existe uma tentação de engenharia compreensível: “o dado já está no banco, por que não consultar diretamente?” Em protótipos e provas de conceito, isso funciona. Em produção, cada novo consumidor direto do banco adiciona:
- Acoplamento de schema: qualquer alteração na estrutura das tabelas do ERP pode quebrar silenciosamente consumidores que nunca foram comunicados sobre a mudança.
- Blast radius ampliado: uma consulta pesada ou mal planejada, originada em qualquer um dos consumidores, pode competir por recursos com a própria operação transacional que o ERP existe para sustentar.
- Exposição excessiva: sem uma camada intermediária, não existe um ponto único para aplicar controle de acesso, mascaramento de dados sensíveis ou limites de uso — cada consumidor reimplementa (ou esquece de implementar) suas próprias regras.
- Perda de observabilidade: sem um contrato explícito, fica difícil responder com confiança “quem está lendo o quê, quando e por quê” no sistema de origem.
Nenhum desses riscos é causado pela IA. Eles existem desde a segunda integração direta ao banco. A chegada de agentes de IA como consumidores apenas torna esse acoplamento mais visível — e mais urgente de resolver — porque agentes tendem a formular perguntas abertas e variáveis, exatamente o tipo de uso para o qual um acesso irrestrito ao banco é mais perigoso.
2. ERP como system of record — não necessariamente como system of intelligence
Uma distinção útil, generalizável e não dogmática: o ERP tende a ser o system of record — a autoridade sobre o estado transacional do negócio (o que foi vendido, o que está em estoque, o que foi produzido). Isso não significa que o ERP deva ser, ao mesmo tempo, o system of intelligence ou o system of operational experience — ou seja, o lugar onde analytics, interpretação de domínio, workflows e interfaces para humanos e agentes acontecem.
Essa separação não é uma regra universal obrigatória para todo sistema do mundo; é uma escolha arquitetural que tende a valer a pena quando:
- o ERP precisa continuar respondendo com previsibilidade para a operação crítica do dia a dia;
- múltiplos consumidores (analytics, PCP, agentes, relatórios) precisam de visões diferentes do mesmo dado;
- a evolução de cada camada acontece em velocidades diferentes.
Em alguns cenários mais simples — poucos consumidores, baixa criticidade, escala pequena — pode ser razoável consultar o ERP de forma mais direta. O ponto não é proibir acesso direto em qualquer circunstância; é reconhecer que, conforme o número de consumidores e a sensibilidade operacional crescem, uma fronteira de integração explícita deixa de ser luxo de engenharia e passa a ser necessidade estrutural.
3. A fronteira de integração: contrato, não acidente
A camada que fica entre o ERP e tudo que consome seus dados — a fronteira de integração — é onde a decisão arquitetural mais importante deste artigo acontece. Ela não é “só uma API”; é um contrato explícito que define o que pode ser acessado, como, por quem e sob quais limites.
Uma fronteira de integração bem desenhada tende a tratar as seguintes propriedades como PROPERTIES (o que o contrato garante), e deixa livre o IMPLEMENTATION MECHANISM (como isso é tecnicamente resolvido) para a realidade de cada stack:
| Property (o que deve ser garantido) | Implementation Mechanism possível (não universal) |
|---|---|
| Acesso mínimo necessário por consumidor | Escopos de API, views restritas, permissões por capacidade |
| Normalização e significado estável do dado | Camada de modelo de domínio, DTOs versionados |
| Isolamento do impacto de consultas | Réplicas de leitura, filas, cache, limites de taxa |
| Observabilidade de quem acessa o quê | Logging estruturado, auditoria, métricas de uso por consumidor |
| Versionamento e evolução sem quebra | Contratos versionados, deprecação controlada, compatibilidade retroativa |
| Identidade do tenant em ambientes multi-cliente | Credencial por tenant, autenticação por token, roteamento por conta |
| Autorização por capacidade, não por tabela | Modelos de permissão orientados a casos de uso, não a acesso bruto a schema |
| Limites de uso e contenção de abuso | Rate limiting, timeouts, circuit breakers |
A distinção entre property e mechanism importa porque evita dogmatismo: não existe uma única forma “certa” de implementar uma fronteira de integração (REST, MCP, GraphQL, mensageria, views materializadas são todos mecanismos possíveis). O que não é opcional, na nossa experiência, é que as propriedades acima existam — do contrário, qualquer mecanismo escolhido vira apenas uma nova forma de acoplamento direto disfarçada.
4. Do dado bruto à capacidade de domínio
Um erro comum é tratar “ter acesso ao banco” como equivalente a “ter uma capacidade de analytics”. Entre o dado bruto e uma capacidade útil para operação, analytics ou um agente de IA, normalmente existem etapas de maturação que não podem ser puladas sem custo de confiabilidade:
Tabelas Transacionais Modelo Normalizado Capacidade de Domínio
(ERP, schema interno) → (significado estável, → (unidade de negócio:
linhas, FKs, campos nomes de domínio, "faturamento do
internos ao sistema) tipos consistentes) período", "Pareto
de produtos")
│ │ │
└───────────────────────────┴────────────────────────────┘
▼
Operação / Analytics Experiência
(relatórios, indicadores, (interface humana,
dashboards, alertas) agente conversacional)Cada etapa adiciona algo que o dado bruto, sozinho, não tem:
- Tabelas transacionais carregam a verdade operacional, mas em um formato otimizado para a operação do ERP — não para interpretação externa. Nomes de colunas internos, convenções específicas do fornecedor do ERP e campos de controle técnico não são, por si só, significado de negócio.
- Modelo normalizado traduz o dado bruto para um vocabulário estável e documentado, desacoplado de detalhes de implementação do ERP. É aqui que “o que uma coluna significa de fato” deixa de depender de conhecimento tribal.
- Capacidade de domínio é a unidade que efetivamente é exposta e consumida — não “a tabela de requisições”, mas “consultar requisições por loja e período”, por exemplo. É no nível de capacidade, não de tabela, que autorização e limites fazem sentido.
- Operação e analytics usam essas capacidades para compor indicadores, relatórios e alertas — sem precisar conhecer a estrutura interna do ERP.
- Experiência é onde humanos e agentes efetivamente interagem com o resultado — interface web, relatório gerencial, resposta de um agente conversacional.
No caso do OpenPharma, essa progressão é observável em capacidades de domínio já em produção no cliente real da Codelevel — por exemplo, consultas de faturamento por período e por loja, análise de requisições, acompanhamento de orçamentos (incluindo taxa de aprovação), identificação de inconsistências fiscais, análise de produtos e componentes de fórmulas (incluindo Pareto de recorrência), e uma visão executiva consolidada por produto. Cada uma dessas capacidades existe como unidade de domínio nomeada — não como acesso livre a uma tabela do ERP — e seus parâmetros, defaults e semântica são definidos pelo contrato técnico da camada de integração, não reconstruídos informalmente por quem consome.
5. Onde entram os agentes de IA
Um agente de IA que precisa responder “qual foi o faturamento da loja X no mês passado?” não precisa — e não deveria precisar — de acesso de leitura irrestrito ao banco do ERP. O caminho recomendado segue a mesma lógica de qualquer consumidor autorizado:
Pergunta humana → Capacidade autorizada → Contrato (parâmetros, defaults,
semântica definidos pela
fronteira de integração)
│
▼
Consulta/operação delimitada
(somente o que a capacidade permite)
│
▼
Resultado estruturado
│
▼
Proveniência / auditoria (o que foi
consultado, quando, com quais parâmetros)Um mecanismo possível para expor essas capacidades a um agente é o Model Context Protocol (MCP) — um protocolo que permite declarar ferramentas (tools) com nome, descrição, parâmetros e semântica, consumíveis por um agente de forma estruturada. É importante frisar: MCP é um mecanismo de exposição de capacidades já definidas pela fronteira de integração — não é, por si só, a fronteira de integração, nem um benefício comercial a ser vendido. Ele resolve “como o agente descobre e invoca uma capacidade de forma padronizada”; não resolve, sozinho, “quais capacidades deveriam existir” ou “quais limites de acesso são apropriados” — essas decisões continuam sendo arquitetura e governança, não propriedade do protocolo.
Um princípio que seguimos na Codelevel, aplicado ao próprio agente interno que consulta dados do OpenPharma em nome de um cliente: nesta arquitetura, o agente não recebe acesso direto ao banco de dados ou ao ERP de um cliente. O acesso a dados operacionais ocorre exclusivamente através de tools autorizadas, e o contrato técnico — nomes, parâmetros, defaults e semântica de cada tool — é definido pela camada de integração (no caso, o OpenPharma MCP), não reconstruído livremente pelo agente a partir de conhecimento geral.
6. Isolamento multi-tenant
Em uma plataforma vertical que atende múltiplos clientes, a fronteira de integração também precisa isolar o acesso entre organizações diferentes. Alguns princípios que seguimos, descritos aqui no nível de propriedade arquitetural (sem revelar detalhes privados de infraestrutura):
- Identidade do tenant determinada pela credencial, não pela escolha do agente ou do consumidor. O tenant ao qual uma requisição pertence deve ser resolvido a partir de uma credencial de autenticação específica daquele cliente; dentro deste desenho, a escolha de tenant não é deixada livre em tempo de execução.
- Autorização por capacidade dentro do escopo do tenant. Um agente ou usuário autenticado como pertencente ao Tenant A não deve conseguir, por construção do contrato, solicitar dados do Tenant B — independentemente da intenção expressa na pergunta.
- Fronteiras por organização/filial quando o próprio domínio exigir. Dentro de um mesmo tenant, pode haver necessidade de segmentar por loja, filial ou unidade de negócio; essa segmentação segue a mesma lógica de autorização por capacidade.
- Postura fail-closed quando a arquitetura suportar. Quando a resolução de tenant ou a autorização de uma capacidade específica falha ou é ambígua, o comportamento mais seguro é negar o acesso por padrão, em vez de assumir um tenant ou escopo default. Essa postura depende de cada implementação concreta e não deve ser generalizada como garantia universal de toda e qualquer configuração possível.
Não detalhamos aqui a topologia física de banco de dados, nomes de ambientes ou mecanismos internos específicos — essas informações são implementação, não são o que importa para quem quer entender o raciocínio arquitetural generalizável.
7. Evolução desacoplada
Uma consequência prática de ter uma fronteira de integração explícita é que ERP, plataforma vertical, analytics e agentes de IA podem evoluir em ritmos diferentes, desde que o contrato entre eles seja respeitado e versionado:
- O ERP pode evoluir seu schema interno, trocar de versão ou até ser substituído, desde que a camada de integração seja atualizada para manter o contrato externo estável (ou o contrato seja versionado de forma explícita quando uma mudança é inevitável).
- A plataforma vertical pode adicionar novas capacidades de domínio sem exigir mudanças no ERP, desde que os dados necessários já estejam disponíveis através do modelo normalizado.
- Agentes de IA podem ganhar novas capacidades de consulta ou operação simplesmente consumindo novas tools expostas pela fronteira — sem exigir qualquer alteração na forma como o ERP opera.
Esse desacoplamento é o que permite que uma plataforma como o OpenPharma continue evoluindo — adicionando novas análises, novos relatórios, novos pontos de contato para agentes — sem que cada evolução vire um projeto de migração de dados ou um risco para a operação transacional em produção.
8. OpenPharma como aplicação real desses princípios
O OpenPharma é a plataforma vertical da Codelevel para farmácias de manipulação, e opera em produção com um cliente real integrado. Na prática operacional, isso significa:
- O ERP da farmácia — onde residem fórmulas, requisições, orçamentos e dados fiscais — permanece o sistema transacional de retaguarda. O OpenPharma não substitui essa autoridade operacional.
- A camada de integração do OpenPharma expõe capacidades de domínio nomeadas (faturamento, requisições, orçamentos, inconsistências fiscais, análise de produtos e visão executiva por produto), cada uma com contrato técnico próprio — parâmetros, defaults e semântica definidos pela própria plataforma, não improvisados por quem consome.
- Um agente conversacional, operando como interface para a farmácia, consome exclusivamente essas capacidades autorizadas. Nesta arquitetura, ele não recebe acesso direto ao ERP ou ao banco de dados do cliente, e não escolhe livremente qual tenant está consultando — isso é resolvido pela credencial de autenticação.
Essa aplicação não é um caso hipotético de arquitetura de referência: é o funcionamento real de uma plataforma em produção, usada como evidência de que os princípios descritos acima são aplicáveis além da teoria — e, ao mesmo tempo, como lembrete de que qualquer generalização a partir de um único cliente real tem limites que devem ser reconhecidos.
9. Checklist de arquitetura
Ao desenhar ou revisar uma integração entre uma plataforma vertical e um ERP, vale verificar:
- Existe uma fronteira de integração explícita entre o ERP e todos os consumidores externos (analytics, plataforma, agentes)?
- O acesso é concedido por capacidade de domínio nomeada, não por acesso direto a tabelas ou schema interno?
- O contrato técnico (parâmetros, defaults, semântica) é definido em um único lugar e versionado, em vez de reconstruído por cada consumidor?
- Existe identidade de tenant resolvida por credencial, com autorização por escopo — e não escolha livre de tenant em tempo de execução?
- Existe observabilidade mínima de quem acessou o quê, quando e com quais parâmetros?
- Mudanças no ERP podem ser absorvidas pela camada de integração sem quebrar consumidores, ou ao menos com deprecação controlada?
- Agentes de IA consomem apenas capacidades autorizadas, com proveniência registrada, em vez de consultas abertas ao banco?
- Claims sobre segurança e isolamento estão qualificados (“reduz o raio de impacto”, “autorização por escopo”) em vez de absolutos (“totalmente seguro”, “impossível de vazar”)?
10. Conclusão
O valor de conectar IA a sistemas operacionais não está em dar mais acesso ao modelo de linguagem; está em construir melhores fronteiras para que software, pessoas e agentes trabalhem sobre capacidades confiáveis. Um ERP que vira superfície aberta de consulta não fica mais inteligente — fica mais frágil. Uma plataforma vertical que respeita a autoridade operacional do ERP, e expõe capacidades de domínio explícitas e auditáveis, é o que permite que analytics, operação e agentes evoluam com velocidade sem transformar cada nova integração em um novo ponto de fragilidade.
Este artigo é parte de uma série sobre arquitetura de sistemas com agentes de IA na Codelevel. Veja também Human Gates na Prática: Desenhando Interfaces Onde Pessoas Realmente Decidem e Por que Separamos Intenção, Aprovação e Autorização de Execução em Sistemas com Agentes.