Guia do programador de webhooks
Introdução
Os Tracking Webhooks da FedEx fornecem atualizações quase em tempo real sobre a expedição ao longo de todo o seu ciclo de vida.
Ao contrário das API de rastreio, que exigem que as aplicações solicitem o estado da expedição, os webhooks enviam automaticamente atualizações sobre a expedição à medida que ficam disponíveis novas informações.
Este guia aborda:
- Três princípios de integração
- Como funcionam os webhooks
- Processamento de payloads de webhooks
- Notificações para clientes
- Registos de data/hora
- Boas práticas e problemas comuns de integração
Três princípios de integração
As integrações de webhooks bem-sucedidas seguem três princípios.
Trate cada payload de webhook como uma atualização do estado da expedição
Não assuma que cada payload representa um novo marco de rastreio. A FedEx publica um novo payload sempre que ficam disponíveis novas informações sobre a expedição.
Um payload pode conter:
- Um novo evento de rastreio
- Previsões de entrega atualizadas
- Informações sobre a prova de entrega
- Informações do Destinatário
- Outras alterações aos dados da expedição
Vários payloads podem partilhar o mesmo marco de rastreio, embora contenham informações de expedição diferentes.
Armazene e integre os dados da expedição
Cada payload pode conter informações novas ou atualizadas sobre a expedição. Armazene cada payload do webhook e integre as novas informações no registo existente da expedição.
Não substitua o registo da expedição existente pelo payload mais recente. Em vez disso, preserve os dados de expedição recebidos anteriormente e incorpore novas informações para manter o registo da expedição completo e atualizado ao longo de todo o ciclo de vida da expedição.
Utilize regras de negócio para orientar as ações
Utilize regras de negócio para determinar quando atualizar sistemas ou notificar clientes.
Não despolete ações exclusivamente com base num código de evento. Antes de atualizar aplicações destinadas aos clientes ou de enviar notificações, avalie:
- Os marcos do rastreio
- A disponibilidade da expedição
- O momento da notificação
- Os requisitos empresariais
Modelo de processamento recomendado
O diagrama seguinte ilustra como os três princípios de integração de webhooks funcionam em conjunto numa implementação típica. Cada payload de webhook é processado como uma atualização do estado da expedição, integrado num registo centralizado da expedição e avaliado através de regras de negócio antes de as aplicações serem atualizadas ou de serem enviadas notificações aos clientes.
Como funcionam os webhooks
A FedEx publica um novo payload de webhook sempre que as informações da expedição são alteradas ou ficam disponíveis. Uma expedição pode gerar vários payloads ao longo do seu ciclo de vida, incluindo vários payloads associados ao mesmo marco de rastreio.
Payloads adicionais podem incluir:
- Marcos do rastreio: Recolhido, Em trânsito, Em distribuição e Entregue.
- Dados da expedição: Prova de entrega (PPOD), Prova de entrega com assinatura (SPOD), Prova de entrega por GPS (GPS POD) e informações do destinatário.
- Atualizações das previsões de entrega: alterações à data de entrega estimada e à hora estimada.
- Exceções de entrega: atualizações e motivos das exceções de expedição e de entrega.
- Atualizações dos metadados da expedição: atualizações de endereço, referências e detalhes do serviço.
- Correções operacionais: marcos adicionais de rastreio e atualizações de
previousEvents.
Nota: a prova fotográfica não está disponível para todas as expedições entregues. A disponibilidade depende do tipo de entrega, dos requisitos de assinatura e de outras regras de negócio.
Cada payload representa o estado mais recente conhecido da expedição. Processe cada payload para garantir que o registo da expedição permanece completo e atualizado.
Compreender as atualizações de webhooks
O exemplo seguinte mostra como podem ser geradas vários payloads de webhook para a mesma expedição ao longo do seu ciclo de vida. Alguns payloads introduzem um novo marco do rastreio. Outras acrescentam informações da expedição, como previsões de entrega, dados da Prova de entrega ou detalhes da expedição.
Importante: vários payloads de webhook podem ser gerados para o mesmo marco de rastreio. Processe cada payload para garantir que as novas informações sobre a expedição são incorporadas no registo da expedição.
Processamento de payloads de webhooks
Processe cada payload de webhook como uma atualização do estado da expedição.
Não assuma que cada payload de webhook representa um novo marco do rastreio. A FedEx envia um novo payload sempre que ficam disponíveis novas informações sobre a expedição. Por exemplo, uma expedição entregue pode gerar payloads adicionais quando são adicionadas ou atualizadas informações da prova de entrega, informações do destinatário ou outros dados da expedição.
Para cada payload, pergunte:
- Que marco de rastreio foi alterado?
- Que informações da expedição foram alteradas?
- A atualização afeta uma aplicação destinada aos clientes?
- A atualização desencadeia uma notificação?
Processe o histórico de expedições
Monitorize tanto scanEvent como previousEvents.
scanEventcontém o marco de rastreio atual associado ao payload.previousEventscontém histórico adicional da expedição, incluindo marcos que podem não aparecer como oscanEventatual.
Alguns marcos de rastreio aparecem em previousEvents em vez de serem publicados como um novo scanEvent. As aplicações que apenas processam scanEvent podem perder atualizações da expedição e gerar históricos de expedição incompletos. Processe ambas as recolhas para captar uma visão completa da expedição.
Mantenha um registo de expedição
Armazene cada payload do webhook e integre as novas informações no registo existente da expedição.
Um registo completo da expedição proporciona visibilidade quase em tempo real sobre:
- Painéis de controlo do rastreio de expedições
- Aplicações de serviço de apoio ao cliente
- Sistemas de gestão de encomendas (OMS)
Atualize o registo da expedição com cada payload para manter a visão mais precisa e completa da expedição.
Notificações para clientes
Escolha uma estratégia de notificação com base nos requisitos da sua empresa e no nível de detalhe da expedição que pretende fornecer.
Os Tracking Webhooks da FedEx enviam atualizações sobre marcos do rastreio e alterações nos dados da expedição quase em tempo real. Utilize regras de negócio para determinar quais atualizações são relevantes para a sua empresa e quais podem ser ignoradas.
As estratégias comuns de notificação incluem:
Notificações praticamente em tempo real
Envie notificações imediatamente após ocorrer um marco de rastreio.
Vantagens
- Comunicação mais rápida com os clientes
- Tarifa mais baixa
Nota: informação adicional sobre a expedição pode ainda não estar disponível.
Notificações avançadas
Aguarde alguns minutos após um marco de rastreio para que possam chegar informações adicionais sobre a expedição.
Por exemplo, após um marco de entrega, aguarde alguns minutos para recolher:
- Prova de entrega (POD)
- Assinatura como prova de entrega (SPOD)
- Prova de entrega por GPS
- Informações do Destinatário
Vantagens
- Atualizações de expedição mais completas para os clientes
- Menos notificações de acompanhamento
- Redução dos contactos de apoio ao cliente
A FedEx recomenda aguardar aproximadamente cinco minutos após um marco de entrega porque as informações da prova de entrega são frequentemente adicionadas pouco depois do evento de entrega inicial.
Recomendações sobre o momento das notificações
O momento das notificações varia consoante o cliente e o caso de utilização. No entanto, as recomendações seguintes são habitualmente utilizadas para notificações pós-compra dirigidas aos destinatários. Para outros tipos de notificações (utilizadores empresariais, representantes do serviço de apoio ao cliente, etc.), escolha uma estratégia de notificação adequada ao seu caso de utilização.
- Entrega estimada: aguarde aproximadamente 15 minutos após estarem disponíveis tanto a Data de compromisso como a primeira data de entrega estimada (EDD).
- Saiu para entrega: envie imediatamente ou de acordo com o horário definido pela sua empresa (por exemplo, diariamente às 08:00).
- Entregue: aguarde aproximadamente 5 minutos para que cheguem os dados complementares da entrega.
- Tentativa de entrega: aplique a mesma abordagem que para Entregue para permitir que as informações de entrega cheguem.
Criação de regras de notificação com base nos dados da empresa
Nem todas as atualizações de expedição requerem uma notificação. Defina regras de notificação que satisfaçam os requisitos da sua empresa.
Abordagem recomendada
Não acione notificações apenas com base em eventCode.
Avalie:
- Marco de rastreio
- Dados obrigatórios da expedição
- Regras empresariais
Gere notificações apenas quando as informações necessárias estiverem disponíveis.
Esta abordagem ajuda a prevenir:
- Notificações duplicadas
- Informações de entrega em falta
- Notificações de entrega incompletas
- Notificações de acompanhamento desnecessárias
Registos de data/hora
Utilize o carimbo de data/hora adequado ao seu caso de utilização.
eventCreateTime: quando ocorreu o evento da expedição. Utilize-o para o histórico de rastreio apresentado aos clientes.- Hora de envio da mensagem: quando a FedEx enviou o payload do webhook. Utilize apenas para depuração e monitorização, não para experiências destinadas aos clientes.
O eventCreateTime reflete quando o evento da expedição ocorreu. A FedEx não atualiza este valor quando são adicionadas informações de expedição adicionais mais tarde. Por exemplo, um evento entregue mantém o respetivo eventCreateTime original, mesmo que payloads subsequentes adicionem informações de prova de entrega ou outras atualizações da expedição. Como resultado, o eventCreateTime deve ser utilizado para identificar quando o evento ocorreu e não quando foram adicionadas informações de expedição relacionadas.
Em alguns casos, a hora do evento pode não estar disponível. Quando tal acontece, o carimbo de data/hora pode conter um valor predefinido de 00:00:00. Os payloads adicionais podem incluir um carimbo de data/hora mais preciso quando este estiver disponível.
Boas práticas e problemas comuns de integração
Boas práticas
- Processe cada payload de webhook — cada mensagem pode conter um novo evento de rastreio ou uma atualização de dados da expedição.
- Integre as atualizações incrementais no seu registo de expedição existente.
- Monitorize tanto
scanEventcomopreviousEventspara captar o histórico completo da expedição. - Acione notificações aos clientes utilizando regras de negócio, não apenas eventos em bruto.
- Aguarde que os dados complementares esperados (por exemplo, PPOD, SPOD, GPS) cheguem antes de notificar os clientes.
- Conceba um processamento idempotente e resiliente que trate mensagens duplicadas e recebidas fora de ordem.
Problemas de integração comuns
- Partindo do princípio de que cada payload representa um novo marco de rastreio.
- Substituir o registo da expedição pelo payload mais recente.
- Basear-se apenas em
scanEvent. - Acionar notificações exclusivamente com base em
eventCode. - Assumir que o primeiro payload entregue contém todos os detalhes da entrega.
- Assumir que as mensagens de webhook chegam apenas uma vez ou por ordem cronológica.
Resumo
Processe cada payload de webhook como uma atualização do estado da expedição. Armazene e combine atualizações da expedição, monitorize tanto scanEvent como previousEvents e utilize regras de negócio para determinar quando atualizar aplicações ou notificar clientes.
Esta abordagem ajuda a garantir uma visibilidade precisa da expedição, um histórico completo de rastreio e comunicações mais informadas com os clientes.
