Skip to main content
ГлавнаяБлогРуководстваКакие данные должен возвращать Tracking API? 12 полей помимо текущего статуса?

Какие данные должен возвращать Tracking API? 12 полей помимо текущего статуса?

17TRACK

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

Какие данные должен возвращать API отслеживания: 12 полей помимо статуса

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

Что делает данные отслеживания полезными?

Текущий статус отвечает на один узкий вопрос: каково обобщенное состояние отправления? Он не обязательно объясняет, что произошло, когда это произошло, насколько свежей является информация и что следует сделать дальше.

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

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

12 полей, которые следует оценивать помимо текущего статуса

1. Идентификаторы отправления и отслеживания

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

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

2. Идентификация перевозчика

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

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

3. Нормализованная детализация статуса

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

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

4. Исходные сообщения и коды перевозчика

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

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

5. История событий отслеживания

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

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

6. Временные отметки событий и сведения о часовых поясах

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

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

7. Местоположения событий и география отправления

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

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

8. Расчетная дата или интервал доставки

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

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

9. Причина исключения и требуемое действие

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

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

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

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

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

11. Результат доставки и ссылки на подтверждение

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

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

12. Актуальность, состояние получения и метаданные ответа

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

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

Отсутствующие данные должны иметь определенное значение

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

  • Неизвестно: Значение еще не установлено.
  • Не предоставлено: Источник не предоставил значение в полученных данных.
  • Неприменимо: Поле не относится к этой записи или состоянию.
  • Ошибка получения: Система не смогла завершить соответствующий запрос.

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

Как протестировать ответ перед интеграцией

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

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

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

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

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

Должны ли все 12 групп данных быть заполнены для каждого отправления?

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

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

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

Какая временная отметка должна определять последнее событие?

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

Может ли API отслеживания подтвердить, что посылка потеряна?

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

Достаточно ли статуса «Доставлено», чтобы закрыть жалобу клиента?

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

Источники