Arquitetura de ERP e integrações: fronteiras e contratos

ERP no Brasil raramente é caixa preta única — é ecossistema: emissão NF-e, financeiro, estoque, WMS, e-commerce, contabilidade SPED, BI. Como arquiteto fundador TEK Softwares desenho integrações que sobrevivem a CFOP novo, servidor Sefaz fora e analista pedindo CSV às 23h. Este artigo consolida padrões que aplico em clientes PME e médias empresas: batch vs realtime, idempotência, contratos versionados e observabilidade sem buzzword.

Camadas lógicas

Core ERP — regra fiscal, estoque, financeiro (monólito Java muitas vezes).
Integration hub — APIs REST, filas, Pentaho PDI (integração Pentaho).
Satélites — e-commerce, CRM, app mobile entregador.
Analytics — DW read-only, não query OLTP pesada.

Batch versus evento

Nota autorizada Sefaz → evento NFeAutorizada → estoque baixa + contas receber + e-mail cliente. Batch noturno reconcilia divergência e envia SPED. Escolha errada: polling HTTP cada 5s 10k SKUs — derruba ERP.

Idempotência obrigatória

Webhook e-commerce reenvia pedido — chave idempotência orderId+source evita NF duplicada. Tabela processed_events com TTL audit. Retry exponential backoff fila.

POST /api/pedidos
Idempotency-Key: shopify-12345
{ "itens": [...], "cfop": "5102" }

Validação CFOP antes persistir — CFOP escrita fiscal.

Contratos e versionamento

OpenAPI publicado semver. Breaking change = /v2 prefix ou header Accept. Consumer-driven contract test Pact quando múltiplos fornecedores consomem API fiscal.

Pentaho no ecossistema

Carga histórica 10 anos vendas para DW, sync legado AS/400, arquivamento XML NF-e S3. Parametrize jobs — parâmetros Pentaho. Não duplique regra ICMS no ETL se ERP já calculou — transporte valores autorizados.

Segurança integrações

VPN site-to-site ou IP allowlist + mTLS. OAuth client credentials machine-to-machine. Log sem XML completo se não necessário — LGPD. Leitura segurança web 2026.

Resiliência Sefaz

Fila contingência offline FS-DA. Retry jitter evita thunder herd quando SVC volta. Status serviço monitorado; dashboard operador.

Microsserviços cirúrgicos

Extraia gateway e-commerce ou serviço consulta CEP — não NF-e core day one. Critérios em microsserviços quando migrar.

Observabilidade

Correlation-ID header propagado ERP → fila → Pentaho log MDC. Métricas: lag fila, job PDI duração, taxa rejeição NF-e por código. Alert on-call rotação documentada.

Dados mestre

Produto, cliente, tabela CFOP — single source of truth ERP. Satélites cache read-only TTL curto. Sync conflito: ERP vence, exceto preço promo e-commerce com janela explícita.

Testes integração 100%

Ambiente homolog Sefaz, pedido fake Shopify, assert NF autorizada + estoque + lançamento contábil stub. CI pipeline — CI/CD pequeno roda suite noturna se lenta.

Documentação viva

Diagrama sequência emissão NF-e atualizado quando muda fluxo. Runbook "Sefaz timeout". DECISIONS.md por cliente TEK — onboarding consultor em dias não meses.

Anti-corruption layer

Adapter traduz modelo legado COBOL copybook para DTO interno limpo. Evita contaminar domínio ERP com nomenclatura host 1980.

Outbox pattern

Transação grava pedido + row outbox mesma commit. Worker publica fila — garante at-least-once sem dual write frágil.

SLA com terceiros

Webhook Shopify SLA implícito retry; Sefaz indisponível SLA zero — desenhe contingência offline. Contrato suporte define escalonamento.

Canonical data model

Produto ERP id interno sku ean ncm unidade — satélites mapeiam sku. Evento ProdutoAtualizado broadcast id não sku frágil rename.

Dead letter queue

Mensagem falha processamento 3 retries → DLQ alerta operador. UI reprocess manual após corrigir dado origem. Não perca pedido Black Friday silencioso.

Batch window fiscal

SPED fechamento dia 1-15 mês — congele deploy produção dia 10-14 except hotfix P1. Comunique calendário integração parceiros.

Diagrama C4 nivel container atualizado

Desenhe ERP monolito fila satelite e-commerce DW pentaho BI usuario operador contador parceiro webhook. Seta legenda protocolo REST JDBC SFTP frequencia realtime batch. Coloque diagrama wiki link README onboarding vendas alinha expectativa integracao inclusa contrato.

Capacity planning pico dezembro black friday fila profundidade max consumer count scale horizontal stateless apenas servico permitido NF-e core vertical scale VM memoria primeiro profiling.

Governança API interna

Catalogo API interno Backstage ou markdown repo openapi yaml review board arquitetura quinzenal nova endpoint justifica duplicacao existente. Sprawl endpoint vira dívida mesma monolito spaghetti classe.

Versionamento evento integração

Schema Avro ou JSON schema version N compatível N-1 consumer. Breaking change increment major fila nova v2 paralela migrate consumer gradual sunset v1 data calendario comunicado parceiros noventa dias antecedencia contrato SLA integração.

Postmortem integração falha template blameless cinco porquês action item owner prazo próximo sprint review — aprendizado organizacional compõe qualidade próximo projeto e-commerce fila dead letter.

Prática adicional TEK Softwares: revise este tópico com stakeholder operacional antes de fechar sprint — alinhamento negócio evita retrabalho custoso em produção fiscal e integrações críticas ERP que atendem milhares documentos eletrônicos mensais sem downtime planejado inadequado.

Documente lições aprendidas DECISIONS.md link artigos relacionados blog tiagoek manutenção longo prazo conteúdo AdSense qualidade leitor desenvolvedor arquiteto tom primeira pessoa experiência vinte anos mercado brasileiro software sob medida impressão 3D marca TEK unificada confiança cliente indicacao orgânica composição juros reputação técnica honestidade entrega previsível pipeline verde segurança prepared statement parametros pentaho cfop correto.

Referência cruzada TEK: combine este guia com práticas de produtividade, pipeline verde e integração ERP documentada nos demais artigos do blog tiagoek — leitura sequencial forma trilha onboarding completa para novos consultores da TEK Softwares em projetos Java, PHP, Pentaho e fiscal brasileiro.

Conclusão

Arquitetura ERP integrações madura equilibra monólito fiscal confiável com bordas modernas API/fila/ETL. Parametrize Pentaho, idempotize webhooks, valide CFOP na entrada, meça tudo. Integração não é afterthought — é metade do valor percebido pelo cliente que emite mil notas/dia sem planilha paralela.