O essencial primeiro: quando uma integração de WMS com seus sistemas internos (ERP, OMS, financeiro) explode, quase nunca é porque as APIs abertas do WMS são difíceis. Explode porque a equipe confunde "a chamada à API funciona" com "a integração está pronta". Um endpoint leva meio dia; uma integração pronta para produção leva pelo menos duas semanas — a diferença são as cinco armadilhas abaixo, e elas causam a grande maioria das falhas de integração que já vi. Cada armadilha: sintoma → causa raiz → correção → checklist. Copie os checklists para sua lista da véspera do go-live.
Armadilha 1: Sem mapeamento de dados mestres — pedidos lixo na entrada
Sintoma: Ordens de venda enviadas do ERP ao WMS, e o WMS rejeita a maioria como "item não encontrado". Ou pior — o item existe, mas é o errado, e o produto errado é expedido. A sincronização de estoque também quebra: a quantidade disponível do WMS nunca concilia com os livros do ERP.
Causa raiz: Os dois sistemas nunca compartilharam dados mestres. Os códigos de item do ERP foram definidos há uma década com prefixos de fornecedor embutidos; o WMS usa SKUs internos novos. Localizações, transportadoras, clientes — cada tabela de códigos existe duas vezes. Uma API move campos; ela nunca verifica se os significados batem.
Vi exatamente essa falha três vezes. A pior: um 3PL de autopeças na Califórnia entrando em produção antes do pico em novembro de 2024. O ERP identificava itens por código de barras do fornecedor, o WMS por SKU interno, e na primeira semana quase um terço de todos os downloads de pedidos morreu numa fila de exceções — os separadores não viam tarefas enquanto os supervisores viam "expedido". A correção não teve glamour: uma tabela de mapeamento feita de um dia para o outro, validação pré-download, um pool de exceções tratado manualmente e congelamento de downloads até limpar o backlog. Quatro dias de apagar incêndio na primeira semana do pico.
Correção:
- Construa tabelas de mapeamento para os quatro conjuntos de códigos — itens, localizações, transportadoras, clientes — assinadas pelos donos de negócio, não só pelo TI.
- Pré-valide cada interface de saída: um código fora da tabela de mapeamento é rejeitado e registrado — nunca "enviado e tratado depois".
- Reconcilie diariamente códigos novos e desativados entre os dois sistemas, enviando as diferenças por e-mail ao dono dos dados. O pool de exceções tem um dono e um SLA (quatro horas, digamos) — não é uma lixeira.
Lista de verificação: mapeamentos assinados; pré-validação ativa; reconciliação testada; dono de exceções designado.
Armadilha 2: Tratar a API como um tubo em tempo real — limitado na taxa no primeiro dia do pico
Sintoma: Bem nas semanas normais. Aí chega uma promoção ou o fim do mês, as chamadas à API do WMS começam a estourar em massa, a latência de download de pedidos se estica de segundos para dezenas de minutos, e o limitador de taxa do fornecedor pode congelar a integração inteira.
Causa raiz: Um atalho — os sistemas internos consultam a API do WMS diretamente ou empurram em tempo real: checagens de estoque a cada poucos segundos, uma chamada por pedido. Toda API aberta tem um teto de frequência de chamadas (consiga por escrito antes de assinar). Volumes baixos nunca encostam nele; volumes de pico batem de frente. Retentativas sem backoff martelam o endpoint já sobrecarregado.
Correção:
- Coloque uma fila de mensagens entre sua camada de integração e o WMS. Os sistemas internos depositam mensagens; o consumidor chama o WMS num ritmo sustentável. Picos criam backlog, não quebra — lento é melhor que morto.
- Prefira callbacks empurrados pelo WMS a polling para estoque e status de pedidos. Quando precisar de polling, cinco minutos contra cinco segundos quase não muda nada operacionalmente — e é uma ordem de magnitude em carga.
- Chaves de idempotência em cada chamada — a mesma transação empurrada duas vezes executa uma. Retentativas com backoff; depois de três falhas a mensagem vai para uma fila de mensagens mortas.
Lista de verificação: fila implantada; limites de taxa por escrito; idempotência de ponta a ponta; retentativas limitadas.
Armadilha 3: Só o caminho feliz foi codificado — timeouts silenciosamente perdem pedidos
Sintoma: A armadilha mais desagradável. Uma chamada estoura o tempo; o sistema interno assume falha e reenvia — mas o WMS tinha recebido, e só a resposta se perdeu. O mesmo pedido é baixado duas vezes, separado duas vezes. Ou um lote de 100 sai, 97 processam, a interface reporta sucesso geral, e três pedidos somem até o dia da reconciliação.
Causa raiz: O desenvolvimento só testou o fluxo normal. Ninguém definiu o que significa um timeout — sucesso ou falha? Quando um lote tem sucesso parcial, quem analisa o status de cada linha? Nunca foi escrito, nunca foi testado. Antes do go-live todos perguntam "conecta?"; ninguém pergunta "o que acontece quando quebra?".
Correção:
- Defina a semântica de timeout por interface e escreva: leituras podem ser repetidas com segurança; para escritas, verifique o status antes de reenviar após um timeout. Nunca reenvie às cegas.
- Analise respostas de lote linha por linha — registre o resultado de cada documento. O "sucesso" geral não significa que cada linha teve sucesso.
- Rode uma reconciliação diária (os status dos seus sistemas versus os do WMS) com alertas automáticos de divergência, e ensaie as interfaces críticas sob falha — cabos puxados, processos mortos, timeouts simulados — para provar que o sistema se recupera sozinho.
Lista de verificação: semântica de timeout documentada; lote analisado por linha; reconciliação rodando; simulados de falha feitos.
Armadilha 4: Segurança colocada por último — uma chave para governar todas
Sintoma: Uma semana antes do go-live alguém lembra da autenticação. Uma chave é gerada, hardcoded na configuração do programa de integração, e compartilhada pelo ERP, pelo OMS e pelo financeiro. Seis meses depois o desenvolvedor que a construiu sai, a chave sai com ele, e ninguém ousa rotacioná-la.
Causa raiz: Segurança fica abaixo da funcionalidade. "Primeiro fazer funcionar", e a questão da chave é adiada até o go-live — depois do qual é assustador demais para mexer.
Correção:
- Chaves separadas por chamador — ERP, OMS, financeiro têm cada um a sua. Um sistema tem um problema, você revoga a chave dele sem tocar nas outras.
- Mínimo privilégio por chave: uma chave de estoque somente leitura não pode baixar pedidos. Cada chave mora num gerenciador de segredos, nunca em texto puro.
- Rotacione num ciclo (seis meses, digamos), e rode a primeira rotação um mês após o go-live, enquanto todos ainda lembram do procedimento.
Lista de verificação: chaves separadas; mínimo privilégio; gerenciador de segredos; rotação ensaiada.
Armadilha 5: Sandbox funciona, então lançamos — a produção explode naquela noite
Sintoma: 200 pedidos voam no sandbox; 2,000 na noite do go-live esmagam o programa de integração. Ou o WMS do sandbox está atrás da produção por uma release menor, um campo se comporta diferente, e a produção cospe erros de lote a noite toda.
Causa raiz: Sandbox e produção são dois mundos diferentes: dez vezes o volume de dados, dados muito mais sujos, uma rede diferente. Testar só no sandbox é como treinar no pátio da autoescola e depois entrar na rodovia.
Correção:
- Teste de carga a 1.5x do pico antes do go-live — você está estressando seu próprio código e sua fila, não o WMS. Ache primeiro o seu próprio gargalo.
- Rejogue uma regressão completa no sandbox com dados de produção mascarados, caçando dados sujos: códigos faltando, caracteres especiais, campos longos demais — sempre pior do que você imagina.
- Confirme a paridade de versões sandbox/produção e consiga as notas de mudança do fornecedor. Ensaie o rollback: se a integração morrer, você consegue voltar ao manual com uma ação, e como faz o backfill? Todos precisam saber as duas respostas de cor.
Lista de verificação: teste de carga a 1.5x do pico; regressão com dados mascarados feita; paridade de versões confirmada; rollback ensaiado.
Um ponto de vista contraintuitivo
O WMS com a documentação de API mais completa e mais endpoints é o que mais dói durante a integração.
Parece ao contrário, mas se sustenta em mais de 30 projetos. Fornecedores com documentação exaustiva expõem endpoints de granularidade fina — um "download de pedido" dividido em cinco ou seis interfaces, cada uma com campos opcionais. Os implementadores integram "tudo", e quanto mais ampla a superfície, mais armadilhas: a semântica de cada campo para alinhar, cada branch de erro para tratar. O WMS com documentação fina e vinte endpoints centrais força você a ficar só com os fluxos de vida ou morte — download, callback, checagem de estoque. Superfície menor, menos formas de falhar.
Então não se deslumbre com "mais de 200 APIs abertas". Faça três perguntas: endpoints mínimos para os fluxos centrais? Limites de taxa — no contrato? Paridade sandbox-produção — por escrito? Sem respostas, a contagem de endpoints é decoração. O trade-off em uma frase: profundidade de integração e custo de integração sempre escalam juntos. Se cinco endpoints centrais resolvem, não integre cinquenta "direitinho". A superfície de integração é manutenção contínua, não uma entrega turnkey.
Checklist da véspera do go-live
Junte os cinco checklists numa folha. Na véspera do go-live o gerente de projeto percorre com os dois líderes item por item — uma caixa desmarcada, sem go-live:
- Mapeamentos construídos e assinados; pré-validação ativa.
- Fila implantada; limites de taxa por escrito; idempotência de ponta a ponta.
- Semântica de timeout documentada; lote analisado por linha; reconciliação rodando.
- Chaves separadas, mínimo privilégio, gerenciador de segredos, rotação ensaiada.
- Teste de carga a 1.5x do pico, regressão com dados mascarados, paridade de versões, rollback ensaiado.
Vi equipes pulando itens dessa lista achando que "provavelmente vai dar certo" — três vezes, três incidentes de produção. Marcar uma caixa leva um minuto. Apagar incêndio leva a noite toda.
Por Lin Xiao, Consultor de implementação de WMS Traduzido do inglês. Em caso de divergência, prevalece a versão em inglês.
