Skip to main content
ГлавнаяБлогРуководстваПочему ответ Tracking API содержит более старые данные, чем страница перевозчика? Причины и способы устранения

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

17TRACK

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

Почему ответ API отслеживания старше данных перевозчика

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

Найдите первое место, где исчезает обновление

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

  1. Зафиксируйте подтверждение от перевозчика. Запишите номер отслеживания, выбранного перевозчика, описание события, местоположение, отображаемое время события и время проверки страницы. Сохраните снимок экрана, не раскрывая информацию о клиенте.
  2. Запросите запись API напрямую. Используйте тот же номер отслеживания и выбор перевозчика, что и в рабочей интеграции. Сохраните необработанный ответ, время запроса, статус HTTP и любой предоставленный идентификатор запроса.
  3. Проверьте сохраненную запись. Сравните необработанный ответ с базой данных, журналами обработки вебхуков и конечной точкой, отображаемой клиенту.
  4. Сравните отдельные события. Сопоставьте описания, местоположения и временные метки, а не полагайтесь только на заголовок вроде «В пути».

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

Важные временные метки

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

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

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

Сохраняйте исходную временную метку и ее смещение, затем нормализуйте сопоставимые временные метки к UTC. RFC 3339 определяет формат временной метки, включающий UTC или числовое смещение. Если перевозчик предоставляет местное время без смещения, явно обрабатывайте эту неоднозначность; не предполагайте молча, что это UTC.

Распространенные причины и правильное решение для каждой

1. Веб-сайт и API используют разные пути публикации

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

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

2. Кэш предоставляет более старую версию данных

Кэширование может происходить в вашем приложении, шлюзе API, обратном прокси, браузере или инфраструктуре провайдера. Поведение HTTP-кэширования определено в RFC 9111, однако внутренний кэш отслеживания приложения может работать отдельно от заголовков HTTP-кэша.

Что делать: Сравните прямой ответ API с конечной точкой приложения. Проверьте соответствующие заголовки, включая Cache-Control и Age, если они присутствуют, а также собственные ключи кэша и правила истечения срока действия. Отсутствие заголовка Age не исключает кэширование на уровне приложения. Параметр запроса для обхода кэша не является надежным способом заставить провайдера повторно получить данные перевозчика.

3. Вебхук был задержан, отклонен или не применен

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

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

4. Отправление связано с неправильным перевозчиком или этапом перевозки

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

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

5. Нормализация создает впечатление неизменного статуса

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

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

6. Порядок или преобразование времени скрывает новое обновление

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

Что делать: Разбирайте временные метки до сортировки. Храните время события отдельно от времени импорта и используйте задокументированные идентификаторы последовательности, если они доступны. Явно определите правило выбора отображаемого события. Не допускайте, чтобы позднее историческое сканирование перезаписывало более поздний статус доставки только потому, что оно поступило последним.

7. Сбор данных отслеживания остановился или столкнулся с ошибкой

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

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

Превратите одно несоответствие в воспроизводимый тест

Используйте одно затронутое отправление, чтобы определить границу сбоя до изменения общесистемных настроек. Например, если страница перевозчика показывает событие доставки и прямой ответ API его содержит, но витрина по-прежнему показывает более раннее событие перемещения, непосредственная проблема находится после этого ответа API. Изменение upstream-опроса, скорее всего, не исправит эту запись.

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

Для постоянного мониторинга разделяйте три измерения: возраст последнего события отправления, возраст последнего успешного сбора данных, если он доступен, и задержку между получением обновления и его отображением. Старое событие отправления может быть нормальным во время спокойного этапа перевозки; необработанное уведомление — это другая операционная проблема.

Применение рабочего процесса к интеграции 17TRACK

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

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

Что включить в полезное обращение в службу поддержки

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

Эти сведения помогают отличить проблему upstream-канала от дефекта разбора, пропущенного уведомления или локального кэша. Не устанавливайте универсальную «допустимую задержку» без задокументированного обязательства службы. Используйте рекомендации провайдера и фактическое поведение собственной интеграции для определения операционных предупреждений.

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

Поможет ли более частый опрос быстрее получать обновления отслеживания?

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

Означает ли ответ 200 OK, что данные отслеживания актуальны?

Нет. Он указывает на успешность HTTP-запроса, но не на то, что новое событие перевозчика было собрано. Изучите тело ответа, ошибки на уровне отправления и задокументированные временные метки, чтобы понять, что представляет собой ответ.

Всегда ли следует доверять странице перевозчика больше, чем API?

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

Могут ли вебхуки устранить разницу?

Вебхуки могут снизить необходимость опроса доступных обновлений вашим приложением, но не гарантируют, что upstream-событие перевозчика уже было собрано. Кроме того, они требуют надежного получения и обработки. Если поддерживается, запрос сверки помогает обнаружить локальные записи, пропустившие обновление.

Что должны видеть клиенты, пока несоответствие не устранено?

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

Источники

  • RFC 9111: HTTP Caching — справочник по поведению HTTP-кэша и полям ответа, связанным с кэшированием.
  • RFC 3339: Date and Time on the Internet: Timestamps — справочник по форматам временных меток и числовым смещениям часовых поясов.
  • 17TRACK Tracking API — официальная отправная точка для интеграции с API, обсуждаемой в этом руководстве.
  • 17TRACK API documentation — справочник для проверки требований и поведения, применимых к интеграции 17TRACK.