Verdict first: nas implantações de OMS, todo mundo olha para a lista de funcionalidades e para a documentação da API, mas o que derrete a linha de suporte costuma ser o item de configuração mais entediante — a máquina de estados do status do pedido. Configure errado as transições e os pedidos começam a "sumir", "congelar" e "voltar à vida", enquanto suporte, armazém e finanças contam, cada um, uma história diferente. Vi essa falha exata três vezes, cada uma diferente.
Por que a máquina de estados do status do pedido importa tanto
O status do pedido é a única língua que todos os papéis compartilham. O suporte consulta, o armazém trabalha com base nele, as finanças liquidam contra ele, o cliente o vê na página de rastreamento. A máquina de estados do status do pedido é o livro de gramática — que estado vai para onde, quem o move, para onde vai um pedido travado.
Erre a gramática e ninguém fala a mesma língua. O armazém diz "enviado", o suporte ainda vê "Alocado", o cliente pergunta "onde está meu pedido" e o suporte só consegue dizer "deixa eu verificar" — e depois corre para perguntar ao armazém num grupo de chat. Não é um suporte pouco profissional. A máquina de estados a traiu primeiro.
Dos meus três colapsos, aqui estão os dois mais instrutivos.
Colapso um: estados congelados, centenas de pedidos "somem"
Há dois anos, liderei um go-live de OMS para um 3PL da Califórnia que movimentava vários milhares de pedidos por dia, com o lançamento duas semanas antes do pico do Thanksgiving. No terceiro dia, a líder de suporte ligou: "Lin Xiao, um lote de pedidos está travado em 'Alocado' no seu sistema, mas o armazém diz que a mercadoria foi enviada ontem."
Causa raiz: quando o picking terminava, o WMS devolvia "picking concluído", mas nossa máquina de estados tinha "Alocado" transitando para "Em picking" — e a tabela de mapeamento de eventos do WMS não tinha nenhum valor para "Em picking". Os dois documentos de integração foram escritos de forma independente, e o UAT cobriu apenas o caminho feliz. Ninguém percorreu cada evento que o WMS podia enviar através da máquina de estados do OMS para confirmar que cada um tinha uma saída.
Resultado: centenas de pedidos congelados em "Alocado". O suporte via "Alocado" em todo lugar, o armazém já tinha enviado há muito tempo, o rastreamento da transportadora mostrava "coletado" — três fontes, três histórias, e a linha de suporte derreteu.
A correção não foi glamourosa: aplicamos um patch no mapeamento de eventos de madrugada e depois escrevemos um job de conciliação que atualizou em massa os pedidos travados para seu progresso real no WMS. Dois dias e duas noites. Salvamos a operação, mas a primeira onda da experiência do cliente na temporada de pico tinha ido embora. Essa lição entrou em cada checklist desde então: a tabela de mapeamento de eventos deve se alinhar à máquina de estados linha por linha. Nem uma linha pulada.
Colapso dois: ramificação de cancelamento ausente, pedidos "voltam à vida"
Outro cliente, uma marca DTC, tinha uma bela máquina de estados com um único fluxo para frente: Revisão pendente → Alocação pendente → Alocado → Em picking → Embalado → Enviado → Entregue. Quando um cliente cancelava, o OMS enviava uma instrução de interceptação ao WMS — mas a máquina de estados não tinha nenhum estado de "Interceptando", "Interceptado" ou "Interceptação falhou".
A interceptação chegou ao armazém, mas a tarefa de picking já tinha sido liberada, e o operador nunca viu a marca de interceptação (o status da tarefa do WMS e o status do pedido do OMS são duas coisas diferentes). A mercadoria foi enviada de qualquer forma. O OMS mostrou "Cancelado" e o reembolso saiu. Resultado líquido: o cliente recebeu um pedido "já cancelado", a empresa absorveu o frete de devolução e o suporte teve que explicar por que um pedido cancelado continuava chegando.
Vi essa falha exata três vezes. Cada cliente diz "não achamos que o cancelamento precisava de estados". Minha resposta é sempre a mesma: o cancelamento não é o fim de um status. O cancelamento é uma ramificação inteira.
O checklist de três tabelas para projetar a máquina de estados do status do pedido
Depois de cicatrizes suficientes, agora configuro a máquina de estados de cada projeto a partir destas três tabelas. Copie-as diretamente.
Tabela um: o fluxo principal — a vida normal de um pedido. Cada linha precisa de quatro colunas: o estado, quem o move, para onde vai no timeout e para onde pode voltar.
- Revisão pendente: movido pela automação do sistema ou por um humano; expira para revisão manual; este é o início, sem retorno.
- Alocação pendente: movido pelo waving ou pelo motor de regras; vai para Em espera quando falta estoque; volta para Revisão pendente se a revisão for rejeitada.
- Alocado: movido pelos callbacks do WMS; vai para exceção quando o WMS fica em silêncio por tempo demais; volta para Alocação pendente quando a alocação é liberada.
- Em picking: movido pelos callbacks do WMS; expira para uma exceção de picking; volta para Alocado quando a tarefa é cancelada.
- Embalado: movido pelos callbacks do WMS; volta (com aprovação) quando uma interceptação tem sucesso e a mercadoria retorna ao staging.
- Enviado: movido pelos callbacks da transportadora ou do WMS; o último ponto rastreável antes da linha de chegada.
- Entregue: movido pelos callbacks da transportadora; o fim.
Tabela dois: os estados de ramificação — cancelamento e interceptação têm sua própria faixa.
Cancelamento solicitado → Em revisão → Cancelado, ou Cancelamento rejeitado (de volta ao estado original). Interceptando → Interceptado (mercadoria de volta a Embalado, aguardando tratamento) → Interceptação falhou (o fluxo original continua, o suporte intervém).
O ponto-chave: cancelamento e interceptação são duas ações diferentes — nunca as funda em um único status. "Cancelado" é o resultado para o dinheiro e o pedido; "Interceptado" é o resultado para a mercadoria física. Cancelar depois que a mercadoria foi enviada versus cancelar antes de qualquer movimento são duas situações completamente diferentes, e os estados devem ficar separados. Funda-os e você vai ter histórias de fantasma como "um pedido cancelado foi enviado".
Tabela três: os estados de exceção — uma saída de emergência para cada estado.
Revisão rejeitada, Em espera por falta de estoque, Exceção de endereço, Exceção de pagamento, Timeout de callback do WMS, Exceção da transportadora. Cada estado de exceção recebe três atribuições: quem é o dono, o SLA de tratamento e para quem escala quando não pode ser resolvido. Um estado de exceção sem dono é o mesmo que não tê-lo.
Ao configurar cada estado, faça três perguntas — esta é uma página fixa no meu checklist da noite do go-live:
- Quem move este estado? Um estado sem dono vai congelar. Movido pelo sistema: documente qual job e sua programação. Movido por humano: documente qual papel.
- Para onde ele vai no timeout? Cada estado precisa de uma saída por timeout — sem ela, você está plantando uma mina para o seu eu futuro.
- Para onde ele pode voltar, e o retorno precisa de aprovação? O retorno é a parte mais esquecida de uma máquina de estados, mas acontece diariamente em produção.
As três formas mais comuns pelas quais máquinas de estados do status do pedido falham
Primeira, eventos e estados estão desalinhados. Os estados do OMS são movidos por eventos externos — callbacks do WMS, da transportadora, de pagamentos — e cada evento deve mapear exatamente uma transição. Projetos que testam apenas o caminho feliz falham aqui mais cedo ou mais tarde. A correção: liste cada evento que os sistemas externos podem enviar, percorra cada um através da máquina de estados e corrija as lacunas na hora.
Segunda, o status de exibição e o status de workflow se misturam. O suporte quer a visão voltada ao cliente, o armazém precisa da visão operacional, as finanças precisam da visão de liquidação. Forçar as três em uma única máquina de estados deixa todo mundo irritado. A correção: a máquina de estados do workflow lida apenas com as transições internas; uma tabela de mapeamento separada de "status visível ao cliente" lida com a exibição. Duas tabelas — uma fonte da verdade, uma camada de tradução.
Terceira — contraintuitivo — uma máquina de estados mais fina não é melhor. Uma vez vi um projeto com mais de trinta estados; o suporte treinou três dias e ainda não conseguia pesquisar pedidos, e cada novo contratado memorizava um diagrama de transição. As máquinas de estados de produção mais estáveis rodam com cerca de uma dúzia de estados entre fluxo principal e ramificações. Estados extras são decoração, e a decoração cobra aluguel de manutenção: cada estado precisa de um timeout, um caminho de retorno, permissões e casos de teste. Cada estado adicionado não soma custo — multiplica.
Mais um trade-off: a proporção de transições automáticas em relação à confirmação manual. Mais automação, mais eficiência, exceções mais difíceis. Meu piso: revisão, interceptação e grandes reembolsos sempre mantêm confirmação humana. Quer automação total? Termine primeiro a lógica de fallback da ramificação de exceção.
Execute este checklist na noite do go-live
Na noite do go-live, faça três coisas: percorra cada estado no ambiente de teste e pergunte "o que acontece se ele travar aqui"; confirme que cada evento externo tem uma saída na máquina de estados; execute as ramificações de cancelamento e interceptação três vezes cada — é aí que os colapsos moram.
Se não conseguir responder, não entre em produção hoje à noite. Duas horas extras na máquina de estados antes do lançamento economizam vinte chamadas de reclamação depois. Fiz essa conta três vezes. Vale a pena sempre.
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.
