Skip to main content
HomeBlogGuiasComo conectar dados de rastreamento de remessas a um Oms: mapeamento de pedidos e regras de sincronização

Como conectar dados de rastreamento de remessas a um Oms: mapeamento de pedidos e regras de sincronização

17TRACK

Para conectar os dados de rastreamento de remessas a um sistema de gerenciamento de pedidos (OMS), associe cada pacote rastreado a um registro interno de remessa e, em seguida, vincule essa remessa ao pedido e às linhas de atendimento. Receba atualizações de rastreamento por meio da interface compatível do provedor, preserve os eventos originais e aplique regras explícitas para duplicatas, atualizações atrasadas, status da remessa e conclusão do pedido. Não use apenas um número de rastreamento como identificador do pedido nem permita que um único evento de entrega feche automaticamente um pedido com vários pacotes.

Como conectar dados de rastreamento de remessas a um pedido do OMS

Este guia é destinado a engenheiros de integração e equipes de operações de comércio eletrônico que implementam essa conexão. O design recomendado separa as observações da transportadora das decisões de negócio: os dados de rastreamento descrevem a jornada de um pacote, enquanto o OMS decide o que essa jornada significa para o atendimento, a comunicação com o cliente e o fechamento do pedido.

Defina qual sistema é responsável por cada registro

Antes de criar uma conexão de API, defina a responsabilidade com o administrador do OMS, a equipe de atendimento e a equipe de serviço ao cliente. Caso contrário, uma integração tecnicamente bem-sucedida ainda poderá substituir dados comerciais válidos.

  • OMS: É responsável pelos pedidos, linhas de pedido, quantidades necessárias, cancelamentos e regras de conclusão do pedido.
  • Sistema de atendimento: É responsável pelos registros de remessa ou pacote que cria, incluindo alocações de embalagem e atribuições de etiquetas. Pode ser o próprio OMS ou um sistema de armazém separado.
  • Provedor de rastreamento: Fornece observações de rastreamento e quaisquer classificações de status definidas pelo provedor.
  • Camada de integração: É responsável pelas referências cruzadas de identificadores, processamento de eventos, normalização, tratamento de novas tentativas e registros de auditoria da sincronização.

Trate esses pontos como limites recomendados, não como suposições sobre seu software. Documente as exceções. Por exemplo, se o armazém puder substituir uma etiqueta de envio, a integração precisará receber uma atualização explícita desse sistema, em vez de presumir que um número recém-observado substitui um antigo.

Crie o mapeamento de pedido para pacote antes de sincronizar os status

Uma relação prática é pedido → atendimento → pacote → atribuição de rastreamento. Seu OMS pode usar nomes diferentes ou combinar alguns desses registros. Preserve as relações mesmo que a estrutura do banco de dados seja diferente.

Um pedido pode ter vários atendimentos, e um atendimento pode conter vários pacotes. Um pacote também pode receber uma nova atribuição de rastreamento ou um identificador de última milha vinculado. Esses identificadores não devem criar quantidades adicionais encomendadas.

RegistroCampos recomendadosFinalidade
PedidoID do locatário ou da loja, ID imutável do pedido no OMSSepara os comerciantes e evita a dependência de números de pedido exibidos.
AtendimentoID do atendimento, ID do pedido, IDs e quantidades das linhas alocadasIdentifica quais itens comprados estão sendo atendidos.
PacoteID interno do pacote, ID do atendimento, alocações do pacote quando disponíveisFornece uma identidade estável independente das etiquetas de rastreamento.
Atribuição de rastreamentoID da atribuição, ID do pacote, conta do provedor, identificador da transportadora, número de rastreamento, período de atividadeVincula as observações de rastreamento recebidas ao pacote correto e ao ciclo de vida da atribuição.

Associe as atualizações por meio de uma referência cruzada armazenada

Quando uma remessa for criada, armazene seus IDs internos antes de registrá-la para rastreamento. Armazene qualquer ID de registro de rastreamento emitido pelo provedor e retornado pelo processo de registro documentado. Se o provedor oferecer suporte a uma referência do comerciante, use uma referência interna opaca e mantenha o mapeamento localmente.

Para atualizações recebidas, primeiro resolva o ID de registro armazenado do provedor dentro da conta e do locatário corretos. Se esse identificador não estiver disponível, use a combinação documentada de número de rastreamento, identidade da transportadora, contexto da conta e histórico de atribuições. Trate isso como uma estratégia de consulta, não como garantia de que a combinação seja globalmente exclusiva.

Não faça a correspondência por nome do cliente, endereço de e-mail ou número de pedido exibido sem escopo. Preserve os números de rastreamento como strings para que os zeros à esquerda sejam mantidos. Evite remover caracteres ou alterar maiúsculas e minúsculas, a menos que o contrato da transportadora ou do provedor permita essa normalização.

Se uma consulta não retornar correspondência ou retornar várias correspondências possíveis, coloque a atualização em quarentena para investigação. Um evento não resolvido é mais seguro do que uma atualização confiante no pedido do cliente errado.

Gerencie pedidos divididos sem inventar alocações de pacotes

Considere um pedido ilustrativo contendo três unidades. O Pacote A transporta duas unidades e o Pacote B transporta uma. A entrega do Pacote A significa que há evidência de entrega de duas unidades; isso não significa que o pedido inteiro foi entregue.

Se o sistema de atendimento registrar apenas que os dois pacotes pertencem ao mesmo atendimento, não invente alocações em nível de unidade. Ainda é possível calcular se todos os pacotes necessários foram entregues, mas os relatórios de entrega em nível de item devem permanecer indisponíveis ou explicitamente incertos até que existam dados de alocação.

Conecte a API de rastreamento por meio de uma camada de ingestão durável

Use um pipeline que mantenha a comunicação com o provedor separada das gravações no OMS:

Criação da remessa → registro do rastreamento → atualização recebida ou recuperação programada → armazenamento durável do evento → mapeamento e normalização → atualização do OMS → reconciliação

Para uma implementação do 17TRACK, a página do produto Tracking API e a documentação oficial da API são os pontos de partida relevantes. Confirme a interface de registro aplicável, os identificadores de transportadora, as opções de entrega de atualizações, os requisitos de autenticação, as definições de status e os limites da conta antes de implementar o adaptador. O modelo de dados deste guia é uma recomendação de integração, não uma afirmação de que o 17TRACK usa esses nomes de campos ou fornece um conector nativo para seu OMS.

Se o provedor escolhido oferecer suporte a webhooks, autentique as solicitações recebidas usando o mecanismo documentado e armazene de forma durável as mensagens aceitas antes de confirmá-las. Mantenha o processamento lento do OMS fora do caminho da solicitação. Siga o contrato real de confirmação e novas tentativas do provedor, em vez de presumir um corpo de resposta ou tempo limite específico.

Se a consulta periódica for necessária, armazene o progresso da recuperação quando a API oferecer suporte a isso, controle a simultaneidade e siga os limites de taxa documentados. Nem o recebimento de um webhook nem uma consulta periódica bem-sucedida comprovam que o OMS foi atualizado; registre esses resultados separadamente.

Defina regras de sincronização que resistam a novas tentativas e eventos atrasados

1. Torne o processamento idempotente

Processar a mesma observação duas vezes não deve duplicar uma remessa, avançar as quantidades duas vezes nem enviar novamente a mesma notificação ao cliente. O HTTP não torna uma operação POST arbitrária idempotente; a integração precisa implementar proteção contra duplicatas. A RFC 9110 explica a idempotência dos métodos HTTP.

Use um ID de evento estável do provedor quando ele for documentado e estiver disponível. Caso contrário, defina uma impressão digital a partir do ID da atribuição e dos campos relevantes do evento, como o carimbo de data e hora, o status de origem e a localização. Documente a possibilidade de colisões ou alterações nas descrições dos eventos. Mantenha a observação bruta mesmo quando ela não gerar outra ação no OMS.

Proteja cada efeito colateral separadamente. Por exemplo, uma gravação de status no OMS e uma notificação por e-mail precisam de seus próprios controles de deduplicação. Use um outbox transacional ou um registro de trabalho durável equivalente para que uma falha do processo não deixe um evento aceito sem uma atualização programada.

2. Armazene separadamente o horário do evento e o horário de recebimento

O horário de ocorrência de um evento e o horário em que sua integração o recebeu respondem a perguntas diferentes. Armazene ambos, juntamente com a representação original do carimbo de data e hora e qualquer deslocamento de fuso horário fornecido. Não atribua silenciosamente o fuso horário do armazém a um evento cujo fuso horário seja desconhecido.

Uma leitura de trânsito recebida com atraso normalmente deve enriquecer o histórico sem substituir um estado de entrega mais recente. No entanto, os carimbos de data e hora sozinhos são insuficientes: um provedor pode emitir uma correção, e os eventos podem conter informações de horário incompletas. Use campos documentados de sequência ou revisão quando disponíveis, além de uma política explícita de correção.

3. Normalize os status sem apagar os detalhes da origem

Crie um vocabulário interno pequeno que o OMS compreenda, como aguardando aceitação da transportadora, em trânsito, saiu para entrega, entregue, exceção e em devolução. Mapeie para ele os status documentados do provedor. Essas são categorias internas sugeridas, não definições universais de transportadoras.

Armazene o código de status original, a descrição, a localização do evento, a referência do registro do provedor e a versão da regra de mapeamento. Um valor não mapeado deve criar uma condição que possa ser revisada, em vez de assumir como padrão que foi entregue ou falhou. A criação da etiqueta não deve ser tratada como prova de aceitação física pela transportadora, a menos que o evento de origem ofereça explicitamente suporte a essa interpretação.

4. Use regras de transição, não uma classificação numérica simples

Os estados da remessa nem sempre formam uma linha reta. Uma exceção pode ser seguida por trânsito normal, e uma tentativa de entrega não é uma entrega. O movimento de devolução pode começar após um evento anterior de entrega.

  • Permita que uma exceção seja resolvida quando evidências posteriores indicarem a retomada do movimento.
  • Impeça que uma leitura histórica comum substitua silenciosamente um estado entregue.
  • Permita uma correção documentada por meio de um caminho de revisão controlado.
  • Acompanhe o movimento de devolução separadamente da conclusão da saída quando o OMS oferecer suporte a isso.
  • Encaminhe evidências ambíguas ou contraditórias para uma fila operacional.

Versione essas regras. Quando um mapeamento mudar, decida se ele se aplica apenas a novos eventos ou se os registros históricos exigem um recálculo controlado.

Calcule o status do pedido a partir das obrigações de atendimento necessárias

O status do pacote e o status do pedido devem ser campos separados. Um pacote marcado como entregue fornece evidência para esse pacote; a conclusão do pedido depende das quantidades necessárias restantes e da sua política comercial.

Um padrão útil é marcar um pedido como totalmente entregue somente quando todas as quantidades que exigem entrega tiverem evidência válida de entrega em nível de pacote e não houver alocações necessárias não resolvidas. Exclua as quantidades canceladas de acordo com as regras de cancelamento do OMS. Gerencie itens digitais, pedidos para retirada e outras obrigações que não envolvam envio por meio de suas próprias condições de conclusão.

As remessas de substituição exigem relações explícitas. Se um pacote perdido for substituído, decida se a substituição substitui a obrigação de entrega original. Caso contrário, o pacote original poderá bloquear a conclusão indefinidamente, ou ambos os pacotes poderão contar para o atendimento. Registre a decisão em vez de deduzi-la apenas do status de rastreamento.

Mantenha a conclusão da entrega separada do fechamento financeiro, da elegibilidade para reembolso e da resolução de disputas. Um evento de entrega da transportadora não deve autorizar automaticamente um reembolso nem resolver uma contestação do cliente.

Recupere-se de falhas sem perder o registro de auditoria

Repita as tentativas de falhas transitórias usando recuo limitado e qualquer orientação documentada sobre novas tentativas. Separe falhas temporárias de conexão de identificadores inválidos, credenciais expiradas, erros de permissão e incompatibilidades de esquema. Estas últimas exigem ações corretivas, não tentativas infinitas.

Mantenha uma fila de trabalho com falha contendo o locatário afetado, o pacote, a referência do evento, a operação tentada, a classificação do erro e a próxima ação. Registre contexto suficiente para investigação sem copiar dados desnecessários do cliente ou credenciais para os logs.

Execute a reconciliação além do caminho normal de atualização. Revise remessas ativas com informações de rastreamento desatualizadas, eventos aceitos cujas gravações no OMS falharam, observações não correspondentes e diferenças entre o estado calculado pela integração e o OMS. Escolha a frequência de revisão com base nos compromissos de entrega, nos limites da API e no risco operacional, em vez de aplicar um cronograma universal arbitrário.

Atribua responsabilidades: a engenharia cuida da ingestão e das falhas de gravação; as operações de atendimento resolvem relações de pacotes ausentes; o serviço ao cliente analisa exceções que exigem comunicação com o cliente. Uma fila sem um responsável definido é apenas um local de armazenamento.

Teste o mapeamento e as regras comerciais antes do lançamento

Use dados de teste controlados e um lançamento limitado em produção. Teste os seguintes casos em relação ao histórico de eventos e ao registro resultante no OMS:

  • Um pedido de pacote único avança normalmente até a entrega.
  • Um pedido dividido tem um pacote entregue e outro ainda em trânsito.
  • O mesmo evento é recebido repetidamente sem efeitos colaterais duplicados.
  • Uma leitura de trânsito mais antiga chega depois da entrega.
  • Uma transportadora ou um status desconhecido entra na fila de revisão.
  • Uma etiqueta é substituída sem criar outra obrigação de atendimento.
  • Uma remessa de substituição substitui um pacote original de acordo com uma regra aprovada.
  • O OMS fica indisponível depois que um evento é aceito.
  • Um processo é reiniciado entre uma gravação no OMS e sua confirmação.
  • O mesmo número de pedido exibido existe em duas lojas sem correspondência entre locatários.

Lance quando todo evento aceito tiver um resultado de processamento rastreável, correspondências ambíguas não puderem atualizar pedidos automaticamente e os operadores puderem reproduzir o trabalho com falha com segurança. Esses são critérios de aceitação mais úteis do que simplesmente demonstrar que uma solicitação de API foi bem-sucedida.

FAQ

Posso conectar os números de rastreamento diretamente aos pedidos?

Para um fluxo de trabalho estritamente de pacote único, uma relação direta pode ser suficiente inicialmente. Ainda assim, use uma identidade interna de remessa entre o pedido e a atribuição de rastreamento. Isso fornece um caminho de migração para remessas divididas, troca de etiquetas e substituições sem alterar o significado do registro do pedido.

A integração deve usar webhooks ou consultas periódicas?

Use o mecanismo de entrega compatível com o provedor e com sua infraestrutura. Os webhooks podem reduzir recuperações repetidas, enquanto as consultas periódicas podem oferecer suporte a fluxos baseados em recuperação e reconciliação quando disponíveis. Nenhuma das abordagens elimina a necessidade de armazenamento durável, tratamento de duplicatas e recuperação.

O que deve acontecer quando um evento de rastreamento não tiver um pedido correspondente?

Armazene-o em uma fila de eventos não correspondentes e investigue o registro de inscrição, o contexto do locatário, a identidade da transportadora e o momento da criação da remessa. Não crie um pedido nem associe automaticamente o evento a um cliente plausível. Reproduza-o depois que o mapeamento for corrigido.

As notificações de entrega devem vir do OMS ou do sistema de rastreamento?

Escolha um responsável por cada tipo e gatilho de notificação. Se dois sistemas puderem enviar a mesma mensagem, desative um caminho ou compartilhe um registro durável de notificações. Decida também se uma mensagem se refere a um pacote ou ao pedido completo, especialmente no caso de atendimento dividido.

Um status de exceção significa que o pedido falhou?

Não. Uma exceção é uma observação que exige interpretação, não necessariamente um resultado permanente. Preserve o motivo, monitore os eventos seguintes e use sua política de escalonamento para decidir quando as operações devem intervir.

Fontes