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

В этом руководстве описывается данный рабочий процесс для разработчиков, подключающих платформу электронной коммерции, систему управления заказами, складское приложение или инструмент обслуживания клиентов. В нем рекомендации по проектированию приложения отделены от требований API конкретного поставщика. Для интеграции с 17TRACK используйте официальную документацию API, чтобы подтвердить схему запроса, аутентификацию, поддерживаемые операции и поля ответа перед реализацией приведенных ниже примеров.
Поймите, что делает регистрация, а чего она не делает
Регистрация отправления в сервисе отслеживания означает передачу идентификатора, чтобы сервис мог отслеживать отправление или управлять им в соответствии с условиями своего API. Это не то же самое, что покупка почтовых услуг, создание транспортной этикетки, бронирование забора отправления или передача посылки перевозчику.
В приложении необходимо разделять три результата:
- Запрос получен: API вернул ответ на ваш HTTP-запрос.
- Регистрация принята: сервис принял отдельную запись отслеживания для обработки.
- Информация об отслеживании доступна: сервис располагает информацией об отправлении, которую ваше приложение может получить или принять.
Эти результаты не следует объединять в единый флаг «успеха». Принятый номер отслеживания может пока не иметь событий перевозчика. Аналогично, успешный HTTP-ответ на пакетный запрос не означает, что каждый элемент пакета был принят; изучите структуру результата на уровне приложения, определенную поставщиком.
1. Подготовьте идентификатор отправления и конфигурацию API
Перед отправкой запроса на регистрацию решите, как отправление будет идентифицироваться в вашей системе. Одного идентификатора заказа обычно недостаточно, поскольку один заказ может быть разделен на несколько посылок. Создайте отдельную внутреннюю запись для каждой отправки или посылки и свяжите ее с соответствующим заказом.
Полезная внутренняя запись включает следующие сведения. Это рекомендуемые поля приложения, а не схема запроса 17TRACK.
- Внутренний идентификатор отправления: стабильный идентификатор посылки в вашей системе.
- Ссылка на заказ: заказ или запись о выполнении заказа, к которой относится отправление.
- Номер отслеживания: идентификатор, выданный перевозчиком; храните его как текст, чтобы сохранять начальные нули.
- Информация о перевозчике: идентификатор перевозчика, предоставленный вашей системой выполнения заказов, если он известен.
- Идентификатор поставщика: идентификатор, возвращенный сервисом отслеживания и необходимый для последующих операций.
- Состояние регистрации: сведения о том, ожидается ли отправка, принята ли она, отклонена или ожидает сверки.
- Состояние отслеживания: последний статус отправления, который хранится отдельно от состояния регистрации.
Проверяйте входные данные перед отправкой. Удаляйте случайные пробелы в начале и конце, но не изменяйте номер отслеживания на основании предположений о формате перевозчика. Сохраняйте исходное значение для устранения неполадок. Если перевозчик известен, сопоставьте его с документированным идентификатором перевозчика у поставщика, а не отправляйте неофициальное отображаемое имя.
Настройте аутентификацию на стороне сервера. Храните учетные данные вне системы контроля версий, разделяйте конфигурации разработки и рабочей среды и удаляйте секреты из журналов. Подтвердите документированную версию API, ограничения запросов, ограничения пакетных операций и требования к учетной записи, а не заимствуйте значения из несвязанной интеграции.
2. Зарегистрируйте отправление и сохраните результат для каждого элемента
Отправьте запись отслеживания с помощью операции регистрации, описанной в документации поставщика. Включайте только обязательные поля и необязательную информацию, имеющую определенную цель. Не отправляйте имена клиентов, адреса или другие персональные данные только потому, что они доступны в базе заказов.
Следующий псевдокод иллюстрирует последовательность действий приложения. Имена функций приведены только для примера; они не являются конечными точками API или методами SDK.
shipment = load_internal_shipment(shipment_id)
validate_tracking_input(shipment)
result = tracking_adapter.register(shipment)
if result.item_accepted:
save_registration_result(shipment_id, result)
elif result.outcome_unknown:
schedule_registration_reconciliation(shipment_id)
else:
save_registration_error(shipment_id, result)
route_for_retry_or_correction(result)Сохраняйте достаточно информации, чтобы объяснить произошедшее: внутренний идентификатор отправления, время отправки, номер попытки, результат для отдельного элемента и любую ссылку на запрос поставщика. Не полагайтесь только на временный журнал рабочего процесса. Службам поддержки клиентов и операционным командам нужен надежный ответ на вопрос, была ли отправка успешно зарегистрирована.
Обрабатывайте пакетные отправки по отдельности
Если API поддерживает пакетную регистрацию, сопоставляйте каждый возвращенный элемент с исходным отправлением. Не помечайте весь пакет как принятый только потому, что HTTP-запрос завершился успешно. Сохраняйте принятые элементы, изолируйте отклоненные и отдельно исследуйте неоднозначные результаты.
Это не позволит одному некорректному номеру отслеживания вызвать ненужные повторные попытки для уже успешно обработанных записей. Кроме того, операционные сотрудники получат действенный список записей, требующих исправления.
Считайте тайм-аут неизвестным результатом
Тайм-аут не доказывает, что регистрация завершилась неудачей. Поставщик мог принять запрос до того, как соединение было прервано. Используйте документированное поведение идемпотентности, обработку дубликатов или операции поиска, чтобы сверить результат перед повторной отправкой вслепую.
Если поведение поставщика при дубликатах неясно, протестируйте его на контролируемых записях и подтвердите условия до включения автоматических повторных попыток. Внутренняя дедупликация заданий регистрации по-прежнему полезна, но она не заменяет понимание того, как удаленный сервис обрабатывает повторные запросы.
3. Дождитесь поступления первой информации об отслеживании
После принятия регистрации данные отслеживания могут быть доступны не сразу. Этикетка может существовать до того, как перевозчик зафиксирует физическое событие обработки. Отсутствие информации также может означать необходимость проверить номер отслеживания, выбранного перевозчика или специальные требования к поиску отправления.
Явно отображайте это состояние. Формулировка «Зарегистрировано; ожидается информация об отслеживании» точнее, чем «В пути» или «Регистрация не выполнена». Не придумывайте оценку доставки или событие перемещения, чтобы заполнить пустой интерфейс.
Если запись остается пустой, проводите проверку в следующем практическом порядке:
- Подтвердите, что отдельная регистрация была принята.
- Сравните отправленный номер отслеживания с записью о выполнении заказа.
- Проверьте сопоставление перевозчика и все документированные дополнительные требования к поиску.
- Проверьте страницу отслеживания самого перевозчика для того же отправления.
- Если у перевозчика есть события, а в вашей интеграции их нет, изучите ответы при получении данных и свяжитесь с поставщиком API, предоставив диагностическую информацию без конфиденциальных данных.
Не применяйте универсальный период ожидания без подтверждающих данных. Правила эскалации должны учитывать службу доставки, ожидаемый процесс передачи и ваши собственные операционные обязательства.
4. Получайте данные отслеживания и правильно их интерпретируйте
Когда запись становится доступной, вызывайте документированную операцию получения подробностей отслеживания, используя требуемые идентификаторы. Не предполагайте, что регистрация и получение данных принимают одинаковые поля. Некоторые API различают номера отслеживания, идентификаторы перевозчиков и ссылки на записи, созданные поставщиком.
Приложение должно различать три уровня информации:
- Сводка по отправлению: общее состояние, используемое в панелях мониторинга, на страницах заказов и в операционных фильтрах.
- История событий: отдельные наблюдения, включая описания событий, временные метки и местоположения, если они предоставлены.
- Метаданные получения: сведения о том, когда приложение получило или запросило информацию и завершился ли запрос успешно.
Успешный поиск означает, что операция получения данных выполнена успешно. Это не означает, что посылка переместилась после предыдущего поиска. Сравнивайте возвращенную информацию отслеживания с сохраненной записью перед созданием уведомления или последующего рабочего процесса.
Храните время события отдельно от времени получения
Храните время, связанное с событием перевозчика, отдельно от времени его получения вашей системой. Событие, полученное сегодня днем, может описывать более раннее сканирование. Замена времени события временем получения создаст впечатление нового физического перемещения вместо старого обновления.
Сохраняйте исходную временную метку и указанный часовой сдвиг. Нормализуйте временные метки для сравнения только при известном часовом поясе. Если информация о часовом поясе отсутствует, сохраняйте эту неопределенность, а не молча назначайте часовой пояс сервера.
Сохраняйте исходный смысл вместе с нормализованным статусом
Нормализованный статус полезен для группировки отправлений разных перевозчиков, но исходное описание события может точнее объяснить операционную проблему. Сохраняйте оба значения, если они доступны. Одной общей категории исключения может быть недостаточно, чтобы сотрудник поддержки понял, нужно ли проверить адрес, связаться с получателем или дождаться следующего обновления.
Не делайте вывод о гарантии доставки, подтвержденной утрате или конкретном результате таможенного оформления на основании расплывчатого статуса. Принимайте меры в соответствии с исходной информацией и вашей операционной политикой.
5. Поддерживайте записи в актуальном состоянии с помощью опроса или вебхуков
Однократного получения данных достаточно для проверки соединения, но недостаточно для постоянного контроля отправления. Рабочая архитектура должна включать механизм обновления. Подтвердите механизмы, поддерживаемые выбранным поставщиком, и связанные с ними условия.
При использовании опроса приложение запрашивает данные отслеживания по расписанию. Планируйте запросы в пределах документированных ограничений, не запрашивайте повторно неизменившиеся записи без причины и применяйте экспоненциальную задержку для повторяемых сбоев. Открытие клиентом страницы заказа не должно автоматически запускать неограниченный запрос к внешнему сервису; сохраненное представление отслеживания может обслужить страницу, пока управляемый фоновый процесс обновляет данные.
Если вы используете вебхуки, проверяйте входящие запросы с помощью документированного механизма проверки поставщика. Сохраняйте принятые сообщения или помещайте их в надежную очередь до подтверждения получения в соответствии с условиями вебхука, а затем обрабатывайте события асинхронно.
Создайте приемник, устойчивый к дубликатам и неожиданному порядку поступления, если только документированные условия доставки не гарантируют обратное. При наличии используйте идентификатор события поставщика для дедупликации. В противном случае определите и протестируйте отпечаток на основе подходящих полей события, учитывая, что для ваших данных он может потребовать корректировок.
Интеграция на основе вебхуков также может использовать контролируемое получение данных для сверки. Например, задача восстановления может проверять записи, затронутые сбоем приемника. Это шаблон отказоустойчивости, а не разрешение игнорировать ограничения частоты запросов или рекомендации поставщика.
6. Превращайте информацию отслеживания в безопасные бизнес-действия
Обновляйте внутреннюю запись отправления до запуска действий, видимых клиенту. Храните надежную историю уведомлений и переходов рабочего процесса, чтобы повторное событие не создавало повторные сообщения.
Связывайте бизнес-действия со значимыми изменениями, а не с каждым ответом API. Недавно обнаруженное событие доставки может оправдывать уведомление о доставке. Повторный ответ с тем же событием — нет. Исключение может потребовать внутренней проверки, но сообщение клиенту должно отражать фактическое содержание события.
Определите, как обрабатывать события, полученные после того, как отправление считалось завершенным. Не удаляйте историю событий и не блокируйте навсегда все последующие обновления только потому, что сводка достигла конечного состояния. Правила хранения, сверки и уведомлений должны учитывать законные исправления, не открывая повторно завершенные рабочие процессы.
Применение рабочего процесса в интеграции с 17TRACK
Для пользовательской интеграции отслеживания отправной точкой являются страница Tracking API 17TRACK и его документация для разработчиков. Используйте страницу продукта для оценки предложения, а документацию — для определения фактических условий интеграции. Страницы отслеживания для потребителей не заменяют спецификации API.
До написания адаптера подтвердите формат аутентификации, операции регистрации и получения данных, правила идентификации перевозчика, обработку ответов на уровне отдельных элементов и применимые ограничения запросов. Для обработки на основе вебхуков также подтвердите схему полезной нагрузки, процесс проверки, требования к подтверждению получения и поведение при повторных попытках.
Храните эти сведения, зависящие от поставщика, внутри адаптера, а не распределяйте предположения о полях ответа по всей системе заказов. Тогда остальная часть приложения сможет работать с внутренними понятиями, такими как результат регистрации, статус отправления, история событий и время последней успешной синхронизации.
Проверки перед запуском, позволяющие обнаружить дорогостоящие ошибки
- Принято, но запись пуста: интерфейс показывает, что информация отслеживания ожидается, а не то, что посылка перемещается.
- Смешанный результат пакета: для каждого отправления сохраняется собственный результат.
- Тайм-аут после отправки: рабочий процесс сверяет неопределенный результат, а не предполагает сбой.
- Повторное событие: временная шкала отправления и уведомление клиенту остаются дедуплицированными.
- Более старое событие получено позднее: событие сохраняется, не заменяя вслепую более новую сводку.
- Внешний сервис недоступен: страница клиента может показать последний сохраненный результат с подходящей отметкой свежести.
- Неверное сопоставление перевозчика: запись можно исправить через документированный путь восстановления.
- Разделенный заказ: каждая посылка сохраняет собственное состояние отслеживания и историю событий.
- Раскрытие учетных данных или полезной нагрузки: журналы содержат диагностические ссылки, не раскрывая секреты или ненужные персональные данные.
Практический критерий завершенности — не просто получение успешного ответа регистрации. Необходимо уметь проследить путь посылки от отправки до обновлений, объяснить пустой или неудачный результат и восстановиться после прерванной обработки без потери событий или дублирования действий для клиентов.
Часто задаваемые вопросы
Создает ли регистрация номера отслеживания отправление?
Не в описанном здесь рабочем процессе. Регистрация отслеживания передает существующий идентификатор сервису отслеживания. Создание этикетки, покупка почтовых услуг и бронирование перевозчика являются отдельными операциями, если конкретный API явно не объединяет их.
Почему после успешной регистрации данные отслеживания пусты?
Принятие регистрации и доступность данных отслеживания — разные условия. Перевозчик мог еще не зафиксировать событие, либо необходимо проверить номер отслеживания, сопоставление перевозчика или дополнительные сведения для поиска. Изучите результат на уровне отдельного элемента, прежде чем считать регистрацию успешной.
Нужно ли регистрировать отправление каждый раз при получении его статуса?
Не используйте повторную регистрацию как стандартный механизм обновления. Сохраните состояние принятой регистрации и используйте документированный механизм получения или обновления данных. Следуйте явным правилам поставщика для исправлений, повторной активации или повторных отправок.
Следует ли использовать опрос или вебхуки?
Используйте механизм, соответствующий документированным условиям API и вашим операционным требованиям. Опрос требует управляемого расписания запросов. Вебхуки требуют безопасного надежного приемника и обработки, устойчивой к дубликатам. Если это поддерживается, обновления через вебхуки с целевой сверкой могут обеспечить практический путь восстановления.
Можно ли использовать номер отслеживания как единственный идентификатор отправления в базе данных?
Используйте внутренний идентификатор отправления. Храните номер отслеживания и соответствующий контекст перевозчика как атрибуты этой записи. Это упрощает работу с разделенными заказами, исправленными номерами отслеживания и ссылками поставщика, не меняя идентичность внутреннего отправления.
Источники
- 17TRACK Tracking API — официальная отправная точка продукта для оценки интеграции API 17TRACK.
- Документация API 17TRACK — официальный источник форматов запросов, операций, ответов и требований к интеграции. Псевдокод и предложения по внутренним полям в этом руководстве являются примерами проектирования приложения, а не цитатами из условий данного API.


