Vou começar pelo veredito: quando um upgrade de WMS ou OMS dá errado, o sistema em si raramente é o problema. O problema são as integrações de terceiros que ninguém colocou no plano do projeto.
Em 2024, eu estava em uma instalação 3PL de 120.000 pés quadrados em Ontario, na Califórnia, assistindo ao desenrolar de um desastre de upgrade de manual. O armazém estava saindo de uma versão do WMS que usava havia quase uma década. A equipe do projeto passou três meses se preparando: ensaios de migração de dados, treinamento de usuários, percursos de rotas de picking, o pacote completo. O go-live era na segunda-feira às 8 da manhã. Às 9, os telefones não paravam de tocar: as APIs de etiquetas das transportadoras haviam parado de funcionar em conjunto, milhares de etiquetas de remessa estavam presas na fila de impressão, e os separadores ficavam parados, sem nada para fazer, com scanners RF na mão. A causa raiz, quando a encontramos, era quase insultante: a nova versão havia mudado um campo do payload de confirmação de remessa de opcional para obrigatório, e o middleware que falava com o serviço de etiquetas eletrônicas da transportadora tinha sido escrito cinco anos antes por um engenheiro que já havia saído. Ninguém no plano de upgrade sabia que aquele código existia.
Teriam bastado dez minutos para corrigir — se alguém soubesse onde olhar.
Faça o inventário antes de tocar em qualquer coisa
Antes de qualquer upgrade começar, faço a equipe fazer uma coisa primeiro: transformar cada integração de terceiros em uma única planilha de inventário, sem exceções. As colunas são simples: nome da integração, contraparte (qual transportadora, qual marketplace, qual ERP ou TMS), protocolo, quem é dono do código, quando foi a última chamada bem-sucedida e quem chamar quando quebrar.
Essa coluna de «última chamada bem-sucedida» é onde os corpos estão enterrados. Muitas integrações parecem vivas no papel, mas estão efetivamente mortas: um callback de devoluções de uma pequena transportadora de três anos atrás, um arquivo noturno de conciliação enviado para o financeiro que ninguém confere. As integrações mais perigosas durante um upgrade não são as que rodam a cada minuto; são as meio esquecidas. Ninguém se lembra delas, os planos de teste não as cobrem, e mesmo assim algum cron job às 2 da manhã continua invocando-as.
Há um truque grosseiro, mas brutalmente eficaz, para construir esse inventário: puxe 90 dias de chamadas de integração de saída dos seus logs de produção e compare essa lista com a feita à mão. O que não bater é quase certamente algo que você perdeu. Quando aquele armazém de Ontario fez seu post-mortem, esse exercício revelou mais três integrações de que ninguém se lembrava.
Depois, há o problema da documentação. A documentação das APIs dos fornecedores corresponde ao código realmente em produção talvez metade das vezes, se você tiver sorte. Não confie na documentação — confie na captura de pacotes. Antes do upgrade, escolha suas integrações principais (criação de etiquetas, callbacks de confirmação de remessa, sincronização de inventário) e capture um ciclo real de solicitação-resposta de cada uma, campo por campo. Leva menos de um dia e elimina a grande maioria das surpresas do tipo «a documentação dizia que funcionava».
Não aposte o armazém em um único corte
Minha posição sobre compatibilidade de integrações é simples: nunca confie em um corte big-bang. Mesmo o WMS mais maduro pode mudar regras de campos, esquemas de autenticação ou formatos de resposta em uma versão major. Onde as notas de versão dizem «retrocompatível», trato como marketing até eu mesmo testar.
A abordagem confiável tem três partes, e pular qualquer uma delas é pedir por problema: testes de integração no sandbox, rollout por fases e um plano de rollback que funcione de verdade.
Testar no sandbox não significa clicar duas vezes no ambiente de testes. É preciso reproduzir tráfego real do negócio: pegue pedidos de produção, remova os dados sensíveis e dispare o volume de um dia inteiro pelo sandbox. Observe se as etiquetas imprimem, se os callbacks para o ERP têm sucesso, se os números de rastreio voltam a sincronizar com os marketplaces. Se o volume de tráfego for pequeno demais, os problemas ficam escondidos. Eu insisto em pelo menos um dia inteiro de negócio de volume reproduzido, o dobro para armazéns em alta temporada.
O rollout por fases é um teste de nervos e paciência. Direcione 10% do volume de pedidos para a nova versão, observe por meio dia e depois vá aumentando. Algumas pessoas odeiam a lentidão — «é só cortar tudo de uma vez numa janela noturna, é mais limpo». Mais limpo, claro, até uma integração quebrar e o prédio inteiro parar. O trabalho extra de um rollout por fases não é nada comparado a uma parada total da instalação.
E a maioria dos planos de rollback é ficção. Um plano real responde a três perguntas: como os dados voltam (a versão antiga aceitará documentos criados pela nova?), como as integrações voltam (as contrapartes vão disparar callbacks em dobro quando você voltar?) e quem pode decidir (às 3 da manhã, quando algo parece errado, quem tem autoridade para dizer «rollback» sem passar por três camadas de aprovação?). Se você não consegue responder às três, o plano é papel.
No dia do go-live, não olhe a CPU dos servidores. Olhe os sinais vitais das integrações: taxa de sucesso, tempo de resposta e distribuição de códigos de erro de cada integração principal. Um simples alerta na taxa de sucesso vai pegar nove de cada dez falhas de integração bem antes de a primeira reclamação de usuário chegar.
Depois vem a parte que a maioria das equipes pula: a janela de observação de uma semana após o go-live. Metade de todas as falhas de integração são atrasadas. O batch de conciliação financeira de fim de mês só roda uma vez por mês — pode não disparar até semanas depois do upgrade e falhar na primeira execução pós-upgrade. A sincronização de inventário dos marketplaces parece ir bem em volume normal e só quebra quando uma promoção dispara o tráfego. Minha regra é simples: na primeira semana após o go-live, dedique dez minutos toda manhã para revisar o relatório de taxa de sucesso das integrações, prestando atenção especial aos jobs de baixa frequência — eles rodaram, deram erro? Na segunda semana, você pode relaxar para um dia sim, um dia não. Só depois de um mês limpo eu chamo o upgrade de verdadeiramente concluído.
Escreva os critérios de aceite antes do upgrade, não depois. Os meus são três linhas duras: taxas de sucesso das integrações principais iguais ou acima da média da semana pré-upgrade, sem lentidão perceptível no fluxo de ponta a ponta da impressão da etiqueta até a confirmação da remessa, e zero retrabalho manual causado por falhas de integração na primeira semana. Se perder qualquer um deles, ainda há pontas soltas — não estoure o champanhe ainda.
Um último trade-off que vale a pena nomear: algumas integrações legadas deveriam ser reescritas durante o upgrade, não remendadas mais uma vez. Já vi armazéns com middleware empilhado em sete camadas de correções históricas que ninguém ousa tocar. Um upgrade é uma desculpa rara e legítima para pagar essa dívida técnica de uma vez só. Custa duas ou três semanas a mais no cronograma do projeto, mas compra anos de noites bem dormidas. Faça as contas no longo prazo.
Aqui vai a única coisa que você pode fazer amanhã: entre no console de administração do seu WMS e exporte cada integração externa chamada nos últimos 90 dias. Compare com a documentação de integração que você tem arquivada. As que não baterem são seus pontos de explosão mais prováveis no próximo upgrade. Anote os nomes — essa é a linha um do seu checklist de compatibilidade.
Traduzido do inglês. Em caso de divergência, prevalece a versão em inglês.
