Como usar APIs de rastreamento de remessas para enviar notificações proativas de entrega
Para enviar notificações proativas de entrega com uma API de rastreamento de remessas, conecte cada pacote ao seu pedido, ingira as atualizações de rastreamento, traduza essas atualizações em eventos relevantes para o cliente e acione mensagens por meio do seu serviço de e-mail, SMS ou notificações do aplicativo. Coloque uma fila durável e verificações de duplicidade entre os dados de rastreamento recebidos e as mensagens enviadas, para que atualizações repetidas ou atrasadas não gerem alertas confusos.

Este guia é destinado a desenvolvedores e equipes de operações de comércio eletrônico que estejam criando esse fluxo de trabalho. O objetivo não é encaminhar cada leitura da transportadora. É informar aos clientes quando algo significativo mudar, o que essa mudança significa e se eles precisam tomar alguma medida.
Projete o fluxo de notificações antes de conectar a API
Uma API de rastreamento de remessas fornece informações de rastreamento; seu aplicativo decide como usá-las. Trate a visibilidade da remessa e a comunicação com o cliente como responsabilidades separadas, mesmo que o serviço escolhido ofereça ambas.
Uma arquitetura prática tem seis etapas:
- Associação do pedido: conecte um número de rastreamento e o identificador da transportadora, quando necessário, a um registro interno da remessa.
- Registro do rastreamento: envie ou registre a remessa de acordo com os requisitos de integração do provedor.
- Ingestão de atualizações: receba callbacks de webhook, obtenha atualizações por meio de solicitações à API ou combine as duas abordagens.
- Processamento de eventos: valide, normalize, elimine duplicidades e avalie os eventos recebidos.
- Decisão de notificação: escolha se deve notificar, quem deve ser contatado e qual canal e modelo usar.
- Entrega da mensagem: envie a notificação e registre a resposta do serviço de mensagens.
Mantenha as informações de contato do cliente no seu próprio sistema de pedidos ou mensagens, a menos que a integração realmente exija compartilhá-las. Em geral, um serviço de rastreamento não precisa do endereço de e-mail do cliente apenas para que seu aplicativo associe um evento de rastreamento a um pedido.
1. Confirme o contrato de integração
Antes de criar o receptor, consulte a documentação do provedor sobre autenticação, registro de remessas, identificação da transportadora, métodos de atualização compatíveis, formatos de resposta, limites de solicitações e tratamento de erros. Para integrações com webhook, verifique também como os callbacks são autenticados, qual resposta confirma o recebimento e como as entregas malsucedidas são tratadas.
Para uma implementação com 17TRACK, comece pela página da Tracking API da 17TRACK e pela documentação oficial da API. Use o contrato documentado para sua integração, em vez de tratar os nomes de campos ilustrativos deste guia como campos de solicitação ou resposta da 17TRACK. Confirme a configuração dos callbacks, os requisitos de segurança e os limites específicos da conta antes da implementação.
Escolha o método de atualização de acordo com o contrato de integração:
- Webhooks: use callbacks quando forem compatíveis e adequados à sua infraestrutura. Eles permitem que seu aplicativo processe as atualizações quando o provedor as envia, sem solicitar repetidamente a mesma remessa.
- Polling: obtenha informações de rastreamento em uma programação definida quando os callbacks não estiverem disponíveis ou não forem adequados. Mantenha a programação dentro dos limites documentados de solicitações.
- Abordagem combinada: use callbacks para o processamento normal e obtenha seletivamente dados pela API para reconciliar remessas cujas atualizações pareçam desatualizadas, se o provedor oferecer suporte a esse fluxo.
Não prometa aos clientes notificações instantâneas simplesmente porque usa webhooks. Seu aplicativo não pode informar um evento da transportadora antes que os dados de rastreamento upstream o tornem disponível.
2. Crie um registro de remessa que suporte pedidos reais
Use um ID interno da remessa como referência principal, não apenas o número de rastreamento. Um pedido pode conter vários pacotes, e não se deve presumir que os números de rastreamento sejam globalmente exclusivos para sempre.
Um registro interno útil inclui:
- ID interno do pedido e da remessa.
- Número de rastreamento e identificador da transportadora, quando conhecidos.
- A referência da remessa no provedor, se fornecida.
- Status normalizado atual e o evento significativo mais recente.
- Horário do evento da transportadora, incluindo fuso horário ou deslocamento quando disponível.
- O horário em que seu sistema recebeu a atualização.
- Uma referência às preferências de comunicação do cliente.
- Histórico de notificações e qualquer fluxo de exceção ativo.
Armazene o horário do evento separadamente do horário de recebimento. Uma leitura que ocorreu antes pode chegar depois de uma leitura mais recente. Se seu aplicativo ordenar apenas pela ordem de chegada, poderá alterar incorretamente uma remessa entregue de volta para em trânsito.
Para pedidos divididos, associe as notificações ao pacote afetado. “Um pacote do seu pedido chegou” é mais preciso do que “Seu pedido chegou” quando outro pacote ainda está em trânsito.
3. Mapeie os eventos de rastreamento às decisões do cliente
As descrições da transportadora são dados operacionais, não mensagens prontas para o cliente. Crie uma camada de normalização que preserve o evento original e atribua uma categoria interna que suas regras de notificação possam compreender.
As categorias a seguir são conceitos de aplicação sugeridos, não um vocabulário universal de status de API:
| Categoria interna | Decisão de notificação | Limite da mensagem |
|---|---|---|
| Informações da remessa recebidas | Envie uma atualização de preparação somente se for útil. | Não sugira que a transportadora esteja de posse física do pacote apenas com base na criação da etiqueta. |
| Em trânsito | Considere notificar no primeiro movimento significativo. | Suprima leituras rotineiras em instalações, a menos que elas alterem o próximo passo do cliente. |
| Saiu para entrega | Notifique quando um evento compatível indicar esse status. | Não transforme o status em um horário de chegada garantido. |
| Tentativa de entrega ou retirada necessária | Envie uma notificação acionável. | Inclua prazos ou instruções de retirada somente quando verificados. |
| Exceção de entrega | Avalie a causa e se o cliente precisa tomar alguma medida. | Não descreva toda exceção como um pacote perdido. |
| Entregue | Envie uma confirmação específica do pacote. | Não invente um destinatário, local de entrega ou comprovante de entrega. |
Preserve a incerteza. Um evento não reconhecido deve seguir para uma etapa de análise ou fallback, em vez de ser forçado à categoria familiar mais próxima. Mantenha a descrição bruta disponível para a equipe de suporte solucionar problemas.
4. Receba atualizações sem perder nem duplicar trabalho
Seu endpoint de webhook deve validar a solicitação, salvar permanentemente a atualização aceita e retornar a confirmação exigida pelo provedor. Gere mensagens de forma assíncrona, em vez de aguardar um serviço de e-mail ou SMS durante a solicitação do callback.
Implemente o método documentado de verificação de callbacks do provedor. Não invente um cabeçalho de assinatura nem presuma que todos os provedores usam o mesmo esquema de autenticação. Também aplique HTTPS, limites de tamanho das solicitações, validação de payloads e controles de acesso adequados.
Um fluxo de processamento simplificado se parece com isto. Estas são operações no nível da aplicação, não um exemplo funcional de SDK:
receive callback
verify request using documented provider mechanism
validate payload
persist accepted payload and enqueue processing atomically
return documented acknowledgment
process queued update
find internal shipment
normalize relevant events
ignore already-processed events
evaluate chronology and state transition
create notification job if policy permits
commit state and job together
send notification job
check recipient preferences and suppression rules
submit message to messaging service
record result and retry only when appropriateAs etapas atômicas são importantes. Se seu aplicativo salvar uma alteração de status, mas falhar antes de criar o trabalho de notificação, o cliente talvez nunca receba o alerta. Um outbox transacional é uma opção de projeto: salve a alteração de estado e o trabalho pendente na mesma transação do banco de dados e, em seguida, permita que um worker despache o trabalho.
Trate referências de remessas desconhecidas explicitamente. Coloque-as em quarentena para investigação ou reconciliação, em vez de tentar adivinhar qual cliente deve receber uma notificação.
5. Adicione proteção contra duplicidades e verificações cronológicas
Projete o receptor para tolerar callbacks repetidos e novas tentativas dos workers. Prefira um identificador de evento estável do provedor quando houver um documentado. Caso contrário, crie uma impressão digital determinística do evento a partir de campos adequados, como o ID interno da remessa, o código do evento, o horário do evento e o local. Teste essa impressão digital com payloads reais antes de depender dela.
A eliminação de duplicidades de eventos e a supressão de notificações resolvem problemas diferentes. A eliminação de duplicidades impede que o mesmo evento seja processado duas vezes. A supressão evita que várias leituras distintas gerem essencialmente a mesma mensagem para o cliente.
Defina uma identidade de notificação em torno do evento de negócio. Uma confirmação de entrega pode usar o ID da remessa e o marco de entrega. Uma tentativa de entrega pode precisar de uma identidade específica da tentativa, pois uma tentativa posterior pode ser genuinamente um novo evento.
Para atualizações fora de ordem, compare os horários dos eventos e avalie as transições de estado permitidas. Não presuma que um callback contenha apenas uma nova leitura; verifique se sua estrutura documentada representa um evento individual, um instantâneo ou um histórico. Encaminhe atualizações contraditórias para reconciliação, em vez de descartar silenciosamente todas as correções.
6. Escreva mensagens que expliquem o que acontece em seguida
Cada notificação deve indicar o pacote relevante, a alteração confirmada e o próximo passo do cliente. Inclua um link seguro de rastreamento e uma referência de pedido reconhecível. Evite expor endereços completos ou informações pessoais desnecessárias em mensagens SMS e visualizações na tela de bloqueio.
Por exemplo:
- Saiu para entrega: “Seu pacote do pedido {order_reference} saiu para entrega. Acompanhe seu progresso aqui: {tracking_link}.”
- Tentativa de entrega: “A transportadora informou uma tentativa de entrega do seu pacote. Consulte a página de rastreamento para ver os próximos passos disponíveis: {tracking_link}.”
- Entregue: “A transportadora marcou seu pacote do pedido {order_reference} como entregue. Consulte os detalhes de entrega disponíveis: {tracking_link}.”
Renderize os placeholders somente a partir de dados validados. Se houver uma estimativa de entrega disponível e adequada para exibição, identifique-a como estimativa. Se estiver ausente, omita-a em vez de inventar uma data.
Para exceções, diferencie um problema da remessa de uma tarefa do cliente. Uma interrupção pode exigir apenas uma explicação; um problema de endereço verificado pode exigir uma ação. Não encaminhe clientes para uma página de pagamento ou upload de documentos com base apenas em conteúdo de rastreamento não confiável e em texto livre.
Escolha os canais usando as preferências do cliente, as permissões do canal, a urgência e as regras aplicáveis. Revise os requisitos de consentimento, cancelamento e horário de silêncio das jurisdições e dos canais de mensagens utilizados. Mantenha as notificações de serviço de entrega separadas das campanhas promocionais, em vez de presumir que as mesmas permissões abrangem ambas.
7. Defina o que acontece quando o rastreamento fica sem atualizações
A comunicação proativa deve abranger tanto a falta de progresso quanto novos eventos, mas o silêncio, por si só, não prova que uma remessa esteja atrasada ou perdida.
Crie uma regra de rastreamento desatualizado usando o nível de serviço, a rota, o último evento significativo e qualquer estimativa de entrega compatível. Defina os limites com base nos seus dados operacionais e no processo de suporte, em vez de aplicar um único período universal de espera a todas as remessas.
Quando essa regra for acionada, verifique se houve falhas no processamento, reconcilie com a fonte de rastreamento quando houver suporte e decida se deve abrir uma tarefa interna de suporte. Se notificar o cliente, use uma linguagem que reflita o que você sabe: “Não recebemos uma nova atualização de rastreamento” é diferente de “Seu pacote está perdido”.
Atribua um responsável às exceções não resolvidas. Um sistema de notificações que anuncia repetidamente um problema sem criar um caminho para a resolução pode aumentar a frustração do cliente.
8. Teste o caminho completo antes de ativar os envios automáticos
Execute primeiro o fluxo em modo sombra: ingira eventos reais ou de teste aprovados, gere notificações propostas e inspecione os resultados sem entrar em contato com os clientes.
- Reproduza um callback idêntico e confirme que ele não cria outra mensagem.
- Processe um evento de trânsito mais antigo depois de um evento de entrega e examine o estado resultante.
- Teste timestamps ausentes, status desconhecidos e payloads malformados.
- Simule uma falha do banco de dados antes da confirmação e uma falha do worker após a persistência.
- Teste timeouts de mensagens, incluindo uma resposta incerta em que o serviço talvez já tenha aceitado a mensagem.
- Confirme que remessas divididas produzem textos específicos para cada pacote.
- Verifique destinatários que cancelaram o recebimento, dados de contato inválidos e o tratamento de horários de silêncio.
- Verifique se os links de rastreamento não expõem informações de pedidos de outro cliente.
Monitore callbacks aceitos, falhas de processamento, idade da fila, trabalhos de notificação, supressão de duplicidades e resultados das mensagens. Meça a latência do processamento a partir do horário de recebimento do seu sistema separadamente da idade do evento da transportadora. Essa distinção ajuda a identificar se uma notificação lenta resultou da disponibilidade dos dados upstream ou do seu próprio pipeline.
Comece com um pequeno conjunto de marcos bem compreendidos. Amplie as regras somente depois que as equipes de suporte e operações concordarem que as mensagens são precisas, acionáveis e úteis.
FAQ
Uma API de rastreamento de remessas envia e-mails ou mensagens SMS automaticamente?
Não necessariamente. O acesso aos dados de rastreamento e as mensagens ao cliente são recursos separados. Consulte o escopo documentado do serviço. Em uma integração personalizada, seu aplicativo pode processar as atualizações de rastreamento e enviar notificações por meio de um serviço de mensagens separado.
Devo notificar os clientes sobre cada leitura de rastreamento?
Geralmente, não. Priorize marcos significativos e eventos que exigem uma ação. Várias leituras em instalações podem representar um trânsito normal sem alterar o que o cliente precisa saber. Mantenha o histórico detalhado na página de rastreamento.
Posso garantir notificações de entrega em tempo real?
Você pode definir e monitorar uma meta de processamento depois que seu sistema receber uma atualização. Não pode garantir quando uma transportadora registrará ou publicará uma leitura. Descreva o serviço em termos que reflitam essa dependência.
Como posso evitar mensagens de entrega duplicadas?
Use a eliminação persistente de duplicidades de eventos, uma identidade de notificação separada para cada marco de negócio e a criação transacional de trabalhos. Quando seu serviço de mensagens oferecer suporte à idempotência, use-a como outra proteção. Uma verificação de duplicidade apenas em memória não sobreviverá a reinicializações ou a vários workers.
O que deve acontecer se a transportadora corrigir um status de entregue?
Preserve ambos os eventos e reconcilie o estado da remessa. Se a correção afetar materialmente o cliente, envie uma correção clara ou encaminhe-a ao suporte de acordo com sua política. Não torne o status de entregue permanentemente irreversível apenas para simplificar o código.
Fontes
Os recursos oficiais a seguir são as referências de implementação para a integração com a 17TRACK discutida acima. O esquema interno, as regras de notificação e o fluxo de processamento deste guia são recomendações arquiteturais, não contratos de API citados.
- 17TRACK Tracking API — ponto de partida oficial para avaliar a integração da API.
- Documentação da API da 17TRACK — referência para formatos de solicitação específicos do provedor, autenticação, operações de rastreamento e requisitos de integração.


