Primeiro o veredicto: a solução de problemas de integração API e EDI após o go-live não é consertar o link quebrado o mais rápido possível. É não piorar a situação. Os erros mais caros que já vi não foram causados pela falha original. Foram causados por alguém que entrou em pânico, reenviou tudo, editou o estoque manualmente e reiniciou a interface, transformando uma falha rastreável em uma bagunça que ninguém conseguia reconciliar. Portanto, antes de tocar em qualquer coisa, classifique a falha. A mensagem nunca chegou? Chegou, mas nunca foi processada? Foi processada, mas nunca foi confirmada? Ou três sistemas insistem, cada um, que seus próprios números estão certos? Se errar na classificação, todos os passos seguintes também estarão errados. Já vi essa armadilha três vezes, em três armazéns diferentes, com o mesmo roteiro.

A primeira história é do outono passado, em um armazém terceirizado de artigos para o lar nos arredores de Ontario, na Califórnia. Na terceira semana após o go-live, em uma terça-feira de manhã, o varejista informou que mais de quatrocentos pedidos nunca haviam chegado ao armazém. A pessoa de plantão presumiu que a interface estava fora do ar e a reiniciou duas vezes. Nada mudou. A verificação mostrou que o varejista havia enviado os pedidos e que nosso gateway os havia recebido, mas eles estavam travados na validação de pedidos porque o varejista havia alterado um sufixo em um código de produto sem nos avisar. Nada estava quebrado. Os dois lados simplesmente presumiram que o outro não havia mudado nada. Colocamos os embarques em movimento mapeando temporariamente os códigos antigos e, em seguida, encaminhamos a alteração de código por um processo formal de notificação. Desde então, verifico o log de alterações antes do log do sistema.

A segunda história é mais dolorosa. Um armazém de pequenos eletrodomésticos perto de Chicago passou seu primeiro mês após o go-live com o estoque divergente em mais de cem unidades por dia, às vezes para cima, às vezes para baixo, e ninguém conseguiu encontrar o padrão por uma semana. Eram dois problemas empilhados. As confirmações de devolução estavam sendo enviadas duas vezes pelo sistema do varejista, e nosso lado não tinha verificação de idempotência, de modo que as mesmas devoluções eram lançadas duas vezes. Além disso, os ajustes de contagem cíclica eram digitados diretamente no WMS e nunca devolvidos ao varejista. Cada lado continuava editando seus próprios números, e a diferença só crescia. A solução não foi engenhosa: deduplicar cada mensagem reenviada pelo número do documento comercial e encaminhar cada ajuste de estoque pela interface, em vez de permitir que alguém alterasse uma quantidade e fosse embora. Essas duas linhas estão na minha lista de verificação da noite do go-live desde então.

Falhas de API/EDI: classifique primeiro, depois aja

A classificação cabe em quatro frases, e você deve enquadrar sua falha em uma delas antes de abrir um arquivo de log. Um, a mensagem nunca chegou: não enviada, enviada para o endpoint errado, certificado expirado, interrupção de rede. Dois, chegou, mas nunca foi processada: travada na validação, no mapeamento ou em um campo ausente. Três, foi processada, mas nunca confirmada: o documento comercial foi criado, mas a confirmação nunca voltou, então o remetente presumiu que você nunca o recebeu e o enviou novamente. Quatro, todos discordam: os sistemas de pedidos, embarques e estoque usam definições diferentes, então cada lado parece certo isoladamente.

Dez minutos de classificação podem economizar quatro horas procurando em milhares de linhas de log sem saber que tipo de problema você está procurando. E uma regra: não reinicie uma interface de produção sem evidência. Uma reinicialização apaga o estado das mensagens em trânsito, e um rastro que você poderia ter seguido se torna um rastro que você não pode mais seguir.

Muitos problemas pós-live foram plantados durante a seleção, quando ninguém definiu quem é dono dos dados mestres nem quem detecta uma exceção primeiro. Se você está revisando essas decisões, a comparação de seleção entre API e EDI é uma referência útil para escrever no seu acordo operacional as responsabilidades que você deixou de fora.

Rastreamento de mensagens API/EDI: encontre a mensagem antes de discutir sobre ela

Minha rotina de rastreamento de mensagens tem cinco passos, e eles funcionam nesta ordem. Passo um, leve o número do documento comercial ao sistema do remetente e confirme o registro de envio: foi enviado, para qual endpoint e qual código de resposta voltou? Passo dois, verifique o registro de recebimento do seu próprio gateway e confirme se a mensagem original foi armazenada. Passo três, valide a mensagem original: é um problema de formato, um problema de codificação ou uma regra de negócio que a está bloqueando? Passo quatro, leia o log de processamento de negócio para ver exatamente onde parou e se parou por um erro de sistema ou por uma retenção manual. Passo cinco, verifique o registro de confirmação: uma confirmação foi enviada e a outra parte a aceitou?

Aqui está a parte contraintuitiva: uma resposta de sucesso não significa sucesso de negócio. Muitas interfaces retornam um 200 apenas para dizer "recebido", e não para dizer que o pedido foi criado ou que o estoque foi baixado corretamente. Certa vez, vi duas equipes exibindo logs 200 uma para a outra por dois dias enquanto os pedidos ficavam parados em uma fila de middleware. Julgue pelo status do documento comercial, nunca apenas pelo código de resposta. O código de resposta só prova que a transmissão não quebrou. Não prova que o negócio foi feito corretamente.

Outra falha clássica: a equipe testou apenas o caminho feliz no ambiente de testes e nunca testou um reenvio, uma mensagem fora de ordem ou um campo vazio. Esses três pertencem à lista de verificação da noite do go-live como testes separados. Um reenvio testa a idempotência, uma mensagem fora de ordem testa a máquina de estados do documento e um campo vazio testa se o sistema gera um erro visível ou descarta o documento em silêncio. Descartos silenciosos são o pior dos três, porque um erro pelo menos avisa alguém, enquanto um descarte silencioso só é descoberto quando um cliente reclama.

Pedidos travados: siga esta lista de verificação, caixa por caixa

Quando os pedidos travam, a solução de problemas de integração API e EDI começa com uma regra: não os crie manualmente para salvar o dia. Um pedido criado manualmente resolve o embarque de hoje e garante um problema de reconciliação amanhã, seja um duplicado ou um pedido ausente. Siga esta lista de verificação e exija evidência para cada caixa, uma entrada de log ou um status de documento, e não "acho que foi enviado". O número do documento existe no sistema do remetente? A mensagem chegou ao gateway? Passou na validação? Os códigos de produto e localização foram mapeados? Há estoque suficiente? O documento está em retenção manual?

Depois de encontrar a causa raiz, a ordem do reparo importa. Proteja primeiro os embarques, corrija segundo os dados e discuta por último a culpa. Se for um problema de mapeamento, coloque um mapeamento temporário para proteger os embarques de hoje enquanto a alteração formal tramita. Se for falta de estoque, confirme se a falta é real ou apenas dados de estoque desatualizados antes de liberar o pedido; um atraso de dados pede reconciliação, uma falta real pede o processo de falta, e forçar o pedido não ajuda ninguém. Depois de corrigir um pedido, verifique se o restante do lote compartilha a mesma causa.

Faça as contas do porquê as soluções manuais não escalam. Suponha que quatrocentos pedidos travem em um dia e que cada um leve oito minutos de verificação e tratamento manual. Isso dá 3,200 minutos, mais de cinquenta horas, e duas pessoas trabalhando horas extras ainda assim não terminarão. Quando os pedidos travados passam de certo volume, a resposta certa é corrigir o link e o processo em lote, e não acrescentar pessoas. Acrescentar pessoas transforma um problema de sistema em um problema de mão de obra, e só fica mais caro.

Divergências de estoque: a reconciliação em três passos

Para divergências de estoque, a solução de problemas de integração API e EDI se resume a três passos. Passo um, reconcilie os totais: a quantidade disponível no WMS, a quantidade disponível no outro sistema e a última quantidade com a qual os dois lados concordaram; em seguida, declare o tamanho da diferença e a data em que ela apareceu pela primeira vez. Passo dois, reconcilie os fluxos: da data-base até hoje, compare recebimentos, embarques, devoluções e ajustes como quatro categorias separadas e descubra qual categoria tem uma diferença acumulada igual à diferença total. Passo três, reconcilie os documentos: pegue a categoria com a maior diferença, amostre algumas transações e verifique uma por uma em busca de duplicados, omissões ou diferenças de definição.

Diferenças de definição são a causa mais negligenciada: um lado pode contar o estoque em trânsito como disponível, enquanto o outro não. Os números podem divergir sem que ninguém esteja errado, porque os dois lados não estão contando a mesma coisa. Antes de reconciliar, escreva o que significam disponível, disponível para venda e em trânsito, e faça os dois lados concordarem. Sem definições acordadas, a reconciliação termina com cada lado insistindo que está certo.

Uma última regra operacional. Uma interface não termina no dia do go-live. Os primeiros trinta dias são o período de maior risco, quando o outro lado pode alterar um código, girar um certificado ou mudar uma frequência de envio sem avisar você. Minha prática agora é a reconciliação semanal durante o primeiro mês, mais a rotação de certificados duas semanas antes do vencimento. As operações de interface são vencidas cumprindo essas rotinas pouco glamorosas.

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.