A etiqueta foi impressa. A encomenda nunca foi enviada. Nove em cada dez vezes, o pedido morreu em algum ponto da cadeia de API.
Durante a alta temporada de 2023, um 3PL de Los Angeles me ligou. Estavam processando 12,000 pedidos por dia, impressoras de etiquetas rodando sem parar — mas toda noite, a contagem real de coletas da transportadora saía mais de 300 encomendas abaixo da contagem de enviados do sistema. Reclamações, reembolsos, reenvios: vários milhares de dólares queimados todos os dias. A separação estava bem. A impressão estava bem. Cada pedido perdido tinha morrido na cadeia entre o WMS e a API de etiquetas da transportadora.
Meu veredito adiantado: etiquetas perdidas quase nunca morrem na impressora. Os verdadeiros assassinos são três: a solicitação nunca saiu do seu prédio, uma nova tentativa após timeout criou etiquetas duplicadas, ou ninguém estava reconciliando. Esta cadeia de solução de problemas vem de anos integrando APIs de etiquetas de transportadoras. Siga-a em ordem e você vai achar a ruptura.
Passo um: a solicitação chegou a sair do seu prédio?
A forma mais boba de perder um pedido é o seu WMS nunca enviar a solicitação — ou enviá-la, não receber nada de volta, e presumir que deu certo.
Meu primeiro movimento é sempre o log local de solicitações. Não o status do pedido no WMS — os registros de chamadas do gateway de saída. Para este pedido, há um registro de uma chamada de "solicitação de etiqueta à transportadora"? Se não há, pare de ler a documentação da API e de ajustar timeouts. O problema está do seu lado. Os suspeitos de sempre: um consumidor de fila de mensagens morto com a fila se acumulando em silêncio, um job agendado que nunca iniciou, ou um pedido travado numa transição de status — o OMS empurrou o pedido, mas o WMS ainda aguardava a liberação da onda, então a solicitação de etiqueta nunca disparou. Já vi isso mais de uma vez: caos de alta temporada, uma política de onda mal configurada, e algumas centenas de pedidos sentados em silêncio em "aguardando liberação" enquanto a solicitação de etiqueta nem sequer tinha sido enviada.
Há uma variante mais traiçoeira: a solicitação saiu, mas o log não a capturou. Alguns sistemas só registram sucessos. Outros giram os logs com tanta agressividade que os minutos que importam já sumiram. Minha regra permanente para os clientes: registre cada chamada à API de etiquetas por completo — o que foi enviado, quando, o que voltou, quanto demorou. Quando você discute com uma transportadora uma divergência de faturamento ou trata uma reclamação de cliente, o log é sua única evidência. Com logs incompletos, ninguém pode ajudar você a achar a ruptura.
Então o veredito do passo um é simples: sem registro no log, o problema está dentro das suas próprias paredes — conserte primeiro a cadeia interna. Com registro, siga em frente.
Timeouts são o verdadeiro assassino: a transportadora pode já ter criado a etiqueta
Esta é a forma mais letal e mais injusta de perder um pedido.
A cena: o WMS chama a API de etiquetas da transportadora, a transportadora demora demais, a chamada estoura o timeout (cada transportadora é diferente — siga a documentação dela), então o WMS marca como expirada e tenta de novo automaticamente. A segunda chamada dá certo, a etiqueta volta, todos comemoram — exceto que a primeira solicitação já tinha criado a etiqueta do lado da transportadora. A resposta simplesmente nunca voltou. Agora este pedido tem duas etiquetas e dois números de rastreio.
Duas consequências. Primeira: você paga duas vezes: algumas transportadoras cobram por etiqueta criada, e o processo de anulação delas é doloroso o bastante para que armazéns pequenos nunca se deem ao trabalho de anular uma por uma — o dinheiro vaza em silêncio. Segunda: o armazém só cola uma etiqueta numa encomenda e a envia. A outra vira uma etiqueta fantasma — criada no sistema, rastreável pelo cliente, mas a encomenda jamais mostrará um scan de coleta. O atendimento ao cliente pesquisa: número de rastreio válido, zero eventos de rastreio. Ninguém consegue explicar. Você absorve o custo e reenvia. O mais enlouquecedor: o WMS parece normal, o rastreio da transportadora parece "normal" — os dois lados normais, e a carga nunca se moveu.
A solução são duas palavras: idempotência e política de novas tentativas.
Idempotência significa que cada solicitação de etiqueta carrega uma chave única de negócio — número do pedido mais sequência do pacote, por exemplo — e a API da transportadora devolve a mesma etiqueta para solicitações repetidas com a mesma chave. Confirme isso com a transportadora durante a integração. Algumas APIs não ativam a idempotência por padrão; é preciso pedi-la no contrato ou na configuração. Enviar novas tentativas sem ela é plantar sua própria mina. Deixe isso escrito no contrato durante a negociação, não depois que algo quebrar.
Política de novas tentativas significa nunca reenviar às cegas após um timeout. Minha abordagem: no primeiro timeout, consulte primeiro a transportadora — use a referência do pedido ou do pacote para verificar se a etiqueta foi de fato criada. Se foi, use a existente. Só reenvie se não foi. Uma consulta custa muito menos do que limpar uma pilha de etiquetas fantasmas. Limite suas tentativas, espaçe-as, e não insista enquanto o sistema da transportadora já está sofrendo. Na alta temporada a API da transportadora já está lenta — novas tentativas cegas só a deixam mais lenta, um ciclo vicioso.
E a impressora? Ela raramente perde pedidos. Uma etiqueta impressa mas nunca aplicada, ou aplicada na encomenda errada — isso é gestão de piso, resolve-se com câmeras e registros de separação, não é um problema de API. Dos pedidos que morrem na cadeia de API, nove em cada dez morrem na palavra "timeout".
Rode a reconciliação todo dia e deixe-a pegar todo o resto
Os dois primeiros passos são "como investigar quando algo quebra". Este é "como saber na hora quando algo quebra".
Por mais sólida que seja a cadeia, insisto que os clientes rodem um job diário de reconciliação. A lógica são três linhas: puxe a contagem de etiquetas criadas da transportadora (via API de reconciliação ou download de faturamento), puxe a contagem real de enviados do WMS, combine-as por pedido ou número de rastreio, e a diferença são seus pedidos perdidos. Cuidado com as definições: exclua etiquetas anuladas, reconcilie cada transportadora separadamente — não conte as etiquetas da transportadora A contra a transportadora B — e rode num horário fixo todo dia. Costumo recomendar de manhã cedo, fora da janela de liquidação da transportadora.
Como definir o limiar de alerta? Minha regra de bolso: alerte quando a diferença passar de 0.5% do volume do dia; ligue para o telefone de alguém quando passar de 2%. Não alerte por qualquer diferença — as transportadoras às vezes criam etiquetas em lote, como processamentos de liquidação noturnos, então uma etiqueta criada hoje pode não entrar no arquivo de faturamento até amanhã. Tolerância zero só treina todo mundo a ignorar os alertas, e aí ninguém olha quando realmente importa. Um limiar existe para ser usado, não adorado — sensível demais é o mesmo que não ter nenhum.
Aquele 3PL de Los Angeles sobreviveu graças a este job de reconciliação. Antes dele existir, eles nem conseguiam dizer quantos pedidos perdiam por dia — essa é a parte mais assustadora, não saber o tamanho do problema. Depois que entrou no ar, os pedidos perdidos caíram de mais de 300 por dia para um dígito, e os poucos restantes eram encomendas mal etiquetadas no piso — nada a ver com a API. Toda manhã, a operação começa o dia com o relatório de reconciliação. Qualquer diferença é investigada no mesmo dia. Problemas não passam a noite.
Lembre-se desta cadeia: primeiro os logs, depois os timeouts, depois a impressora — e reconcilie todo santo dia.
Traduzido do inglês. Em caso de divergência, prevalece a versão em inglês.
