Como integrar uma API de rastreamento de remessas à sua loja de comércio eletrônico
Para integrar uma API de rastreamento de remessas à sua loja de comércio eletrônico, conecte seu sistema de pedidos ao provedor de rastreamento, envie os dados da remessa e da transportadora por meio de uma solicitação segura no servidor, salve os eventos de rastreamento normalizados e exiba o status resultante nas interfaces do cliente e do suporte. Uma implementação confiável é mais do que adicionar um campo de número de rastreamento: ela deve lidar com a seleção da transportadora, atualizações de status, exceções de entrega, novas tentativas, privacidade e a forma como os clientes realmente usam as informações pós-compra.
Este guia explica uma abordagem prática de integração para proprietários de lojas, desenvolvedores e equipes de operações. Ele usa a documentação oficial da Tracking API da 17TRACK como referência, mas os mesmos princípios de planejamento se aplicam ao avaliar outro provedor multitransportadoras.
Decida o que a integração deve alcançar
Comece pelo resultado comercial, e não pelo endpoint da API. A maioria das lojas quer reduzir os contatos do tipo “Onde está meu pedido?”, oferecer aos compradores uma visão clara da entrega e ajudar as operações a identificar remessas atrasadas antes que um cliente reclame. Esses objetivos exigem dados e fluxos de trabalho diferentes.
- Visibilidade para o cliente: exibir o status atual da remessa, informações estimadas de entrega quando disponíveis, detalhes da transportadora e o evento relevante mais recente.
- Visibilidade operacional: permitir que a equipe encontre remessas atrasadas, paradas, devolvidas ou com exceções entre as transportadoras.
- Comunicação automatizada: disparar e-mails, SMS ou outras notificações aprovadas quando uma remessa atingir um estado definido.
- Consistência dos dados: converter diferentes rótulos de eventos das transportadoras em um conjunto menor de status que sua loja possa usar de forma confiável.
Defina esses resultados antes de escolher um método de implementação. Uma API de rastreamento pode fornecer dados da remessa, mas não decide automaticamente quais eventos merecem uma notificação ao cliente ou como sua loja deve lidar com um problema de endereço.
Escolha a arquitetura de integração adequada
Uma arquitetura típica tem quatro camadas: a plataforma de comércio, um serviço de integração, o provedor de rastreamento e a experiência voltada ao cliente. O serviço de integração pode ser uma aplicação de backend, um sistema de gerenciamento de pedidos ou um fluxo de trabalho serverless. Manter essa lógica no servidor geralmente é mais seguro do que colocar as credenciais da API em código executado no navegador.
O fluxo básico é semelhante a este:
- Um pedido pago é processado e recebe um número de rastreamento e uma transportadora.
- Seu backend envia os detalhes da remessa ao provedor de rastreamento.
- O provedor retorna um identificador de rastreamento ou dados de rastreamento de acordo com o design da sua API.
- Seu sistema armazena a referência do provedor e mapeia os eventos da remessa para status internos.
- Um processo de atualização agendado ou uma notificação de evento compatível atualiza a remessa.
- Sua vitrine, página do pedido, ferramentas de suporte e serviço de notificações leem seus próprios dados normalizados.
Não faça com que cada visualização de página consulte a transportadora ou a API de rastreamento. Esse design pode criar experiências lentas para os clientes, solicitações duplicadas, problemas de limite de requisições e resultados inconsistentes. Armazene em seu banco de dados o estado de rastreamento mais recente aceito e atualize-o por meio de tarefas em segundo plano controladas ou do mecanismo de atualização compatível do provedor.
Confirme a documentação do provedor antes de programar
Antes da implementação, consulte a documentação oficial da API do provedor sobre autenticação, formatos de solicitação, campos de resposta, transportadoras compatíveis, comportamento de erros, mecanismos de atualização e requisitos da conta. A 17TRACK fornece uma página do produto Tracking API dedicada e uma documentação para desenvolvedores. Considere essas páginas como a autoridade sobre o comportamento atual da API, em vez de confiar em exemplos copiados de fóruns ou tutoriais antigos de integração.
Crie uma breve lista de requisitos com base na documentação:
- Como as credenciais da API são emitidas, armazenadas, alternadas e revogadas?
- A solicitação exige um código de transportadora ou o serviço pode identificar a transportadora pelo número de rastreamento?
- Quais campos de resposta identificam a remessa, o status, a localização, os registros de data e hora e a mensagem de exceção?
- Como as atualizações assíncronas são entregues, se a conta for compatível com elas?
- Quais são os limites de solicitações documentados, as regras de cobrança, as expectativas de tempo limite e os códigos de erro?
- Como devem ser tratados números de rastreamento duplicados, números inválidos, transportadoras desconhecidas e remessas entregues?
Não deduza um recurso pelo nome de um produto. Por exemplo, “tempo real” pode descrever uma declaração de posicionamento do produto, e não uma garantia de que todos os eventos da transportadora aparecerão imediatamente. Sua implementação deve explicar que as leituras da transportadora podem sofrer atrasos e que uma API não pode criar uma leitura que a transportadora ainda não informou.
Prepare os dados do pedido e da remessa
Normalmente, o momento mais útil para criar o rastreamento é o processamento da remessa, e não a criação do pedido. Um pedido pode estar pago, mas ainda não embalado, e um número de rastreamento pode ser gerado antes de o pacote ser aceito pela transportadora. Decida qual evento do seu fluxo de processamento deve criar o registro de rastreamento.
No mínimo, seu registro interno de remessa deve distinguir os seguintes valores:
- ID interno do pedido e ID do processamento
- Número de rastreamento
- Nome ou código da transportadora
- País ou região de destino, quando operacionalmente necessário
- ID de rastreamento do provedor ou referência de assinatura, se retornado
- Status normalizado atual
- Registro de data e hora do último evento e da última sincronização
- Resposta bruta do provedor ou uma referência de auditoria controlada
Mantenha os dados do pedido e os dados da remessa separados. Um pedido pode conter vários pacotes, remessas divididas ou transportadoras diferentes. A suposição de uma relação de um pedido para um único número de rastreamento geralmente falha quando um armazém envia os itens separadamente.
Use um processo idempotente. Se o sistema de processamento repetir a mesma solicitação, a integração deverá atualizar a remessa existente em vez de criar assinaturas ou mensagens duplicadas para o cliente. Uma chave de idempotência prática pode combinar seu ID interno de processamento, o identificador da transportadora e o número de rastreamento, sujeita aos próprios requisitos do provedor.
Normalize os status das transportadoras para os clientes
As transportadoras usam rótulos e sequências de eventos diferentes. Sua loja deve manter um modelo interno pequeno de status, como Informações recebidas, Em trânsito, Saiu para entrega, Entregue, Exceção e Devolvido. Preserve o evento original da transportadora para a equipe de suporte, mas use o status normalizado na lógica da vitrine.
As regras de normalização devem ser explícitas. Um evento de “etiqueta criada” não deve ser apresentado como prova de que o pacote está em movimento. “Entregue” deve ser tratado como um evento informado pela transportadora, e não como uma garantia de que o cliente localizou fisicamente o pacote. Uma exceção não deve ser convertida silenciosamente em “em trânsito” apenas porque a remessa poderá continuar mais tarde.
Defina também a precedência dos status e o tratamento de regressões. Um feed atrasado da transportadora pode chegar fora de ordem. Compare os registros de data e hora dos eventos quando disponíveis, registre o evento bruto e evite substituir um estado mais recente de entregue por um estado mais antigo de em trânsito. Se os registros de data e hora estiverem ausentes ou forem ambíguos, sinalize o registro para uma atualização conservadora em vez de inventar uma sequência.
Crie o fluxo de solicitações no servidor
Seu backend deve validar os dados de processamento recebidos antes de chamar o provedor de rastreamento. Verifique se o número de rastreamento está presente, remova espaços em branco acidentais, valide o formato esperado quando apropriado e confirme se o valor da transportadora é aceitável. Não rejeite números de rastreamento incomuns, mas válidos, apenas porque não correspondem a um padrão local restrito.
Um fluxo de solicitação independente do provedor pode ser representado assim:
receive fulfillment event
validate order and shipment fields
check for an existing idempotency key
send the documented tracking request from the server
store the provider response and internal shipment record
queue a refresh or process the supported update event
publish only approved fields to the storefrontUse tempos limite curtos, novas tentativas limitadas e recuo exponencial para falhas temporárias. Não repita todas as solicitações em caso de erro. Uma falha de autenticação, uma solicitação inválida ou uma transportadora não compatível geralmente exigem correção, e não chamadas repetidas. Registre um ID de correlação, o resultado da solicitação e a categoria do erro do provedor, mas evite gravar chaves de API, endereços completos de clientes ou informações pessoais desnecessárias nos logs da aplicação.
Mantenha a resposta do provedor separada do modelo voltado ao cliente. Isso facilita a troca de provedores, a correção de uma regra de mapeamento e a limitação das informações expostas por meio de uma página pública de pedidos.
Projete a experiência de rastreamento do cliente
Uma página de rastreamento deve responder rapidamente a três perguntas: qual é o estado atual, o que aconteceu mais recentemente e o que o cliente deve fazer em seguida? Exiba a referência do pedido, o número da remessa de forma consciente em relação à privacidade, o nome da transportadora, o horário do evento mais recente e uma explicação clara para as exceções.
Não mostre uma linha do tempo vazia como se fosse uma falha técnica. Antes da primeira leitura da transportadora, explique que as informações de envio foram recebidas e que o movimento talvez ainda não esteja visível. Para uma exceção, forneça uma explicação em linguagem simples somente quando os dados de origem a sustentarem. Se a transportadora informar um problema de endereço, inclua um link para o processo de suporte ou para a ação de atendimento ao cliente que sua empresa realmente possa oferecer.
Para lojas desenvolvidas no Shopify ou em outra plataforma de comércio, verifique como os eventos de processamento, as contas dos clientes, as páginas de status dos pedidos e os modelos de notificação são disponibilizados pela plataforma. A documentação oficial para desenvolvedores do Shopify inclui recursos para webhooks e dados de processamento. As APIs da plataforma e a documentação versionada podem mudar; portanto, confirme a versão usada pela sua aplicação antes do trabalho em produção.
Use as notificações com cuidado
Os eventos de remessa são gatilhos úteis, mas enviar uma mensagem para cada leitura da transportadora pode causar fadiga de notificações. Defina regras comerciais como notificar na criação da remessa, em um progresso relevante em trânsito, quando sair para entrega, na entrega e em exceções selecionadas. Suprima duplicatas e adicione um intervalo mínimo para mensagens repetidas de atraso.
Separe os alertas operacionais das notificações aos clientes. Uma equipe de suporte pode precisar saber que uma remessa não mudou por vários dias, enquanto um cliente talvez precise de uma mensagem apenas quando a transportadora informar uma exceção concreta. O limite de tempo deve refletir o nível de serviço, o destino, a transportadora e o método de envio, em vez de um número universal sem base operacional.
Teste com cenários reais de entrega
Uma resposta bem-sucedida para um número de rastreamento não é suficiente para um lançamento em produção. Crie uma matriz de testes que inclua várias transportadoras, países, tipos de remessa e estados de eventos. Teste pelo menos:
- Uma remessa recém-criada sem leitura da transportadora
- Uma remessa normal em trânsito
- Uma remessa que saiu para entrega
- Uma remessa entregue
- Uma exceção ou evento relacionado a endereço
- Uma remessa devolvida
- Um número de rastreamento inválido
- Um evento de processamento duplicado
- Uma resposta atrasada do provedor ou um tempo limite
- Um evento fora de ordem
Meça mais do que a disponibilidade da API. Verifique se o pedido correto é atualizado, se o cliente vê uma linguagem compreensível, se as notificações duplicadas são suprimidas e se a equipe de suporte consegue identificar o evento original da transportadora. Faça primeiro uma implementação limitada, mantenha uma alternativa operacional e monitore as categorias de erro após o lançamento.
Segurança, privacidade e manutenção
Armazene as credenciais em um gerenciador de segredos ou em uma variável de ambiente protegida, não no código do tema, no código móvel, no controle de versão ou em solicitações do navegador. Restrinja o acesso aos dados das remessas por função, use HTTPS e revise por quanto tempo as respostas brutas e os campos relacionados aos clientes são mantidos.
Revise regularmente a documentação do provedor e a versão da API da sua plataforma de comércio. O suporte às transportadoras, os nomes dos eventos, os requisitos de autenticação e o comportamento dos webhooks da plataforma podem mudar. Mantenha as regras de mapeamento de status configuráveis, documente as suposições por trás delas e possibilite repetir ou reconciliar uma remessa sem enviar outra mensagem ao cliente.
A API da 17TRACK é uma opção relevante a ser avaliada quando sua loja precisa de uma integração de rastreamento dedicada entre transportadoras. A escolha adequada ainda depende das transportadoras que você usa, dos países atendidos, do comportamento das atualizações documentado para sua conta, do volume esperado de solicitações e dos controles operacionais exigidos pela sua equipe. Confirme esses pontos na documentação oficial e em uma prova de conceito controlada antes de assumir um design de produção.
FAQ
O rastreamento deve ser criado quando o pedido é feito?
Geralmente, não. Crie ou ative o registro da remessa quando o fluxo de processamento tiver uma transportadora e um número de rastreamento. Criá-lo no checkout pode gerar registros para pedidos que sejam cancelados, não processados ou divididos posteriormente.
Uma API de rastreamento pode garantir informações de entrega em tempo real?
Não. Nenhuma API pode garantir que todas as leituras das transportadoras ficarão visíveis imediatamente. O provedor depende dos dados da transportadora, e os sistemas das transportadoras podem informar eventos com atrasos ou lacunas. Apresente os registros de data e hora e a linguagem dos status com precisão e evite prometer um tempo exato de atualização, a menos que a documentação relevante e o acordo de serviço sustentem essa promessa.
O navegador deve chamar diretamente a API de rastreamento?
Na maioria das implementações, não. Use uma integração no servidor para manter as credenciais protegidas, normalizar as respostas, controlar as novas tentativas e filtrar os dados voltados ao cliente. Normalmente, a vitrine deve ler uma visualização aprovada da remessa a partir da sua aplicação.
Como uma loja deve lidar com vários pacotes em um pedido?
Modele cada processamento ou pacote como uma remessa separada, mantendo o ID do pedido principal. A página do pedido pode mostrar um resumo geral e linhas do tempo separadas para cada pacote. Isso evita ocultar um pacote atrasado por trás do status de entregue de outro pacote.
Qual é a primeira métrica de produção a monitorar?
Monitore o fluxo completo desde a criação do processamento até uma atualização correta visível ao cliente. O sucesso da API, por si só, não é suficiente. Acompanhe registros duplicados, remessas desatualizadas, eventos não mapeados, falhas de notificação e a porcentagem de remessas que exigem correção manual.
