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

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

17TRACK

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

Как проверять номера отслеживания перед отправкой в API: 7 правил

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

Что может и чего не может подтвердить проверка

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

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

Семь правил

1. Нормализуйте значение, не изменяя его смысл

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

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

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

2. Отклоняйте значения, не проходящие базовые структурные проверки

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

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

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

3. Используйте контекст перевозчика, а не делайте выводы только по номеру

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

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

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

4. Применяйте контрольные суммы только при наличии документированного правила

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

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

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

5. Разделяйте проверку формата и допустимость для API

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

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

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

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

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

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

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

7. Подтверждайте результат после отправки и отслеживайте ложноположительные результаты

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

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

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

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

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

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

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

Контрольный список реализации

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

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

Может ли регулярное выражение проверить номер отслеживания?

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

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

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

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

Нет. Контрольная сумма, если она применима, проверяет лишь соответствие значения математическому правилу. Она не подтверждает, что перевозчик выдал этот номер или что посылка поступила в сеть.

Что делать, если перевозчик неизвестен?

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

Как следует обрабатывать ошибки API?

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

Источники

  • Документация 17TRACK API — рекомендации по запросам и интеграции для разработчиков API отслеживания.
  • 17TRACK Tracking API — официальная информация о продукте и варианты использования API.
  • Отслеживание USPS — официальная страница отслеживания перевозчика и рекомендации для клиентов.
  • Отслеживание UPS — официальная страница отслеживания перевозчика.