Skip to main content
HomeBlogGuiasFluxo de trabalho da Shipment Tracking API: do registro de uma remessa à obtenção dos detalhes de rastreamento

Fluxo de trabalho da Shipment Tracking API: do registro de uma remessa à obtenção dos detalhes de rastreamento

17TRACK

Um fluxo de trabalho de uma API de rastreamento de remessas começa com o envio de um número de rastreamento e de quaisquer informações necessárias da transportadora, a verificação de que o registro foi concluído com sucesso, a espera até que os dados de rastreamento estejam disponíveis e a obtenção do status e do histórico de eventos da remessa. Em uma integração de produção, os desenvolvedores também precisam vincular cada registro de rastreamento a um pedido, lidar com falhas parciais, processar atualizações com segurança e distinguir um registro aceito de uma leitura real da transportadora.

Fluxo de trabalho da API de rastreamento de remessas: do registro de uma remessa à obtenção de informações

Este guia explica esse fluxo de trabalho para desenvolvedores que conectam uma plataforma de comércio eletrônico, um sistema de gerenciamento de pedidos, um aplicativo de armazém ou uma ferramenta de atendimento ao cliente. Ele separa as recomendações de design da aplicação dos requisitos específicos da API do provedor. Para uma integração com a 17TRACK, use a documentação oficial da API para confirmar o esquema das solicitações, a autenticação, as operações compatíveis e os campos das respostas antes de implementar os exemplos abaixo.

Entenda o que o registro faz — e o que não faz

Registrar uma remessa em um serviço de rastreamento significa enviar um identificador para que o serviço possa rastrear ou gerenciar essa remessa de acordo com o contrato da API. Isso não é a mesma operação que comprar postagem, gerar uma etiqueta de envio, agendar uma coleta ou entregar uma encomenda à transportadora.

Mantenha três resultados separados na sua aplicação:

  • Solicitação recebida: A API retornou uma resposta à sua solicitação HTTP.
  • Registro aceito: O serviço aceitou o registro de rastreamento individual para processamento.
  • Informações de rastreamento disponíveis: O serviço possui informações da remessa que sua aplicação pode consultar ou receber.

Esses resultados não devem ser combinados em um único indicador de “sucesso”. Um número de rastreamento aceito pode ainda não ter eventos da transportadora. Da mesma forma, uma resposta HTTP bem-sucedida para uma solicitação em lote não comprova que todos os itens do lote foram aceitos; examine a estrutura do resultado no nível da aplicação definida pelo provedor.

1. Prepare a identidade da remessa e a configuração da API

Antes de fazer uma solicitação de registro, decida como uma remessa será identificada dentro do seu próprio sistema. Normalmente, apenas um identificador de pedido é insuficiente, pois um pedido pode ser dividido em várias encomendas. Dê a cada remessa ou encomenda seu próprio registro interno e associe esse registro ao pedido relevante.

Um registro interno útil inclui as seguintes informações. Estes são campos sugeridos para a aplicação, não um esquema de solicitação da 17TRACK.

  • ID interno da remessa: Seu identificador estável para a encomenda.
  • Referência do pedido: O pedido ou registro de atendimento ao qual ela pertence.
  • Número de rastreamento: O identificador fornecido pela transportadora, armazenado como texto para preservar zeros à esquerda.
  • Informações da transportadora: A identidade da transportadora fornecida pelo seu sistema de atendimento, quando conhecida.
  • Referência do provedor: Qualquer identificador retornado pelo serviço de rastreamento necessário para operações posteriores.
  • Estado do registro: Seu registro indicando se o envio está pendente, aceito, rejeitado ou aguardando conciliação.
  • Estado do rastreamento: O status mais recente da remessa, mantido separadamente do estado do registro.

Valide os dados antes do envio. Remova espaços em branco acidentais ao redor, mas não reescreva o número de rastreamento com base em suposições sobre o formato da transportadora. Preserve o valor original para fins de solução de problemas. Se a transportadora for conhecida, mapeie-a para o identificador documentado pelo provedor em vez de enviar um nome informal de exibição.

Configure a autenticação no lado do servidor. Mantenha as credenciais fora do controle de versão, separe as configurações de desenvolvimento e produção e oculte segredos nos logs. Confirme a versão documentada da API, os limites de solicitações, os limites de lotes e os requisitos da conta, em vez de reutilizar valores de uma integração não relacionada.

2. Registre a remessa e armazene o resultado no nível do item

Envie o registro de rastreamento usando a operação de registro descrita na documentação do seu provedor. Inclua apenas os campos obrigatórios e as informações opcionais que tenham uma finalidade definida. Evite enviar nomes de clientes, endereços ou outros dados pessoais apenas porque estão disponíveis no banco de dados dos pedidos.

O pseudocódigo a seguir ilustra a sequência da aplicação. Os nomes das funções são ilustrativos; não são endpoints da API nem métodos de SDK.

shipment = load_internal_shipment(shipment_id)
validate_tracking_input(shipment)

result = tracking_adapter.register(shipment)

if result.item_accepted:
    save_registration_result(shipment_id, result)
elif result.outcome_unknown:
    schedule_registration_reconciliation(shipment_id)
else:
    save_registration_error(shipment_id, result)
    route_for_retry_or_correction(result)

Persista informações suficientes para explicar o que aconteceu: o ID interno da remessa, o horário do envio, o número da tentativa, o resultado no nível do item e qualquer referência da solicitação do provedor. Não dependa apenas de um log temporário do worker. Suas equipes de atendimento ao cliente e operações precisam de uma resposta duradoura sobre se uma remessa foi registrada com sucesso.

Trate os envios em lote individualmente

Se a API oferecer suporte ao registro em lote, associe cada item retornado à sua remessa original. Não marque todo o lote como aceito porque a solicitação HTTP foi concluída com sucesso. Salve os itens aceitos, isole os itens rejeitados e investigue os resultados ambíguos separadamente.

Isso evita que um número de rastreamento malformado force novas tentativas desnecessárias de registros que já foram processados com sucesso. Também fornece à equipe de operações uma lista acionável de registros que precisam de correção.

Trate os tempos limite como um resultado desconhecido

Um tempo limite não comprova que o registro falhou. O provedor pode ter aceitado a solicitação antes que sua conexão fosse interrompida. Use o comportamento documentado de idempotência, o tratamento de duplicatas ou operações de consulta para conciliar o resultado antes de reenviar cegamente.

Quando o comportamento do provedor em relação a duplicatas não estiver claro, teste-o com registros controlados e confirme o contrato antes de ativar novas tentativas automáticas. A desduplicação interna dos trabalhos de registro ainda é útil, mas não substitui a compreensão de como o serviço remoto trata solicitações repetidas.

3. Aguarde a chegada das primeiras informações de rastreamento

Depois que o registro for aceito, os detalhes do rastreamento podem não estar disponíveis imediatamente. Uma etiqueta pode existir antes que a transportadora registre um evento físico de manuseio. A ausência de informações também pode exigir a verificação do número de rastreamento, da seleção da transportadora ou dos requisitos de consulta específicos da remessa.

Represente essa condição explicitamente. “Registrado; aguardando informações de rastreamento” é mais preciso do que “Em trânsito” ou “Registro falhou”. Não invente uma estimativa de entrega ou um evento de movimentação para preencher uma interface vazia.

Quando um registro continuar vazio, investigue em uma ordem prática:

  1. Confirme que o registro individual foi aceito.
  2. Compare o número de rastreamento enviado com o registro de atendimento.
  3. Verifique o mapeamento da transportadora e quaisquer requisitos adicionais de consulta documentados.
  4. Consulte a página de rastreamento da própria transportadora para a mesma remessa.
  5. Se a transportadora tiver eventos, mas sua integração não, examine as respostas de consulta e entre em contato com o provedor da API com informações de diagnóstico ocultadas.

Evite adotar um período de espera universal sem evidências. As regras de escalonamento devem refletir o serviço de envio, o processo esperado de transferência e seus próprios compromissos operacionais.

4. Obtenha os detalhes do rastreamento e interprete-os corretamente

Quando o registro estiver disponível, chame a operação documentada de detalhes do rastreamento usando os identificadores exigidos. Não presuma que o registro e a consulta aceitam campos idênticos. Alguns contratos de API distinguem entre números de rastreamento, identificadores de transportadoras e referências de registros geradas pelo provedor.

Sua aplicação deve distinguir três camadas de informações:

  • Resumo da remessa: O estado geral usado em painéis, páginas de pedidos e filtros operacionais.
  • Histórico de eventos: As observações individuais, incluindo descrições de eventos, horários e locais quando fornecidos.
  • Metadados da consulta: Quando sua aplicação recebeu ou buscou as informações e se a solicitação foi concluída com sucesso.

Uma consulta bem-sucedida significa que a operação de obtenção foi concluída com sucesso. Isso não significa que a encomenda tenha se movimentado desde a consulta anterior. Compare as informações de rastreamento retornadas com o registro armazenado antes de gerar uma notificação ou um fluxo de trabalho posterior.

Mantenha o horário do evento separado do horário da consulta

Armazene separadamente o horário associado a um evento da transportadora e o horário em que seu sistema o recebeu. Um evento consultado nesta tarde pode descrever uma leitura anterior. Substituir o horário do evento pelo horário da consulta faria uma atualização antiga parecer uma nova movimentação física.

Preserve o carimbo de data e hora original e qualquer deslocamento fornecido. Normalize os carimbos de data e hora para comparação somente quando o fuso horário for conhecido. Se um evento não tiver informações de fuso horário, mantenha essa incerteza em vez de atribuir silenciosamente o fuso horário do seu servidor.

Preserve o significado original junto ao status normalizado

Um status normalizado é útil para agrupar remessas entre transportadoras, mas a descrição original do evento pode explicar um problema operacional com mais precisão. Mantenha ambos quando disponíveis. Sozinha, uma categoria ampla de exceção pode não informar a um agente de suporte se a próxima ação é verificar um endereço, entrar em contato com o destinatário ou aguardar outra atualização.

Não deduza uma garantia de entrega, uma perda confirmada ou um resultado aduaneiro específico a partir de um status vago. Faça o escalonamento de acordo com as informações subjacentes e sua política operacional.

5. Mantenha os registros atualizados por polling ou webhooks

Obter os detalhes uma vez é suficiente para testar a conectividade, mas não para manter a visibilidade da remessa. Seu design de produção precisa de um mecanismo de atualização. Confirme os mecanismos compatíveis com o provedor escolhido e as condições associadas a eles.

Com polling, sua aplicação solicita os detalhes do rastreamento em uma programação definida. Programe as solicitações dentro dos limites documentados, evite consultar repetidamente registros inalterados sem motivo e use recuo progressivo para falhas que podem ser repetidas. A abertura de uma página de pedido por um cliente não deve disparar automaticamente uma solicitação upstream irrestrita; uma visualização de rastreamento armazenada pode atender à página enquanto um processo em segundo plano controlado a atualiza.

Se você usar webhooks, valide as solicitações recebidas usando o mecanismo de verificação documentado pelo provedor. Persista ou coloque em uma fila durável as mensagens aceitas antes de confirmá-las de acordo com o contrato do webhook e, em seguida, processe os eventos de forma assíncrona.

Desenvolva o receptor para tolerar duplicatas e uma ordem de chegada inesperada, a menos que o contrato de entrega documentado garanta o contrário. Use um identificador de evento do provedor para desduplicação quando disponível. Caso contrário, defina e teste uma impressão digital baseada em campos de evento adequados, reconhecendo que essa impressão digital pode exigir ajustes para seus dados.

Uma integração orientada por webhooks também pode usar consultas controladas para conciliação. Por exemplo, um trabalho de recuperação pode verificar registros afetados por uma interrupção do receptor. Esse é um padrão de resiliência, não uma autorização para ignorar limites de taxa ou orientações específicas do provedor.

6. Transforme as informações de rastreamento em ações comerciais seguras

Atualize o registro interno da remessa antes de acionar ações voltadas ao cliente. Mantenha um registro durável das notificações e das transições de fluxo de trabalho para que um evento repetido não gere mensagens repetidas.

Associe as ações comerciais a mudanças significativas, não a cada resposta da API. Um evento de entrega observado recentemente pode justificar uma notificação de entrega. Uma resposta repetida contendo o mesmo evento não deve fazê-lo. Uma exceção pode justificar uma análise interna, mas a mensagem ao cliente deve refletir o que o evento realmente informa.

Defina como você tratará eventos recebidos depois que uma remessa tiver sido considerada concluída. Não exclua o histórico de eventos nem bloqueie permanentemente todas as atualizações posteriores apenas porque um resumo atingiu um estado terminal. Suas regras de retenção, conciliação e notificação devem considerar correções legítimas sem reabrir repetidamente fluxos de trabalho concluídos.

Aplicando o fluxo de trabalho a uma integração com a 17TRACK

Para uma integração de rastreamento personalizada, os pontos de partida relevantes são a página da API de rastreamento da 17TRACK e sua documentação para desenvolvedores. Use a página do produto para avaliar a oferta e a documentação para estabelecer o contrato real de integração. As páginas de rastreamento destinadas aos consumidores não substituem as especificações da API.

Antes de escrever seu adaptador, confirme o formato de autenticação, as operações de registro e consulta, as regras de identificação da transportadora, o tratamento das respostas no nível do item e os limites de solicitação aplicáveis. Para processamento baseado em webhooks, confirme também o esquema do payload, o processo de verificação, os requisitos de confirmação e o comportamento de novas tentativas.

Mantenha esses detalhes específicos do provedor dentro de um adaptador, em vez de espalhar suposições sobre campos de resposta por todo o sistema de pedidos. Assim, o restante da aplicação pode trabalhar com conceitos internos como resultado do registro, status da remessa, histórico de eventos e última sincronização bem-sucedida.

Verificações antes do lançamento que evitam erros dispendiosos

  • Registro aceito, mas vazio: A interface mostra que as informações de rastreamento estão pendentes, não que a encomenda está em movimento.
  • Resultado de lote misto: Cada remessa recebe seu próprio resultado persistido.
  • Tempo limite após o envio: O worker concilia o resultado incerto em vez de presumir uma falha.
  • Evento repetido: A linha do tempo da remessa e a notificação ao cliente permanecem sem duplicatas.
  • Evento mais antigo recebido posteriormente: O evento é preservado sem substituir cegamente um resumo mais recente.
  • Serviço upstream indisponível: A página do cliente pode mostrar o último resultado armazenado com uma indicação adequada de atualização.
  • Mapeamento incorreto da transportadora: O registro pode ser corrigido por meio de um caminho de recuperação documentado.
  • Pedido dividido: Cada encomenda mantém seu próprio estado de rastreamento e histórico de eventos.
  • Exposição de credenciais ou payloads: Os logs contêm referências de diagnóstico sem revelar segredos ou informações pessoais desnecessárias.

O critério prático de conclusão não é simplesmente receber uma resposta de registro bem-sucedida. É conseguir rastrear uma encomenda desde o envio até as atualizações, explicar um resultado vazio ou com falha e se recuperar de um processamento interrompido sem perder eventos nem duplicar ações para o cliente.

FAQ

Registrar um número de rastreamento cria uma remessa?

Não no fluxo de trabalho descrito aqui. O registro de rastreamento envia um identificador existente para um serviço de rastreamento. A criação de etiquetas, a compra de postagem e a contratação da transportadora são operações separadas, a menos que uma API específica as combine explicitamente.

Por que os detalhes do rastreamento estão vazios depois que o registro é aceito?

A aceitação do registro e a disponibilidade dos dados de rastreamento são condições diferentes. A transportadora pode ainda não ter registrado um evento, ou pode ser necessário verificar o número de rastreamento, o mapeamento da transportadora ou informações adicionais de consulta. Examine o resultado no nível do item antes de considerar o registro concluído com sucesso.

Devo registrar a remessa toda vez que consultar seu status?

Não use o registro repetido como mecanismo padrão de atualização. Armazene o estado do registro aceito e use o mecanismo documentado de consulta ou atualização. Siga as regras explícitas do provedor para correções, reativação ou envios duplicados.

Devo usar polling ou webhooks?

Use o mecanismo que se adapte ao contrato documentado da API e aos seus requisitos operacionais. O polling exige uma programação controlada de solicitações. Os webhooks exigem um receptor seguro e durável e um processamento protegido contra duplicatas. Quando compatível, atualizações por webhook com conciliação direcionada podem fornecer um caminho prático de recuperação.

Posso usar um número de rastreamento como único identificador de remessa do meu banco de dados?

Use um identificador interno de remessa. Armazene o número de rastreamento e o contexto relevante da transportadora como atributos desse registro. Isso facilita o gerenciamento de pedidos divididos, números de rastreamento corrigidos e referências específicas do provedor sem alterar a identidade da sua remessa interna.

Fontes

  • API de rastreamento da 17TRACK — ponto de entrada oficial do produto para avaliar uma integração com a API da 17TRACK.
  • Documentação da API da 17TRACK — referência oficial para formatos de solicitação, operações, respostas e requisitos de integração específicos da implementação. O pseudocódigo e as sugestões de campos internos deste guia são exemplos de design de aplicação, não citações deste contrato de API.