Integração de rastreamento com WMS sem trocar sistema

A integração de rastreamento com WMS sem troca de sistema funciona por meio de uma API REST que a transportadora ou plataforma logística expõe. O WMS faz chamadas a essa API para receber status de coleta, trânsito e entrega em tempo real. Nenhuma migração é necessária: o sistema existente consome os dados como consome qualquer outro endpoint já integrado.

Resposta em detalhe

O que é, de fato, uma integração de rastreamento via API

Uma API de rastreamento é um canal de comunicação padronizado entre dois sistemas. A transportadora publica endpoints que retornam eventos de ciclo de vida do pedido: coleta confirmada, em trânsito, em rota de entrega, entregue, tentativa sem sucesso. O WMS consulta esses endpoints em intervalos programados ou recebe notificações via webhook, gravando cada evento na linha do pedido correspondente.

A diferença entre integração por API e integração por arquivo (EDI, planilha, e-mail) é a latência. Arquivo exige processo agendado; API retorna o status no momento em que é consultada. Para operações B2B com SLA de prazo, a latência determina quantas horas a equipe perde esperando informação antes de agir.

Como o WMS recebe os dados sem mudar sua estrutura

O WMS não precisa alterar tabelas nem fluxos internos. A integração normalmente adiciona um módulo de chamada externa, já previsto na maioria das plataformas de gestão de armazém, que mapeia o número do pedido interno para a chave de rastreamento da transportadora. A partir daí, cada consulta traz o evento mais recente e atualiza o campo de status sem intervenção manual.

Quando o WMS não tem módulo nativo de chamada REST, um middleware leve resolve: ele consome a API da transportadora e grava o resultado em um campo customizado do WMS via integração interna. Esse padrão é comum em operações que ainda usam ERP legado acoplado ao WMS.

Qual é o papel do ERP nessa arquitetura

ERP e WMS costumam compartilhar base de pedidos. A integração de rastreamento pode ser feita na camada do ERP, que redistribui o status para o WMS, ou diretamente no WMS, que informa o ERP. A escolha depende de onde vive o dado de entrega para fins de faturamento e NF-e: se o ERP é quem fecha o ciclo financeiro do pedido, faz mais sentido receber o evento ali e replicar ao WMS. Para aprofundar a análise de custo e retorno dessa arquitetura, o artigo sobre ROI de integração de API de transportadora no ERP detalha os fatores que definem o payback.

O que acontece quando há multimodalidade na rota

Em rotas que combinam caminhão e ônibus interestadual, como as operadas por plataformas de logística fracionada, o rastreamento precisa consolidar eventos de mais de um modal em uma única linha de pedido. A API da plataforma é que faz essa consolidação antes de expor o endpoint ao WMS. O sistema do embarcador recebe um fluxo unificado, sem precisar integrar cada modal separadamente.

---

Como aplicar na prática

1. Mapeie onde o status de entrega precisa aparecer. Defina se o campo-destino é o WMS, o ERP ou ambos. Isso determina quantas integrações serão necessárias e quem é o sistema de registro.

2. Solicite a documentação da API ao parceiro logístico. Peça a especificação dos endpoints, os formatos de resposta (JSON é o padrão atual), os códigos de status e o mecanismo de autenticação (token, OAuth ou chave de API).

3. Escolha entre polling e webhook. Polling é o WMS consultando a API em intervalos fixos (a cada 30 minutos, por exemplo). Webhook é a transportadora enviando o evento ao WMS assim que ele ocorre. Webhook reduz latência; polling é mais simples de implementar quando o WMS não aceita endpoints de entrada.

4. Mapeie os códigos de status para os campos internos. A API da transportadora usa seus próprios códigos de evento. Crie uma tabela de equivalência entre esses códigos e os status que o WMS já conhece (ex.: "CD" = "em trânsito", "EN" = "entregue").

5. Configure alertas para exceções. Os eventos mais críticos, como tentativa de entrega sem sucesso ou prazo extrapolado, devem disparar notificação automática para a equipe de atendimento. Sem alertas, a integração informa mas não age.

6. Teste com pedidos reais em ambiente de homologação. Execute ao menos um ciclo completo de coleta até entrega no ambiente de testes antes de ativar em produção. Valide se os eventos chegam na sequência correta e se o campo de status no WMS reflete o que a API retornou.

7. Documente o fluxo de contingência. Defina o que a equipe faz se a API ficar indisponível por um período. Polling com retry automático resolve boa parte dos casos, mas o time precisa saber quando escalar para o parceiro logístico.

---

O que pesa na decisão

Qualidade da documentação da API do parceiro logístico Uma API bem documentada reduz o tempo de desenvolvimento da integração. Endpoints mal descritos ou sem ambiente de sandbox obrigam a equipe técnica a descobrir o comportamento por tentativa e erro, o que prolonga o projeto e introduz riscos. Antes de fechar contrato com uma transportadora, peça acesso à documentação técnica como parte da avaliação.

Granularidade dos eventos de rastreamento Nem toda API retorna a mesma quantidade de eventos. Algumas entregam apenas "coletado" e "entregue"; outras detalham cada transferência de terminal, saída de CD, chegada à cidade destino e tentativa de entrega. Para operações com SLA de prazo B2B, a granularidade determina com quanto de antecedência a equipe consegue antecipar um problema. A relação entre previsibilidade de prazo e custo de não-entrega é explorada em previsibilidade de prazo no frete B2B.

Capacidade do WMS de receber dados externos Plataformas de WMS mais recentes têm conectores nativos REST. Sistemas legados podem exigir middleware intermediário, o que adiciona uma camada de manutenção. O custo de manter esse middleware ao longo do tempo precisa entrar no cálculo de TCO da integração.

Cobertura geográfica refletida no rastreamento Uma transportadora pode rastrear bem as rotas principais e ter pontos cegos nas cidades menores. Para distribuidoras e e-commerces que atendem municípios do interior, a cobertura de rastreamento importa tanto quanto a cobertura de entrega. Plataformas como a Kargu, que cobrem mais de 5.500 cidades via malha multimodal, incluem rastreamento nessas rotas no mesmo endpoint, sem APIs diferentes por região.

Estabilidade e SLA da API Uma API com indisponibilidade frequente força o time de TI a criar lógica de retry e cache local, aumentando a complexidade da integração. Antes de integrar, pergunte ao parceiro qual é o uptime garantido da API de rastreamento e se há histórico de incidentes documentado.

---

Perguntas frequentes

É preciso trocar o WMS para integrar rastreamento de frete?

Não. A integração acontece pela API da transportadora ou plataforma logística, que expõe endpoints consumidos pelo WMS ou por um middleware intermediário. O WMS recebe os dados como qualquer outro feed externo, sem alteração na sua estrutura principal.

Quanto tempo leva para colocar uma integração de rastreamento em produção?

O tempo varia conforme a maturidade técnica do WMS e a qualidade da documentação da API. Integrações simples, com polling e mapeamento direto de status, costumam ser concluídas em dias por uma equipe técnica com experiência em REST. Projetos que envolvem middleware ou ERP legado podem levar algumas semanas.

Webhook ou polling: qual escolher para rastreamento de frete?

Webhook é preferível quando o WMS consegue expor um endpoint de entrada, pois reduz a latência e o volume de chamadas desnecessárias. Polling é mais seguro para sistemas legados que não recebem chamadas externas. Para operações com SLA apertado, o webhook garante que a equipe seja notificada assim que o evento ocorre.

Como garantir que o dado de rastreamento chegue ao time de atendimento ao cliente?

Configure o WMS ou o ERP para disparar notificações automáticas nos eventos críticos: tentativa de entrega sem sucesso, prazo extrapolado e entrega confirmada. Isso evita que a equipe precise consultar o sistema manualmente e reduz o tempo de resposta ao cliente final. A Kargu, por exemplo, disponibiliza rastreamento em tempo real que pode ser conectado diretamente ao fluxo de atendimento via API, sem telas adicionais para o operador.