Central de integrações
| Área | Gestão e integração |
|---|---|
| O que faz | Antes, doze ligações separadas para manter. Agora tudo passa pela central, que traduz e entrega a cada sistema. |
| Funções | Cadastro feito uma vez · Tradução automática · Reenvio automático |
| Habilidades | Mapeamento de sistemas · Integração com ERP · Design de painel · Tratamento de falhas |
O que o sistema cobre.
Central que liga ERP, CRM, loja virtual, estoque e serviços como transportadora e marketplace. Recebe cada mensagem, traduz para um formato comum e entrega ao sistema de destino. Cada sistema se conecta uma vez só. Tudo fica registrado: o que chegou, o que foi enviado, as tentativas e a resposta do outro lado. Serve à TI e à operação.
Para quem
Gestores de TI e operação em empresas com ERP, CRM, loja virtual e estoque em sistemas separados.
O que mudou na empresa
Pedido que sumia entre loja e ERP deixou de ser redigitado. Cada mensagem fica registrada do início ao fim. Sistema fora do ar não trava os outros e a falha aparece no painel.
Módulos e funções.
8 partes do sistema, cada uma com o que faz.
Conectores por sistema
Um conector por ERP, CRM, loja virtual, estoque, transportadora e marketplace, com credencial própria.
Entrada sem duplicidade
Aceita aviso do sistema de origem, consulta agendada ou arquivo. Guarda tudo e ignora mensagem repetida.
Modelo comum de dados
Cada sistema fala do seu jeito. A central converte para um modelo comum antes de entregar.
Tabelas de correspondência
Campos, unidades e códigos de cada sistema em tabelas com versão, alteradas sem programar.
Fila ordenada por pedido
Atualizações do mesmo pedido chegam na ordem certa. Pedidos diferentes andam em paralelo, sem fila única.
Tratamento de falhas
Sistema fora do ar: a central espera e tenta de novo. Dado inválido vai para revisão.
Rastro de cada mensagem
O que entrou, o que saiu, cada tentativa e a resposta do destino. Permite reprocessar.
Painel por conexão
Fila, tempo de resposta, taxa de erro e idade da mensagem mais antiga por conexão.
Três telas.
O design é meu. Cada legenda diz o que a tela faz.
Como funciona por dentro.
Integration Hub é o barramento entre ERP, CRM, e-commerce, WMS e APIs de terceiros: recebe, traduz, enfileira, entrega e guarda o rastro de cada mensagem.
- RecebeWebhook assinado, polling agendado de API externa, transportadora, marketplace, ou arquivo. Valida o HMAC, grava o payload bruto e responde 202 sem processar nada.
- DeduplicaA chave é o id do evento na origem; quando a origem não oferece id estável, chave natural mais hash do payload. Repetição vira no-op e devolve o mesmo resultado da primeira vez.
- NormalizaO formato nativo vira evento canônico versionado. Contrato fora do esperado para aqui, com o motivo no log.
- EnfileiraO hash da chave de negócio escolhe uma de N partições, e cada partição tem um consumidor por vez. Ordem preservada por agregado, sem serializar o barramento inteiro.
- TransformaMapeamento declarativo aplica campos, unidades e de-para de códigos. Enriquecimento consulta as tabelas de correspondência.
- EntregaChamada ao destino com timeout, token bucket e circuit breaker, levando a chave de idempotência no próprio request. O conector fala o dialeto nativo do sistema.
- Confirma ou repeteSucesso grava recibo. Falha é classificada: reagenda com backoff e jitter, repetindo a mesma chave, ou vai para a DLQ com o envelope completo.
- RegistraEntrada, saída, tentativas, latência e trace ficam na trilha. O replay reinjeta o envelope gravado e a deduplicação impede efeito colateral no que já foi entregue.
O problema e a saída.
O problema
Quatro sistemas geram doze integrações ponto a ponto, cada uma escrita por alguém diferente num ano diferente. Sem retry, sem log, sem dono: o pedido some entre o site e o ERP e ninguém prova onde parou. Cliente é e-mail no CRM e CNPJ no ERP.
A saída
Hub-and-spoke, canônico versionado: envelope gravado antes de processar, dedupe por id do evento ou hash, fila por tenant e entidade, entrega com timeout, token bucket e breaker. 429 e 5xx voltam com backoff e jitter; 400 e 422 vão à DLQ. Credencial em cofre.
Arquitetura.
Como as partes se encaixam.
O Hub é um barramento hub-and-spoke. Nenhum sistema conhece outro sistema: cada um conhece o Hub. Na borda ficam os conectores, um por ERP, CRM, e-commerce, WMS e por cada API de terceiro, transportadora, marketplace, gateway -, cada um com credencial, limite de taxa e dialeto próprio. No meio fica um modelo canônico versionado: pedido, produto, cliente, estoque, movimento. O conector de entrada traduz o formato nativo para o canônico; o de saída faz o caminho inverso. É o que troca N² integrações por N conectores.
Toda mensagem vira um envelope: id, origem, entidade, chave de negócio, versão do contrato, trace e o payload bruto intacto. O envelope é gravado antes de qualquer processamento, a resposta ao webhook é um 202 e mais nada. Dali ele entra numa fila particionada na aplicação: o hash da chave de negócio escolhe uma de N partições por tenant e entidade, e cada partição é consumida por um worker de cada vez. Duas atualizações do mesmo pedido não correm em paralelo; pedidos diferentes correm juntos. Ordem onde importa, paralelismo no resto.
A entrega é at-least-once. O worker chama o destino com timeout curto, token bucket por conector e circuit breaker. O erro é classificado antes de qualquer retentativa: 429 e 5xx voltam para a fila com backoff exponencial e jitter; 400 e 422 vão direto para a DLQ, porque repetir payload inválido é só barulho. A deduplicação na entrada usa o id do evento da origem e, quando a origem não emite id estável, a chave natural mais o hash do payload. Na saída, o conector manda uma chave de idempotência no próprio request; quando o destino não aceita chave, consulta o destino pela chave natural antes de recriar, o recibo gravado no Hub só cobre duplicata que o próprio Hub geraria depois de um sucesso confirmado. Cada salto emite trace, então dá para abrir uma mensagem e ver o payload que entrou, o transformado, as tentativas e a resposta crua do outro lado.
Diário de construção.
Por onde comecei, onde travou e o que mudou no caminho.
Comecei pelo envelope e pelo log, não pelo conector. Antes de qualquer integração funcionar já existia a tabela que guarda mensagem recebida, mensagem transformada, tentativa e resposta. Sem isso, todo bug de integração termina em alguém dizendo que acha que o ERP não recebeu.
O primeiro fluxo ponta a ponta foi o mais chato de propósito: pedido do e-commerce para o ERP, com cliente que pode não existir, item fora de linha e frete que muda de nome no meio do caminho. Só depois que esse caso passou é que o mapeamento virou declarativo e os outros conectores nasceram dele. Generalizar antes teria produzido uma abstração bonita e errada.
A parte difícil foi testar sem o sistema do outro lado. Cada conector ganhou modo de replay: o tráfego gravado, request, resposta e cabeçalho, roda contra um stub, e o mesmo lote é reexecutado a cada mudança de mapeamento. Foi assim que apareceu o erro clássico, o destino que grava o registro e depois responde 500. O recibo local não resolve isso: como o sucesso nunca voltou, não há recibo. O conector passou a mandar uma chave de idempotência no próprio request e, nos destinos que não aceitam chave, a consultar o registro pela chave natural antes de recriar.
Tecnologias e o porquê.
| Camada | Escolha | Por quê |
|---|---|---|
| Borda e ingestão | Node + TypeScript com Fastify | Webhook precisa responder rápido e aguentar rajada. O trabalho aqui é I/O puro: validar assinatura, gravar o envelope, devolver 202. |
| Fila | Redis Streams com consumer groups | Consumer group por destino, ack explícito e pending list que já serve de lista de travadas. A partição por chave de negócio é feita na aplicação: hash da chave escolhe um de N streams, e cada stream tem um consumidor por vez. |
| Estado | PostgreSQL | Outbox, recibos de idempotência, tabelas de-para e log de execução particionado por data. É esse histórico que alimenta o replay, e o expurgo vira DROP de partição, não DELETE gigante. |
| Transformação | Mapeamento declarativo versionado | Campo que muda de nome é edição de mapa e publicação de versão, não deploy. O caso exótico cai numa função de escape isolada e testada à parte. |
| Observabilidade | OpenTelemetry, Prometheus e Grafana | Um trace id atravessa do webhook ao ack do destino. As métricas que importam são idade da mensagem mais antiga e taxa de DLQ, não CPU. |
| Credenciais | Cofre por conector, com rotação | Cada conector tem escopo próprio e token rotacionável. Vazar uma credencial não abre o barramento inteiro. |
Decisões de projeto.
At-least-once, não exactly-once
Exactly-once não existe com rede e timeout: parei de prometer. O destino que grava e responde 500 não deixa recibo local, a chave de idempotência foi para dentro do request. Retry sem medo.
Redis Streams e Postgres, não Kafka
Abri mão do replay direto do log e de throughput que o cenário não pede. Em troca, a stack roda sem especialista dedicado e o publish ficou atrás de uma interface.
Ordem por chave, não ordem global
Perdi a ordem entre entidades: o Hub não promete cliente antes do pedido, e o conector cria o que faltar. Em troca, um destino lento não trava a fila de todos os outros.
Escopo.
O que o sistema cobre
- Um ponto de controle para ERP, CRM, e-commerce, WMS e APIs de terceiros
- Webhook assinado, polling agendado de API externa e ingestão de arquivo na mesma esteira
- Retry com backoff, DLQ e replay reinjetando o envelope gravado, com dedupe no caminho
- Mapeamento de campos e de-para versionados, editáveis sem deploy
- Log por mensagem: payload de entrada, transformado, tentativas e resposta do destino
- Painel por conector: fila, latência, taxa de erro e estado do circuito
O que não está publicado
- Nome da empresa e números de operação não são divulgados aqui.
- O código não é público. O que dá para ver: o processo, as telas e as decisões.
Da mesma faixa.
Gestão e integração
Quer ver este sistema de perto?
Mostro o processo que mudou, os módulos, as telas e como foi construído.