Skip to main content
ГлавнаяБлогРуководстваКак получить последний статус отправления через API, не дожидаясь Webhook

Как получить последний статус отправления через API, не дожидаясь Webhook

17TRACK

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

Как получить последний статус отправления через API без

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

Определите, что означает «последний статус отправления»

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

ОперацияЧто она делаетЧего она не устанавливает
Чтение собственной базы данныхВозвращает информацию об отслеживании, которую ваше приложение уже хранит.Получил ли провайдер более новое обновление.
Запрос к API отслеживанияИзвлекает информацию, доступную через операцию запроса провайдера.Происходил ли новый запрос к перевозчику во время этой операции.
Запрос на обновление отслеживанияЗапрашивает ещё одну проверку у внешнего источника, если провайдер поддерживает такую операцию.Наличие нового сканирования у перевозчика или синхронное завершение обновления.

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

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

Проверьте контракт запроса до написания кода

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

  • Идентификатор отправления: принимает ли запрос номер отслеживания, внутренний ID отправления или номер отслеживания вместе с идентификатором перевозчика?
  • Требования к регистрации: нужно ли зарегистрировать отправление до того, как его можно будет запросить?
  • Аутентификация: какой заголовок или механизм аутентификации требуется?
  • Значение ответа: возвращает ли операция сохранённую информацию, инициирует сбор данных или возвращает задачу для последующей проверки?
  • Обработка результата: может ли успешный HTTP-ответ содержать ошибку на уровне отправления или результат в состоянии ожидания?
  • Ограничения использования: какие применяются ограничения частоты запросов, пакетных операций и аккаунта?
  • Поля актуальности: какие временные метки относятся к событиям перевозчика, обновлениям провайдера и формированию ответа?

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

Не фиксируйте в коде предположения о поведении обновления или частоте запросов. Эти детали должны соответствовать используемой операции и условиям сервиса.

Создайте получение данных по требованию через backend

Практичный вариант — предоставить аутентифицированный endpoint в собственном приложении. Браузер запрашивает обновление отправления у этого endpoint; сервер проверяет права доступа, решает, нужен ли запрос к провайдеру, и возвращает нормализованный результат.

Следующий маршрут является примером endpoint, который вы создаёте в своём приложении. Это не endpoint 17TRACK и не спецификация запроса провайдера.

GET /api/orders/{order_id}/shipment-status

Используйте идентификатор заказа, чтобы найти отправление на сервере. Не позволяйте вызывающей стороне получать историю отслеживания другого клиента простой заменой номера отслеживания в запросе. Храните учётные данные API провайдера на backend, а не в JavaScript браузера или пакете мобильного приложения.

Процесс запроса, который можно реализовать

  1. Авторизуйте доступ. Убедитесь, что клиент или сотрудник имеет право просматривать заказ.
  2. Определите отправление. Считайте сохранённый идентификатор отслеживания и данные о перевозчике, если применимо.
  3. Проверьте локальную актуальность. Если недавний успешный запрос уже существует, повторно используйте его в соответствии с политикой актуальности вашего приложения.
  4. Запросите провайдера при необходимости. Используйте документированную операцию и ограниченный тайм-аут запроса.
  5. Проверьте результат. Проверьте как исход HTTP-запроса, так и результат на уровне отправления.
  6. Объедините информацию. Применяйте те же правила нормализации и согласования, которые используются для событий webhook.
  7. Верните статус и сведения об актуальности. По возможности включите время последнего события и время последней успешной проверки провайдера.

Локальная политика актуальности — это инженерное решение, а не утверждение о частоте обновлений перевозчика. Выбирайте её с учётом требований интерфейса, ограничений провайдера, объёма отправлений и фактической полезности запросов. Многократные нажатия клиентом кнопки обновления не должны создавать неограниченный поток запросов к внешнему источнику.

Нормализуйте ответ, не выдумывая сведения об актуальности

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

{
  "shipment_id": "internal-shipment-id",
  "status": "in_transit",
  "latest_event_at": null,
  "provider_updated_at": null,
  "last_successful_query_at": null,
  "retrieval_state": "success",
  "source": "provider_query"
}

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

В интерфейсе клиента разделяйте сообщения: «Последнее событие перевозчика» описывает активность отправления, а «Отслеживание проверено» — активность приложения по получению данных. Это различие не позволяет представить неизменившееся сканирование как новое.

Не позволяйте API-запросам и webhook перезаписывать данные друг друга

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

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

  • Используйте единый конвейер обновлений. Направляйте результаты запросов и payload webhook через одни и те же функции проверки, нормализации и сохранения.
  • Удаляйте дубликаты событий. Предпочтительно использовать документированный идентификатор события. Если его нет, создайте тщательно определённый отпечаток на основе доступных полей, например времени события, статуса, местоположения и описания.
  • Используйте поля порядка с известной семантикой. Документированная ревизия или последовательность полезнее предположения, что время получения определяет порядок событий.
  • Сохраняйте историю. Недавно полученное событие может заполнить пробел в истории, не изменяя текущую сводку по отправлению.
  • Допускайте исправления. Статусы не являются универсальной линейной лестницей. Следуйте документированному поведению исправлений, а не навсегда отклоняйте каждый кажущийся переход назад.

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

По-разному обрабатывайте отсутствие данных и ошибки запросов

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

Запрос выполнен успешно, но статус не изменился

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

Для отправления пока нет информации об отслеживании

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

Запрос провайдеру завершился по тайм-ауту или ошибкой

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

Используйте ограниченное число повторных попыток с задержкой и случайным разбросом для подходящих временных ошибок. Не повторяйте запросы с недействительными учётными данными или некорректным форматом. Если ответ содержит Retry-After, интерпретируйте его в соответствии с контрактом провайдера и семантикой HTTP. Спецификация HTTP допускает представление этого значения в виде задержки в секундах или даты HTTP.

Для одного отправления поступает несколько запросов

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

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

Без webhook плановый polling может поддерживать актуальность базы данных, но для него необходима чёткая операционная политика. Определите, какие отправления остаются доступными для проверки, как ошибки влияют на расписание и когда регулярный polling прекращается.

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

  • Отдавайте приоритет активным отправлениям и записям с неустранёнными ошибками получения данных.
  • Не запрашивайте каждое историческое отправление при каждом плановом запуске.
  • Определите обработку завершённых отправлений, включая необходимое вашему бизнесу окно исправлений.
  • Отслеживайте, как часто запросы находят действительно новую информацию.
  • Исследуйте проблемы доставки webhook, а не маскируйте их всё более частым polling.

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

Протестируйте процесс до выпуска

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

  • Webhook поступает, пока запрос по требованию ещё выполняется.
  • Два клиента или сотрудника одновременно запрашивают одно и то же отправление.
  • Провайдер возвращает успешный HTTP-ответ, но сообщает об ошибке на уровне отправления.
  • Запрос завершается ошибкой после того, как приложение уже получило действительную информацию об отслеживании.
  • В событии отсутствует часовой пояс или содержится незнакомый код статуса.
  • Исправление перевозчика меняет ранее отображавшийся результат.
  • Пользователь пытается получить доступ к отправлению, принадлежащему другому аккаунту.

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

FAQ

Заставляет ли запрос к API перевозчика отсканировать или обновить посылку?

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

Можно ли использовать API-запросы без настройки webhook?

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

Как часто следует проверять статус отправления с помощью polling?

Универсального интервала не существует. Выберите расписание с учётом ограничений провайдера, объёма отправлений и бизнес-ценности более раннего обнаружения обновлений. Измеряйте, как часто polling возвращает новые события, и корректируйте расписание, не предполагая, что частые запросы обеспечивают более свежие данные перевозчика.

Почему API возвращает информацию, которую я уже получил через webhook?

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

Должна ли кнопка обновления называться «Обновить отслеживание»?

Только если такая формулировка точно описывает операцию. Если кнопка получает сохранённые данные провайдера, понятнее будет «Проверить обновления». Отображайте последнее событие перевозчика отдельно от времени последней успешной проверки приложения.

Источники

  • 17TRACK Tracking API — официальная информация о продукте для интеграции с API отслеживания, рассматриваемой в этом руководстве.
  • Документация API 17TRACK — справочник по операциям провайдера, аутентификации, полям запросов и обработке ответов.
  • RFC 9110, раздел 10.2.3: Retry-After — определяет формы HTTP-заголовка delay-seconds и HTTP-date.