Webhook-уведомления FedEx для отслеживания обеспечивают обновление статуса отправлений в режиме, близком к реальному времени, на протяжении всего их жизненного цикла.

В отличие от API отслеживания, требующих от приложений самостоятельно запрашивать статус отправления, механизм webhook автоматически доставляет обновления по мере появления новой информации.

Содержание руководства

• Три принципа интеграции
• Как работает webhook
• Обработка полезных данных webhook
• Уведомления для клиентов
• Метки времени
• Рекомендации и типичные проблемы с интеграцией

Для успешной интеграции webhook следует придерживаться трех принципов.

Рассматривайте любые полезные данные webhook как обновление статуса отправления

Не следует считать, что все полезные данные обозначают новое контрольное событие отслеживания. FedEx публикует новые полезные данные по мере появления новых сведений об отправлении.

Полезные данные могут содержать следующие сведения:

• новое событие отслеживания;
• обновленный прогноз доставки;
• информацию о подтверждении доставки;
• Информация о получателе
• другие изменения в данных об отправлении.

Несколько блоков полезных данных могут относиться к одному и тому же контрольному событию отслеживания, но при этом содержать разную информацию об отправлении.

Сохраняйте и объединяйте данные об отправлении

Каждый блок полезных данных может содержать новую или обновленную информацию об отправлении. Сохраняйте все полезные данные webhook без исключения и объединяйте новую информацию с существующими записями об отправлениях.

Не перезаписывайте существующие записи об отправлениях последними полезными данными, а сохраняйте их, включая новую информацию. Таким образом вы обеспечите полноту и актуальность записи об отправлении на каждом этапе.

Используйте бизнес-правила для инициации действий

Бизнес-правила позволяют определить, когда нужно обновлять системы или уведомлять клиентов.

Не инициируйте действия, основываясь только на коде события. Прежде чем обновлять клиентские приложения или отправлять уведомления, проверьте следующее:

• контрольные события отслеживания;
• доступность отправления;
• время уведомления;
• требования организации.

Рекомендуемая модель обработки данных

На схеме ниже показано, как три принципа интеграции webhook работают в комплексе при типичной реализации. Каждый блок полезных данных webhook обрабатывается как обновление статуса отправления, объединяется с централизованной записью об отправлении и оценивается с помощью бизнес-правил до обновления приложений и отправки уведомлений.

Важно! Для одного и тоже контрольного события отслеживания может быть создано несколько блоков полезных данных webhook. Чтобы гарантировать добавление новой информации в запись об отправлении, обрабатывайте все полезные данные.

Обрабатывайте все полезные данные webhook как обновления статуса отправления.

Не следует считать, что все полезные данные webhook обозначают новое контрольное событие отслеживания. FedEx отправляет новые полезные данные по мере появления новых сведений об отправлении. Например, для доставленного отправления могут создаваться дополнительные полезные данные, когда добавляется или обновляется информация о подтверждении доставки, данные получателя или другие сведения об отправлении.

При оценке полезных данных в каждом случае постарайтесь ответить на приведенные ниже вопросы.

• Какое контрольное событие отслеживания изменилось?
• Какая информация об отправлении изменилась?
• Влияет ли обновление на клиентское приложение для отслеживания?
• Инициирует ли обновление отправку уведомления?

Обработка истории отправления

Отслеживайте оба параметра scanEvent и previousEvents.

• Параметр scanEvent содержит информацию о текущем контрольном событии отслеживания, связанном с полезными данными.
• Параметр previousEvents содержит дополнительную историю отправления, в том числе контрольные события, которые могут не отображаться как текущие события scanEvent.

Некоторые контрольные события отслеживания содержатся в данных previousEvents и не публикуются как новые события scanEvent. Приложения, которые обрабатывают только данные scanEvent, могут пропускать обновленные сведения об отправлении и формировать неполные истории отправлений. Обрабатывайте оба набора данных, чтобы получить полное представление об отправлении.

Поддержание актуальности записи об отправлении

Сохраняйте все полезные данные webhook без исключения и объединяйте новую информацию с существующими записями об отправлениях.

Полная запись об отправлении предоставляет актуальную информацию в режиме, близком к реальному времени:

• на информационных панелях для отслеживания отправлений;
• в приложениях клиентского сервиса;
• в системах обработки заказов.

Обновляйте запись об отправлении с каждым пакетом полезных данных, чтобы сохранять максимально точные и полные сведения о нем.

Выбирайте стратегию уведомлений, исходя из потребностей вашей организации и желаемого уровня детализации сведений об отправлении.

Механизм webhook FedEx для отслеживания доставляет обновления контрольных событий отслеживания и изменения данных об отправлении в режиме, близком к реальному времени. Используйте бизнес-правила, чтобы определить, какие обновления важны для вашей организации, а какие можно игнорировать.

Распространенные стратегии уведомлений:

Уведомления в режиме, близком к реальному времени

Отправка уведомлений сразу при наступлении контрольного события отслеживания.

Преимущества

• Самое быстрое взаимодействие с клиентами.
• Минимальная задержка.

Примечание. Дополнительные сведения об отправлении могут быть пока недоступны.

Подробные уведомления

Подождите несколько минут после контрольного события отслеживания, чтобы поступила дополнительная информация об отправлении.

Это позволит вам собрать, например, следующие сведения:

• подтверждение доставки (POD);
• подтверждение доставки подписью получателя (SPOD);
• Подтверждение доставки с использованием GPS
• Информация о получателе

Преимущества

• Более полные сведения об отправлениях для клиентов.
• Меньше лишних уведомлений.
• Сокращение количества обращений клиентов в поддержку.

FedEx рекомендует ожидать после контрольного события доставки около пяти минут, поскольку подтверждающая информация часто добавляется в скором времени после первого события доставки.

Рекомендации по времени уведомления

Выбор времени уведомления зависит от клиента и цели. Однако для уведомлений, отправляемых получателям после совершения покупки, часто применимы приведенные ниже рекомендации. Для уведомлений прочих типов (отправляемых корпоративным клиентам, представителям отделов по работе с клиентами и т. д.) следует выбирать стратегии исходя из целесообразности.

• Ожидаемая доставка: подождите около 15 минут после того, как станут доступны дата фиксации и первая дата ожидаемой доставки.
• Передано для доставки: отправьте сразу же или по вашему рабочему графику (например, ежедневно в 08:00).
• Доставлено: подождите около пяти минут, пока не поступят подробности о доставке.
• Попытка доставки: примените тот же подход, что и к уведомлениям о событии «Доставлено», чтобы дождаться поступления информации о доставке.

Создание правил уведомлений на основе корпоративных данных

Не все новые сведения об отправлении требуют отправки уведомлений. Определите правила для уведомлений в соответствии с потребностями вашей организации.

Рекомендуемый подход

Не инициируйте отправку уведомлений, основываясь только на данных eventCode.

Учитывайте:

• контрольное событие отслеживания;
• требуемые данные об отправлении;
• бизнес-правила.

Создавайте уведомления, только если необходимая информация доступна.

Такой подход позволяет предотвратить:

• дублирование уведомлений;
• утрату сведений о доставке;
• недостаточность сведений в уведомлениях о доставке;
• отправку избыточных уведомлений.

Используйте целесообразные метки времени.

• eventCreateTime: время наступления события отправления. Используется в клиентской истории отслеживания.
• Время отправки сообщения: время отправки полезных данных webhook FedEx. Используется только для устранения неполадок и мониторинга, не предназначено для предоставления клиентам.

eventCreateTime означает время наступления события отправления. FedEx не обновляет это значение при дальнейшем добавлении дополнительной информации об отправлении. Например, событие доставки сохраняет исходное значение eventCreateTime, даже если последующие полезные данные вносят информацию о подтверждении доставки или другие новые сведения об отправлении. По этой причине значение eventCreateTime используется для определения момента наступления события, а не времени добавления связанной информации об отправлении.

В некоторых случаях время наступления события может быть недоступно. И тогда метка времени содержит значение по умолчанию: 00:00:00. При появлении более точной метки времени она может быть включена в дополнительные полезные данные.

Рекомендации

• Обрабатывайте каждый блок полезных данных webhook. Каждое сообщение может содержать новое событие отслеживания или новые данные об отправлении.
• Включайте поступающие обновления в существующую запись об отправлении.
• Отслеживайте оба параметра scanEvent и previousEvents. Таким образом вы будете фиксировать историю отправления в полном объеме.
• Инициируйте отправку уведомлений клиентам на основе бизнес-правил, а не просто необработанных событий.
• Заложите время на ожидание дополнительных данных (например, о подтверждении доставки с помощью фото, подписи получателя или GPS) перед отправкой уведомлений клиентам.
• Спроектируйте идемпотентный и отказоустойчивый механизм обработки, который корректно справляется с дубликатами и сообщениями, пришедшими не по порядку.

Наиболее частые ошибки интеграции

• Считать, что каждый блок полезных данных обозначает новое контрольное событие отслеживания.
• Перезаписывать сведения об отправлении новыми полезными данными.
• Полагаться только на данные scanEvent.
• Инициировать отправку уведомлений, основываясь исключительно на данных eventCode.
• Считать, что первый блок полезных данных о доставке содержит все подробности.
• Считать, что сообщения webhook поступают однократно или в хронологическом порядке.

Обрабатывайте все полезные данные webhook как обновления статуса отправления. Храните и объединяйте обновления об отправлении, отслеживайте оба параметра scanEvent и previousEvents, и применяйте бизнес-правила, чтобы определять, когда следует обновлять приложения или уведомлять клиентов.

Такой подход помогает обеспечить точное отображение сведений об отправлении, полноту истории отслеживания и большую информированность при взаимодействии с клиентами.