Skip to main content
ГлавнаяБлогРуководства6 проверок, чтобы убедиться, что последние события отслеживания перевозчика синхронизированы через ваш API

6 проверок, чтобы убедиться, что последние события отслеживания перевозчика синхронизированы через ваш API

17TRACK

Чтобы убедиться, что ваш API синхронизировал последние события отслеживания перевозчика, проверьте идентификатор отправления, временные метки событий, сведения о событиях, маршрут доставки, порядок событий и актуальность данных, сравнив их с независимым представлением отслеживания. Успешный ответ API или подтверждение webhook подтверждает только одну часть этой цепочки; само по себе это не доказывает, что ваше приложение получило новейшее событие перевозчика.

6 проверок для подтверждения синхронизации последних событий отслеживания перевозчика

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

Перед началом: определите, что означает «последнее»

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

Перед расследованием выберите точку сравнения. В идеале используйте страницу отслеживания перевозчика или другую авторизованную запись, предоставленную перевозчиком, для того же отправления. Если это недоступно, сравните ваше приложение с текущим ответом API провайдера отслеживания. Такое более узкое сравнение может показать, соответствует ли ваше приложение провайдеру; оно не доказывает, что провайдер уже получил каждое сканирование перевозчика. Зафиксируйте время сравнения, чтобы последующее обновление не сделало ранний результат кажущимся несогласованным.

1. Убедитесь, что обе системы относятся к одному и тому же отправлению

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

  • Найдите точный номер отслеживания и перевозчика, переданные в API отслеживания.
  • Убедитесь, какая внутренняя запись отправления или посылки получила ответ.
  • Проверьте, не было ли отправление заменено, разделено, отменено или повторно связано после регистрации.
  • Сравните перевозчика и номер в исходной записи с данными, отображаемыми в вашем приложении.

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

2. Сравнивайте время событий, не теряя его смысла

Для каждого возможного последнего события зафиксируйте указанное перевозчиком время возникновения, его часовой пояс или смещение, если они предоставлены, а также время получения и сохранения в вашем приложении. Приведите временные метки к единой основе для сравнения, но сохраните исходное значение. RFC 3339 определяет формат интернет-временной метки с явной информацией о смещении; это полезный ориентир при проектировании собственных полей времени. Однако он не гарантирует, что перевозчик или провайдер указывает часовой пояс для каждого события.

Отображение только времени без даты, предполагаемый местный часовой пояс или парсер, который незаметно отбрасывает смещение, могут перенести событие на другой календарный день или поместить его в неправильную последовательность. Если источник указывает неоднозначное местное время, пометьте сравнение как неопределенное, а не придумывайте точный момент UTC. Также отличайте время возникновения события от времени ответа API: ответ, полученный сейчас, вполне может содержать событие, произошедшее ранее.

Запишите время, в которое вы проверяли представление перевозчика или провайдера. Если источник опубликовал новое сканирование после вашего запроса к API, различие между двумя представлениями не доказывает, что предыдущий запрос завершился ошибкой.

3. Проверяйте содержимое события, а не только общий статус

Сравните описание последнего события, местоположение, статус или код перевозчика и все относящиеся к доставке поля с исходной записью. Нормализованный статус, например «в пути», может обобщать несколько разных сканирований. Если ваше приложение хранит только сводный статус, он может выглядеть неизменным, даже если поступило новое событие.

Проверьте исходный ответ API или сохраненное тело webhook, если это допускается правилами обработки данных. Затем проследите путь события через разбор, сопоставление полей, сохранение и отображение. Ищите случаи, когда значения null перезаписываются значениями по умолчанию, неожиданные коды статуса попадают в общую категорию, текст обрезается или интерфейс показывает только выбранные типы событий. Несоответствие названий статусов отличается от пропущенного события: оно указывает на логику преобразования или отображения, а не на доставку.

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

4. Проследите, как событие попало в ваше приложение

Если вы используете webhooks, проверьте журнал получения для соответствующего отправления и события. Убедитесь, что ваша конечная точка приняла запрос, сообщение прошло проверку, а последующая обработка завершилась. Успешный HTTP-ответ от вашей конечной точки не доказывает, что последующий обработчик очереди сохранил событие. Если обработка выполняется асинхронно, изучите как входящий запрос, так и результат выполнения задания.

Если вы опрашиваете API, проверьте последний завершенный запрос, идентификатор отправления в этом запросе, его ответ, а также логику постраничной выборки или получения данных, используемую вашей интеграцией. После успешного запроса все еще может произойти ошибка записи в базу данных или чтение устаревшего кэша. Используйте соответствующую документацию провайдера, чтобы проверить фактические поля ответа, требования к аутентификации и правила доставки для вашей интеграции, вместо того чтобы предполагать, что каждый API отслеживания работает по одному и тому же контракту. Для интеграции с 17TRACK соответствующими отправными точками являются его страница Tracking API и документация API; проверьте документированное поведение используемых вами конечной точки и метода.

Сделайте обработку событий безопасной для повторного выполнения. Повторная попытка не должна создавать дублирующиеся сканирования, многократно отправлять одно и то же уведомление клиенту или заменять более новое сохраненное состояние старой полезной нагрузкой. Подходящий ключ дубликата зависит от полей, которые действительно предоставляет ваш провайдер. Проверьте выбранный ключ на разных событиях, у которых случайно совпадают статус или временная метка; такие события не должны объединяться только потому, что выглядят похожими.

5. Проверьте правила порядка и переходов состояний

Отсортируйте записанные события по четко определенному правилу, затем изучите результат. Многие приложения должны различать «последнее произошедшее событие» и «последнее полученное нами событие». Задержанное раннее сканирование может прийти после более нового сканирования. Если база данных просто делает последнее обработанное сообщение текущим состоянием отправления, такое задержанное сканирование может вернуть отображаемый статус назад.

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

Для практической проверки возьмите отправление с несколькими событиями и воспроизведите его сообщения в другом порядке поступления в непроизводственной среде. Убедитесь, что история событий остается полной, а статус для клиентов соответствует задокументированному правилу. Это выявляет дефекты порядка, которые невозможно обнаружить при обычном тестировании с последовательным поступлением.

6. Измерьте актуальность и согласуйте исключения

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

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

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

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

Часто задаваемые вопросы

Означает ли успешный ответ webhook, что последнее событие синхронизировано?

Нет. Это показывает, что ваша конечная точка вернула успешный ответ на запрос. Убедитесь, что проверка, обработка очереди, сохранение в базе данных и отображение также завершились успешно. Проверьте полезную нагрузку, чтобы установить, какое событие содержал запрос.

Почему на странице перевозчика отображается более новое сканирование, чем в моем ответе API?

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

Следует ли выбирать последний статус по временной метке события или по времени его получения моей системой?

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

Что делать, если статус API не изменился, но в списке событий появилась новая запись?

Это может быть ожидаемо, если несколько событий перевозчика сопоставляются с одним нормализованным статусом. Сравните сведения о событиях и убедитесь, что приложение сохранило и отображает новую запись там, где это необходимо. Рассматривайте пропущенное событие и неизменную сводную метку как разные проблемы.

Источники