Como as marcas de comércio eletrônico por assinatura podem rastrear envios recorrentes com uma API de rastreamento
Para rastrear remessas recorrentes com uma API de rastreamento, crie um registro de remessa para cada pacote físico, vincule-o ao pedido de atendimento referente a esse ciclo da assinatura e registre seu número de rastreamento quando o armazém ou parceiro de atendimento o fornecer. Use as atualizações de rastreamento da API para mostrar aos clientes onde o pacote está e sinalizar exceções de entrega para sua equipe. Mantenha o ID da assinatura como um vínculo entre os ciclos, não como o identificador de um pacote.

Rastreie o pacote, não a assinatura
Uma assinatura informa o que um cliente está programado para receber ao longo do tempo. Um pedido de atendimento informa o que precisa ser enviado em um ciclo. Um número de rastreamento informa sobre um pacote específico. Manter esses registros separados evita que uma remessa atrasada de um ciclo apareça na página de rastreamento do ciclo seguinte.
Por exemplo, suponha que uma caixa de assinatura de maio seja dividida em dois pacotes e que a caixa de junho seja enviada enquanto um dos pacotes de maio ainda está em trânsito. O cliente deve ver dois pacotes no pedido de maio e um pacote separado no pedido de junho. A atualização atrasada de maio deve alterar apenas o pacote de maio. Se você enviar uma substituição, crie um novo registro de remessa e vincule-o ao original para que o suporte possa entender por que ambos existem.
- Assinatura: Armazene o ID da assinatura para que o suporte possa encontrar o histórico de remessas do cliente.
- Ciclo e pedido: Registre o identificador do ciclo ou a data de atendimento programada, o ID do pedido e quaisquer IDs de atendimento necessários para associar os pacotes ao pedido correto. Não deduza o ciclo a partir da data em que um evento de rastreamento chega.
- Remessa: Dê a cada pacote um ID interno de remessa. Armazene a transportadora e o número de rastreamento, a referência de atendimento relevante e qualquer ID de registro de rastreamento retornado pelo provedor. Mantenha etiquetas canceladas e números de rastreamento substituídos fora da visualização ativa do cliente, mas preserve o histórico para o suporte.
Em uma página de pedido, mostre o progresso no nível do pacote junto com qualquer resumo do pedido. Se um pacote foi entregue e outro está em trânsito, informe isso. Só mostre o pedido inteiro como entregue quando todos os pacotes necessários para concluí-lo tiverem chegado, levando em conta remessas canceladas e substituições.
Conecte o atendimento à API de rastreamento
- Registre a partir de um evento de atendimento. Acione o registro quando um sistema de atendimento, armazém ou parceiro de logística terceirizado enviar a transportadora e o número de rastreamento. Um pagamento de renovação é cedo demais: o pedido ainda pode estar aguardando o envio, e talvez não exista um número de rastreamento.
- Salve a remessa antes de chamar a API. Persista o registro interno da remessa e coloque a solicitação de registro em uma fila. Se a mesma mensagem de atendimento chegar duas vezes, reutilize esse registro em vez de criar outro pacote. Se a chamada da API expirar, verifique se a solicitação original foi bem-sucedida antes de tentar novamente, quando o provedor oferecer uma forma de fazer isso.
- Associe as atualizações ao pacote registrado. Use o identificador de registro do provedor se ele for retornado nas atualizações. Caso contrário, faça a correspondência usando os identificadores especificados na documentação e valide o resultado em relação aos seus registros de remessa. Se uma atualização puder pertencer a mais de um registro, envie-a para análise em vez de aplicá-la ao pedido mais recente.
- Separe a criação da etiqueta do movimento da transportadora. Um número de rastreamento pode existir antes que a transportadora registre a posse. Use uma mensagem como “Preparando para coleta pela transportadora” quando você tiver apenas uma etiqueta. Reserve “Em trânsito” para informações da transportadora que sustentem esse status.
A API de rastreamento da 17TRACK é uma opção para essa configuração. A documentação para desenvolvedores é a referência para registrar números de rastreamento e receber atualizações de rastreamento. Use essas atualizações para manter o registro do pacote no seu sistema; mantenha as regras de atribuição de ciclos, conclusão de pedidos e notificações aos clientes na sua aplicação de comércio eletrônico. Antes da implementação, teste com pacotes de rotas reais das suas transportadoras e parceiros de atendimento, em vez de depender apenas de uma lista de transportadoras.
Torne as atualizações seguras para serem processadas duas vezes
Quando o provedor oferecer webhooks, use-os para receber atualizações sem consultar continuamente cada pacote. Um webhook é uma solicitação HTTP que o provedor envia à sua aplicação. Siga os requisitos de verificação do provedor, armazene os payloads aceitos de forma durável e confirme as solicitações de acordo com as regras de resposta documentadas. Execute trabalhos mais lentos, como atualizar visualizações de pedidos ou enviar e-mails, fora do manipulador da solicitação.
Crie o fluxo de processamento para que uma atualização repetida não tenha efeito adicional. Se o provedor fornecer IDs de evento estáveis, use-os para reconhecer repetições. Se ele enviar instantâneos de rastreamento em vez de eventos individuais, compare o estado recebido e o histórico de rastreamento com o que você já possui antes de agir. Elimine duplicações de mensagens aos clientes separadamente: uma notificação de entrega que já foi enviada não deve ser enviada novamente apenas porque os mesmos dados da remessa foram processados duas vezes.
Mantenha separado o horário em que uma leitura ocorreu e o horário em que sua aplicação a recebeu. Uma leitura de trânsito que chega atrasada pode pertencer ao histórico do pacote sem substituir um status de entrega mais recente. No entanto, não presuma que toda mudança legítima faça um pacote avançar. Uma correção da transportadora ou uma atualização de devolução ao remetente pode precisar alterar o que você exibe. Se os novos dados entrarem em conflito com o estado armazenado e você não puder determinar qual está correto, coloque a remessa em uma fila de análise.
Faça uma verificação periódica das remessas abertas que possam precisar de atenção: registros ainda pendentes, pacotes sem a primeira leitura após uma transferência esperada e remessas cujo rastreamento ficou sem novas informações. Quando a API oferecer uma consulta ou atualização, use-a seletivamente dentro dos limites do provedor. Verifique o padrão entre transportadoras e armazéns antes de escalar o problema. Se as atualizações pararem para muitas remessas não relacionadas ao mesmo tempo, investigue a integração antes de abrir casos de entrega individuais.
Transforme os dados de rastreamento em mensagens úteis para os clientes
Os clientes raramente precisam de um e-mail para cada leitura. Comece com mensagens relacionadas a algo que eles precisam saber ou fazer: o pacote entrou na rede da transportadora, uma tentativa de entrega exige ação ou a transportadora informa que a entrega foi realizada. Mostre a referência do pedido e a caixa ou o ciclo relevante para que os assinantes saibam a qual remessa a mensagem se refere. Em um pedido dividido, identifique o pacote e deixe claro se o restante do pedido ainda está a caminho.
- Etiqueta criada, sem leitura: Verifique a transferência esperada nos registros do armazém. Se o prazo de transferência tiver passado, peça ao atendimento que confirme se o pacote deixou a unidade antes de informar ao cliente que ele está atrasado em trânsito.
- O rastreamento parou de avançar: Use limites que reflitam a rota e o serviço, em vez de um único cronômetro para todos os pacotes. Para remessas internacionais, analise o último evento da transportadora antes de decidir se deve entrar em contato com o cliente ou escalar o caso.
- Tentativa malsucedida ou retirada necessária: Informe ao cliente qual ação é necessária se a transportadora fornecer instruções claras. Se o evento for vago, encaminhe o caso ao suporte em vez de adivinhar uma data de nova entrega ou um local de retirada.
- Marcado como entregue, mas não recebido: Mantenha o status informado pela transportadora e abra um caso separado de suporte. Seu fluxo de suporte deve distinguir um relato do cliente de uma correção da transportadora.
Ofereça à equipe de suporte uma visão única do ciclo, do pedido, do histórico do pacote e das mensagens já enviadas. Para cada exceção, atribua um responsável e uma próxima etapa. O atendimento pode investigar uma transferência ausente, a logística pode acompanhar uma exceção da transportadora e o suporte pode cuidar da comunicação com o cliente. Um status de rastreamento descreve o pacote; ele não decide se uma substituição ou um reembolso é devido.
Teste a sobreposição antes da implementação
Comece com um parceiro de atendimento e um conjunto de remessas que reflita como ele realmente despacha os pedidos. Inclua um ciclo com vários pacotes, uma etiqueta anulada, uma substituição e uma remessa mais antiga que ainda esteja aberta quando o ciclo seguinte for enviado. Em seguida, reproduza deliberadamente um webhook duplicado e entregue um evento mais antigo depois de um mais recente. Verifique o registro do pacote, a página do pedido do cliente, a visualização do suporte e o registro de notificações. Um teste que verifica apenas uma resposta bem-sucedida da API pode deixar passar o erro mais caro: atualizar o pedido errado ou enviar uma mensagem ao cliente errado.
Monitore falhas de registro, a proporção de pacotes elegíveis registrados com sucesso, primeiras leituras posteriores ao esperado e atualizações não associadas. Se você acompanhar a latência das atualizações, diferencie o tempo entre um evento da transportadora e seu recebimento do tempo que seu próprio sistema leva para processá-lo. Isso ajuda a decidir se é necessário investigar o feed da transportadora, o endpoint do webhook ou uma fila dentro da sua aplicação.
Expanda para mais rotas quando puder responder a três perguntas sobre qualquer pacote: A qual ciclo ele pertence? O que a transportadora informou por último? Quem age se a atualização estiver ausente ou incorreta? Se alguma resposta não estiver clara, corrija o mapeamento dos registros ou o fluxo de exceções antes de adicionar mais regras de notificação.
Perguntas frequentes
Uma API de rastreamento pode informar aos clientes quando a próxima caixa da assinatura será enviada?
Use sua programação de assinatura e seu sistema de atendimento para a próxima data planejada de envio. Uma API de rastreamento é destinada a um pacote específico quando as informações de rastreamento existem. Uma data planejada de envio, uma estimativa de entrega da transportadora e uma entrega confirmada são fatos diferentes e devem ser identificados separadamente.
E se o armazém substituir um número de rastreamento depois que um e-mail for enviado?
Marque a etiqueta antiga como substituída e vincule o novo número de rastreamento ao mesmo pedido. Se o seu e-mail apontar para uma página de rastreamento no nível do pedido, atualize essa página para que o cliente encontre o pacote ativo sem precisar do link original da transportadora. Envie uma correção quando a alteração afetar informações que o cliente precise usar para agir.
E se um parceiro de atendimento enviar números de rastreamento sem códigos de transportadora?
Peça ao parceiro um campo de transportadora consistente ou um mapeamento dos códigos de serviço de envio usados por ele. Se sua API oferecer detecção de transportadora, verifique como ela funciona com as etiquetas do parceiro antes de depender dela. Encaminhe correspondências ambíguas para análise em vez de escolher uma transportadora apenas com base no número de rastreamento.
Assinaturas pausadas ou ignoradas precisam de registros de rastreamento?
Não é necessário um registro de pacote para um ciclo que nunca é enviado. Se uma remessa anterior ainda estiver aberta, continue rastreando-a mesmo quando a assinatura estiver pausada, ignorada ou cancelada. O estado da assinatura controla o atendimento futuro; ele não informa o que aconteceu com um pacote que já deixou o armazém.
Fontes
- API de rastreamento da 17TRACK — visão geral do produto para integrar o rastreamento de pacotes a sistemas empresariais.
- Documentação da API de rastreamento da 17TRACK — referência de implementação para registrar números de rastreamento e receber dados de rastreamento.
- Documentação de webhooks da Stripe — referência para práticas gerais de webhook, como lidar com eventos duplicados e evitar suposições sobre a ordem de entrega. Siga as regras próprias do seu provedor de rastreamento para verificação e confirmações.


