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

Как зарегистрировать номер отслеживания через API: поля запроса, коды перевозчиков и ответы

17TRACK

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

Как зарегистрировать трек-номер через поля API-запроса

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

Что делает регистрация — и чего она не делает

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

Разделяйте эти три события в своем приложении:

  • Отправление создано: ваша система доставки назначила трек-номер.
  • Регистрация принята: сервис отслеживания принял отправление для отслеживания.
  • Информация об отслеживании получена: события перевозчика стали доступны через сервис отслеживания.

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

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

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

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

Поле или значениеНазначениеПравило реализации
Трек-номерИдентифицирует отправление для отслеживания.Храните и передавайте его как строку; сохраняйте ведущие нули.
Идентификатор перевозчикаИдентифицирует перевозчика в системе поставщика отслеживания.Используйте идентификатор, указанный поставщиком, а не внутренний код склада.
Внутренняя ссылкаСвязывает регистрацию с записью об отправлении.Используйте поддерживаемое поле ссылки, если оно доступно; в любом случае сохраняйте собственное сопоставление в базе данных.
Дополнительные идентификационные данныеМогут помочь идентифицировать отправление, если перевозчику требуется больше, чем только трек-номер.Передавайте только поля, документированные для данной интеграции и перевозчика.
Учетные данные APIАутентифицируют вызывающую учетную запись.Храните их на сервере и исключайте из журналов приложения.

Рассматривайте трек-номер как идентификатор

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

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

Храните ссылки на заказы отдельно от идентификаторов отправлений

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

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

Выберите правильный код перевозчика

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

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

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

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

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

Пример: отправка запроса на регистрацию в 17TRACK

В следующем примере показаны эндпоинт регистрации 17TRACK v2.2, заголовок аутентификации 17token и массив, содержащий один объект с трек-номером. Перед развертыванием убедитесь, что эта версия и ее требования к запросу соответствуют вашей учетной записи и официальной документации. Трек-номер является заполнителем и должен быть заменен реальным идентификатором отправления.

curl --request POST \
  --url 'https://api.17track.net/track/v2.2/register' \
  --header "17token: ${TRACKING_API_TOKEN}" \
  --header 'Content-Type: application/json' \
  --data '[
    {
      "number": "YOUR_TRACKING_NUMBER"
    }
  ]'

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

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

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

Читайте ответ на трех уровнях

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

1. Результат HTTP и передачи данных

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

2. Результат на уровне запроса

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

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

3. Результат на уровне отправления

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

Нормализуйте ответы поставщика в собственные стабильные состояния приложения. Например, в базе данных можно использовать accepted, rejected и uncertain. Это рекомендуемые внутренние состояния, а не буквальные значения ответов 17TRACK. Сохраняйте исходный ответ поставщика в соответствии с надлежащей политикой хранения и доступа, чтобы разработчики могли исследовать расхождения.

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

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

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

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

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

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

Отслеживайте регистрацию отдельно от обновлений отслеживания

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

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

Практическая производственная проверка должна отвечать на следующие вопросы:

  1. Имеется ли запись о регистрации для каждого отправления, ожидающего отслеживания?
  2. Можно ли связать каждую принятую регистрацию с правильной посылкой?
  3. Направляются ли отклоненные элементы ответственному, который может исправить исходные данные?
  4. Согласуются ли неопределенные запросы, вместо того чтобы быть оставленными или повторяться бесконечно?
  5. Формируются ли статусы, отображаемые клиенту, на основе событий отправления, а не принятия регистрации?
  6. Исключены ли из журналов учетные данные и ненужная персональная информация?

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

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

Можно ли зарегистрировать трек-номер до первого сканирования перевозчиком?

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

Всегда ли нужно указывать код перевозчика?

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

Почему API вернул успешный HTTP-ответ, хотя отправление завершилось ошибкой?

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

Что делать, если запрос на регистрацию завершился по тайм-ауту?

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

Настраивает ли регистрация уведомления об отслеживании автоматически?

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

Источники

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