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

Как отправить несколько номеров отслеживания в одном API-запросе (ограничения пакетной обработки и частичные сбои)

17TRACK

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

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

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

Сначала определите, что именно делает пакетная конечная точка

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

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

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

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

Ограничения пакета — это не только максимальное количество отправлений

У Tracking API нет универсального ограничения размера пакета. Ограничения могут различаться в зависимости от провайдера, конечной точки, версии API и настроек учётной записи. Перед реализацией пакетной обработки зафиксируйте эти ограничения отдельно.

ОграничениеЧто необходимо подтвердитьПоследствие для реализации
Количество элементов в запросеМаксимальное количество записей для конкретной операцииРазделять входной список перед отправкой
Размер тела запросаЛюбое задокументированное ограничение в байтахУчитывать дополнительные поля и размер сериализации
Частота запросовРазрешённое количество запросов за определённый интервалРегулировать запросы через общий ограничитель
ПараллелизмЛюбое ограничение на одновременные запросыОграничить количество активных рабочих процессов
Учёт использованияУчитывается ли использование по запросам, отправлениям или другой единицеОценивать потребление отдельно от количества запросов

Например, если гипотетическая конечная точка разрешает 25 записей в одном запросе, для 63 записей потребуются три запроса, содержащие 25, 25 и 13 записей. Эти числа иллюстрируют только разделение на части; они не являются ограничениями 17TRACK.

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

Подготовьте записи перед формированием запроса

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

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

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

Иллюстративная структура запроса

Следующий JSON демонстрирует концепцию пакетной полезной нагрузки. Обёртка, имена свойств и идентификаторы являются иллюстративными и не представляют схему запроса 17TRACK. Некоторые API ожидают массив верхнего уровня вместо объекта, содержащего массив.

{
  "shipments": [
    {
      "tracking_number": "EXAMPLE000001",
      "carrier_id": "DOCUMENTED_CARRIER_ID"
    },
    {
      "tracking_number": "EXAMPLE000002",
      "carrier_id": "DOCUMENTED_CARRIER_ID"
    }
  ]
}

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

Обрабатывайте ответ на двух уровнях

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

Уровень 1: Был ли получен пригодный для использования ответ?

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

Семантика HTTP определена в RFC 9110. Однако документация провайдера определяет, как поля результата на уровне приложения соотносятся с фактическими результатами по отправлениям.

Уровень 2: Что произошло с каждым отправлением?

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

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

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

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

Обрабатывайте частичные сбои, не повторяя успешные записи

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

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

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

HTTP 429 означает слишком большое количество запросов, и ответ может содержать заголовок Retry-After, как описано в RFC 6585. Не предполагайте, что этот заголовок присутствует всегда. Если явная задержка для повторной попытки не указана, используйте ограниченную стратегию экспоненциальной задержки, соответствующую документации API.

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

Почему тайм-ауты требуют особого подхода

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

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

Практический рабочий процесс пакетной обработки

Храните детали, зависящие от провайдера, в адаптере, чтобы логика очереди, планировщика повторных попыток и мониторинга не зависела от необработанных имён полей ответа.

проверить записи и сохранить локальные идентификаторы отправлений
разрешить дубликаты в пределах заданной области бизнеса
разделить записи с учётом задокументированных ограничений элементов и полезной нагрузки

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

    если результат неопределён:
        поставить согласование в очередь
        продолжить

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

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

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

Отслеживайте результаты по отправлениям, а не только доступность HTTP

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

  • Доля принятия элементов: Принятые записи, разделённые на отправленные записи, с чётко определённым учётом повторных попыток.
  • Распределение сбоев: Количество по конечной точке, задокументированному коду ошибки и соответствующему контексту перевозчика.
  • Неизвестные результаты: Несогласованные записи и время, в течение которого они остаются нерешёнными.
  • Очередь повторных попыток: Ожидающие повторы, возраст самой старой повторной попытки и исчерпанные попытки.
  • Состояние запросов: Задержка, тайм-ауты, ограничение частоты и ошибки сервера.
  • Актуальность отслеживания: Получают ли принятые отправления впоследствии пригодную для использования информацию об отслеживании.

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

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

Проверьте эти случаи до выхода в рабочую среду

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

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

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

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

Сколько номеров отслеживания можно отправить в одном запросе?

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

Может ли один недопустимый номер отслеживания привести к сбою всего пакета?

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

Следует ли повторять пакет, если HTTP-ответ успешен?

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

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

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

Ускоряет ли пакетная обработка получение обновлений отслеживания?

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

Источники

  • 17TRACK Tracking API — официальная отправная точка продукта для разработчиков, оценивающих интеграцию отслеживания.
  • Документация 17TRACK API — справочная информация о контракте конечной точки провайдера, ограничениях, аутентификации и обработке ответов.
  • RFC 9110: Семантика HTTP — семантика HTTP-статусов, идемпотентность, автоматические повторы и Retry-After.
  • RFC 6585: Дополнительные коды состояния HTTP — определение HTTP 429 Too Many Requests и необязательного заголовка Retry-After.