O veredito primeiro: quando etiquetas de envio somem, a transportadora quase nunca é culpada. O pedido morreu em algum ponto da sua própria cadeia de integração, entre o WMS e a API de etiquetas da transportadora. Não comece ligando para a transportadora. Depure nesta ordem: expedição do WMS → camada de API/fila → resposta da transportadora → escrita de status → estação de impressão. Onde quer que o pedido pare, é ali que mora o seu problema. Erre a ordem e você vai queimar três dias sem encontrar nada.
Por que os pedidos "evaporam"
Uma solicitação de etiqueta percorre cinco elos antes de chegar à caixa:
- O WMS gera uma solicitação de envio.
- A camada de integração (ou middleware) a envia à API da transportadora.
- A transportadora devolve os dados da etiqueta e um número de rastreio.
- O WMS escreve o número de rastreio de volta no pedido e o move para "pronto para imprimir".
- A estação de empacotamento imprime a etiqueta e o operador a cola na caixa.
Cada elo pode engolir um pedido: a solicitação nunca sai, apodrece numa fila não consumida, o seu lado esgota o tempo antes de ler a resposta da transportadora, a escrita falha, a impressora está offline. Erros são o caso fácil — pelo menos dá para vê-los. O assassino é a falha silenciosa: seu WMS acha que enviou a solicitação, a transportadora acha que nunca chegou, e o pedido fica no vão, reivindicado por ninguém. É por isso que o armazém grita "pedidos perdidos" enquanto a TI insiste que "os logs parecem bons".
Já vi isso três vezes: duas histórias de guerra
A primeira, em novembro passado, num armazém 3PL de vestuário no leste da China usando a API de etiquetas da UPS. De vinte a trinta etiquetas por dia sumiam, e a transportadora jurava que seu backend nunca recebeu as solicitações. Uma tarde de investigação descobriu: o timeout era de 5 segundos, e na alta temporada a API da transportadora respondia em 8 a 10. Cada timeout fazia o WMS marcar o pedido como "etiqueta falhou" — enquanto a transportadora já tinha gerado a etiqueta e o número de rastreio. Duas histórias, um pedido: o WMS mostrava falhas aguardando reimpressão manual, o faturamento da transportadora já tinha cobrado as etiquetas. Pior, o armazém via "falhou" e clicava em tentar de novo, e a nova tentativa produzia um segundo número de rastreio para o mesmo pedido. Duas etiquetas candidatas por pacote — escolha a errada e é um pacote perdido mais um cliente furioso.
A segunda, em março deste ano, num armazém de e-commerce transfronteiriço no sul da China usando a API de uma transportadora internacional. Pedidos feitos entre meia-noite e 2 AM sumiam em massa; de dia estava tudo perfeito. Causa raiz mais cruel: a API da transportadora tinha uma janela de manutenção noturna que retornava "serviço indisponível", e a camada de integração do WMS não tinha nenhuma fila de falhas. Solicitações falhadas eram simplesmente descartadas — sem nova tentativa, sem alerta, sem registro. Duas horas de pedidos não deixaram rastro no sistema, os pedidos ficaram em "aguardando etiqueta", e o armazém achou que o sistema estava atrasado e esperou até de manhã. Os logs mostraram a verdade: duas horas inteiras de solicitações sequer foram enviadas. A camada de integração as comeu.
Sintomas diferentes, mesma causa raiz: ninguém estava conciliando a cadeia de etiquetas. Dinheiro se concilia. Estoque se concilia. Etiquetas? Trabalho de ninguém.
O manual: uma cadeia de depuração de cinco elos
Este é meu checklist da noite de lançamento. Faço os clientes ticar cada item antes do lançamento.
Passo 1: Verifique o log de expedição do WMS. Confirme que todo pedido enviável tem um registro de solicitação de expedição com número do pedido, peso e dimensões do pacote, e produto de serviço. Se o pedido nunca gerou uma solicitação dentro do WMS, o problema é interno — uma máquina de estados travada, um agendador de expedição morto. Pule a API.
Passo 2: Verifique a fila da camada de integração. Para expedição assíncrona, olhe o atraso da fila, se os consumidores estão vivos, e o que está se acumulando na fila de mensagens mortas (dead-letter queue). Para chamadas síncronas, olhe as configurações de timeout e novas tentativas. O timeout nunca deve ser menor que o teto de resposta do SLA da transportadora — e na alta temporada, dobre com margem. O timeout de 5 segundos do armazém de vestuário foi pego bem aqui.
Passo 3: Verifique a resposta da transportadora. Cada solicitação precisa de um log pareado solicitação-resposta: o que foi enviado, em que timestamp, o que voltou, e o número de rastreio. Registrar a solicitação sem a resposta é o mesmo que não registrar nada — o pior sistema que já vi armazenava apenas as palavras "chamada bem-sucedida", nem mesmo o número de rastreio.
Passo 4: Verifique a escrita de status. Depois que a transportadora devolve um número de rastreio, o WMS deve escrevê-lo de volta no pedido e avançar o status para "pronto para imprimir". Uma escrita falhada deve ir para uma fila de novas tentativas, nunca ser silenciosamente ignorada. A escrita é a zona de maior baixa — em muitos sistemas a solicitação e a escrita são duas transações independentes. A solicitação tem sucesso, a escrita morre, e o pedido flutua no limbo: a transportadora tem, o WMS não.
Passo 5: Verifique a impressora. A impressora da estação de empacotamento fica offline, acaba o papel, o driver quebra, a etiqueta não sai, e o operador clica em "reimprimir". A reimpressão deve seguir o fluxo de reimpressão — o mesmo número de rastreio existente, papel novo. Nunca emita uma nova solicitação de etiqueta, ou um pedido vira dois números de rastreio e a conciliação de fim de mês vira seu pesadelo pessoal.
Passo 6: Concilie a cadeia completa. Após o corte diário, execute uma conciliação em quatro vias: contagem de expedição do WMS = contagem de solicitações da camada de integração = contagem de sucessos da transportadora = contagem impressa. Qualquer diferença são suas etiquetas perdidas, quantificadas. Este script de conciliação deve existir no dia um do lançamento — não depois do primeiro incidente. Escreva tarde e você nem conseguirá responder "quantas perdemos?".
Passo 7: Chaves de idempotência. Cada solicitação de etiqueta carrega uma chave de idempotência globalmente única. Use número do pedido mais sequência do pacote — nunca o número do pedido sozinho, porque pedidos multi-pacote vão colidir. Tanto o lado da transportadora quanto sua própria camada de integração devem deduplicar pela chave. Esta é a única defesa contra "a nova tentativa imprime uma etiqueta duplicada". Não há uma segunda.
| Elo | Sintoma típico | Ação de depuração |
|---|---|---|
| Expedição do WMS | Pedidos presos em "aguardando etiqueta", sem registro de solicitação | Verifique a máquina de estados do pedido, o agendador de expedição |
| Fila da API | Latência crescente, fila de mensagens mortas se acumulando | Verifique a saúde dos consumidores, alertas de profundidade da fila |
| Resposta da transportadora | Timeouts frequentes, falhas esporádicas | Verifique as configurações de timeout, página de status da transportadora, logs pareados |
| Escrita de status | O número de rastreio existe mas o status do pedido não muda | Verifique a transação de escrita, a fila de novas tentativas |
| Estação de impressão | Operadores relatam "nada imprime" | Verifique o status da impressora, use o fluxo de reimpressão, nunca solicite de novo |
Pontos de falha comuns (autoavaliação antes do lançamento)
- Timeout curto demais. Sempre explode na alta temporada. Já vi isso três vezes, e toda vez a história começa com "funcionava bem até a grande promoção".
- Falhas descartadas em vez de enfileiradas. Uma janela de manutenção da meia-noite ou um 500 aleatório da transportadora vira "pedido não encontrado".
- Novas tentativas sem chaves de idempotência. Tentar de novo é gostoso; a conciliação de fim de mês é a ressaca — a transportadora cobra por cada etiqueta duplicada.
- Conciliar dinheiro e estoque, mas não etiquetas. O financeiro fecha, o estoque fecha, e ninguém nota algumas dezenas de etiquetas perdidas até os clientes relatarem pacotes que nunca chegaram.
- Tratar "chamada bem-sucedida" como "etiqueta criada". Um 200 da API da transportadora não significa que uma etiqueta foi gerada. Leia o código de status de negócio dentro do corpo da resposta — transportadoras rotineiramente embrulham uma falha de negócio num HTTP 200.
A parte contraintuitiva
O modo de falha mais perigoso não é um erro — é o falso sucesso. Um erro dispara um alerta e alguém olha. Mas "solicitação enviada, WMS mostra sucesso, transportadora nunca recebeu" pode ficar quieto por semanas e depois detonar na manhã da sua maior promoção. Uma regra se defende disso: o número de rastreio devolvido pela transportadora é a única fonte da verdade. Qualquer pedido sem um é tratado como nunca enviado. Alinhe o armazém e o atendimento ao cliente nisso antes do lançamento, ou os três lados vão discutir sobre isso depois do incidente — com a TI levando a culpa.
Um trade-off merece honestidade: chamadas síncronas versus fila assíncrona. Síncrono é simples — o operador clica em imprimir e sabe o resultado — mas uma resposta lenta da transportadora trava toda a linha de empacotamento. Assíncrono dá vazão e absorve picos, mas a cadeia fica mais longa e a depuração fica duas vezes mais difícil. Minha regra: abaixo de 5,000 pedidos por dia, vá de síncrono com timeouts curtos e uma fila de revisão manual para falhas. Acima disso, vá de assíncrono — mas só depois que a conciliação de cadeia completa e os alertas acima estiverem no lugar. Assíncrono não é bala de prata; ele converte "erro na sua cara" em "conciliação depois do fato". Conciliação fraca torna perdas assíncronas mais difíceis de achar que as síncronas.
APIs de etiquetas parecem tranquilas até as 3 AM do dia da promoção. Imprima este checklist e cole ao lado da estação de empacotamento. É melhor que qualquer dashboard.
Por Lin Xiao, Consultor de Implementação WMS
Traduzido do inglês. Em caso de divergência, prevalece a versão em inglês.
