Как интегрировать API отслеживания отправлений в ваш интернет-магазин
Чтобы интегрировать API отслеживания отправлений в ваш интернет-магазин, подключите систему заказов к поставщику отслеживания, передавайте данные об отправлении и перевозчике через защищённый запрос на стороне сервера, сохраняйте нормализованные события отслеживания и отображайте полученный статус в интерфейсах для клиентов и службы поддержки. Надёжная реализация — это больше, чем добавление поля с номером отслеживания: она должна учитывать выбор перевозчика, обновления статуса, исключения при доставке, повторные попытки, конфиденциальность и то, как клиенты фактически используют информацию после покупки.
В этом руководстве описывается практический подход к интеграции для владельцев магазинов, разработчиков и операционных команд. В качестве ориентира используется официальная документация 17TRACK по Tracking API, однако те же принципы планирования применимы при оценке другого поставщика услуг отслеживания для нескольких перевозчиков.
Определите, чего должна достичь интеграция
Начинайте с бизнес-результата, а не с конечной точки API. Большинство магазинов стремятся сократить количество обращений «Где мой заказ?», предоставить покупателям понятную информацию о доставке и помочь операционной команде выявлять задержанные отправления до того, как клиент пожалуется. Для этих целей требуются разные данные и рабочие процессы.
- Видимость для клиентов: отображение текущего статуса отправления, расчетной информации о доставке, если она доступна, сведений о перевозчике и последнего значимого события.
- Операционная видимость: возможность находить задержанные, застрявшие, возвращённые отправления или отправления с исключениями у разных перевозчиков.
- Автоматизированная коммуникация: запуск одобренных уведомлений по электронной почте, SMS или через другие каналы, когда отправление достигает определённого состояния.
- Согласованность данных: преобразование разных обозначений событий перевозчиков в меньшее количество статусов, которые магазин может надёжно использовать.
Определите эти результаты до выбора способа реализации. API отслеживания может предоставлять данные об отправлении, но не определяет автоматически, какие события требуют уведомления клиента или как магазин должен обрабатывать проблему с адресом.
Выберите подходящую архитектуру интеграции
Типичная архитектура состоит из четырёх уровней: торговая платформа, сервис интеграции, поставщик отслеживания и интерфейс для клиентов. Сервисом интеграции может быть серверное приложение, система управления заказами или бессерверный рабочий процесс. Размещение этой логики на сервере обычно безопаснее, чем хранение учётных данных API в коде браузера.
Базовый процесс выглядит следующим образом:
- Оплаченный заказ комплектуется и получает номер отслеживания и данные о перевозчике.
- Ваш сервер передаёт сведения об отправлении поставщику отслеживания.
- Поставщик возвращает идентификатор отслеживания или данные отслеживания в соответствии со своей архитектурой API.
- Ваша система сохраняет ссылку на поставщика и сопоставляет события отправления с внутренними статусами.
- Запланированный процесс обновления или поддерживаемое уведомление о событии обновляет данные об отправлении.
- Ваш интернет-магазин, страница заказа, инструменты поддержки и сервис уведомлений считывают данные из собственного нормализованного хранилища.
Не заставляйте каждую загрузку страницы обращаться к перевозчику или API отслеживания. Такая архитектура может привести к медленной работе для клиентов, дублированию запросов, проблемам с ограничениями частоты и непоследовательным результатам. Храните последнее принятое состояние отслеживания в базе данных и обновляйте его с помощью контролируемых фоновых задач или поддерживаемого поставщиком механизма обновления.
Перед написанием кода изучите документацию поставщика
Перед реализацией изучите официальную документацию поставщика по аутентификации, форматам запросов, полям ответов, поддерживаемым перевозчикам, обработке ошибок, механизмам обновления и требованиям к аккаунту. 17TRACK предоставляет отдельную страницу продукта Tracking API и документацию для разработчиков. Считайте эти страницы источником актуальной информации о работе API, а не примеры, скопированные с форумов или из старых руководств по интеграции.
Составьте по документации краткий список требований:
- Как выдаются, хранятся, обновляются и отзываются учётные данные API?
- Требуется ли для запроса код перевозчика или сервис может определить перевозчика по номеру отслеживания?
- Какие поля ответа идентифицируют отправление, статус, местоположение, временные отметки и сообщение об исключении?
- Как доставляются асинхронные обновления, если аккаунт их поддерживает?
- Каковы документированные ограничения запросов, правила тарификации, ожидаемые тайм-ауты и коды ошибок?
- Как следует обрабатывать дублирующиеся номера отслеживания, недействительные номера, неизвестных перевозчиков и доставленные отправления?
Не делайте вывод о наличии функции только по названию продукта. Например, «в реальном времени» может описывать позиционирование продукта, а не гарантировать немедленное отображение каждого события перевозчика. Ваша реализация должна объяснять, что сканирование перевозчиком может задерживаться и что API не может создать событие сканирования, о котором перевозчик не сообщил.
Подготовьте данные о заказе и отправлении
Обычно наиболее подходящий момент для создания отслеживания — выполнение отправления, а не создание заказа. Заказ может быть оплачен, но ещё не упакован, а номер отслеживания может быть создан до того, как посылка будет принята перевозчиком. Определите, какое событие в вашем процессе выполнения заказа должно создавать запись отслеживания.
Как минимум внутренняя запись об отправлении должна различать следующие значения:
- Внутренний идентификатор заказа и идентификатор выполнения
- Номер отслеживания
- Название или код перевозчика
- Страна или регион назначения, если это необходимо для работы
- Идентификатор отслеживания у поставщика или ссылка на подписку, если они возвращаются
- Текущий нормализованный статус
- Временная отметка последнего события и последней синхронизации
- Исходный ответ поставщика или контролируемая ссылка на аудит
Храните данные заказа и данные отправления отдельно. Один заказ может содержать несколько посылок, разделённые отправления или отправления разных перевозчиков. Предположение о соответствии одного заказа одному номеру отслеживания часто не работает, когда склад отправляет товары отдельно.
Используйте идемпотентный процесс. Если система выполнения заказа повторяет тот же запрос, интеграция должна обновить существующее отправление, а не создавать дублирующиеся подписки или повторные сообщения клиентам. Практический ключ идемпотентности может объединять внутренний идентификатор выполнения, идентификатор перевозчика и номер отслеживания с учётом собственных требований поставщика.
Нормализуйте статусы перевозчиков для клиентов
Перевозчики используют разные обозначения и последовательности событий. Ваш магазин должен поддерживать небольшую внутреннюю модель статусов, например Информация получена, В пути, Передано курьеру для доставки, Доставлено, Исключение и Возвращено. Сохраняйте исходное событие перевозчика для сотрудников поддержки, но используйте нормализованный статус в логике интернет-магазина.
Правила нормализации должны быть явными. Событие «этикетка создана» не следует представлять как доказательство движения посылки. Статус «Доставлено» следует рассматривать как событие, о котором сообщил перевозчик, а не как гарантию того, что клиент физически нашёл посылку. Исключение не следует молча преобразовывать в «в пути» только потому, что отправление позднее может продолжить движение.
Также определите приоритет статусов и обработку возврата к предыдущему состоянию. Задержанный поток данных перевозчика может поступать не по порядку. Сравнивайте временные отметки событий, если они доступны, сохраняйте исходное событие и не заменяйте более новый статус «доставлено» старым статусом «в пути». Если временные отметки отсутствуют или неоднозначны, помечайте запись для консервативного обновления, а не придумывайте последовательность.
Создайте поток запросов на стороне сервера
Ваш сервер должен проверять входящие данные о выполнении заказа перед обращением к поставщику отслеживания. Убедитесь, что номер отслеживания указан, удалите случайные пробелы, при необходимости проверьте ожидаемый формат и подтвердите допустимость значения перевозчика. Не отклоняйте необычные, но действительные номера отслеживания только потому, что они не соответствуют узкому локальному шаблону.
Поток запросов, независимый от конкретного поставщика, можно представить так:
receive fulfillment event
validate order and shipment fields
check for an existing idempotency key
send the documented tracking request from the server
store the provider response and internal shipment record
queue a refresh or process the supported update event
publish only approved fields to the storefrontИспользуйте короткие тайм-ауты, ограниченное число повторных попыток и экспоненциальную задержку для временных сбоев. Не повторяйте каждый запрос при любой ошибке. Ошибка аутентификации, недействительный запрос или неподдерживаемый перевозчик обычно требуют исправления, а не повторных вызовов. Записывайте идентификатор корреляции, результат запроса и категорию ошибки поставщика, но не сохраняйте в журналах приложения ключи API, полные адреса клиентов или лишнюю персональную информацию.
Храните ответ поставщика отдельно от модели, предназначенной для клиентов. Это упрощает смену поставщика, исправление правила сопоставления и ограничение информации, раскрываемой на публичной странице заказа.
Спроектируйте клиентский интерфейс отслеживания
Страница отслеживания должна быстро отвечать на три вопроса: каково текущее состояние, что произошло последним и что клиенту делать дальше? Показывайте ссылку на заказ, номер отправления в форме, учитывающей конфиденциальность, название перевозчика, время последнего события и понятное объяснение исключений.
Не показывайте пустую шкалу событий так, будто это техническая ошибка. До первого сканирования перевозчиком объясните, что информация об отправлении получена, но движение ещё может быть невидимым. Для исключения предоставляйте объяснение простым языком только тогда, когда исходные данные это подтверждают. Если перевозчик сообщает о проблеме с адресом, добавьте ссылку на процесс поддержки или действие службы поддержки клиентов, которое ваша компания действительно может выполнить.
Для магазинов на Shopify или другой торговой платформе проверьте, как платформа предоставляет события выполнения, аккаунты клиентов, страницы статуса заказа и шаблоны уведомлений. Официальная документация разработчика Shopify содержит ресурсы по вебхукам и данным о выполнении заказов. API платформ и версионируемая документация могут меняться, поэтому перед работой в рабочей среде подтвердите версию, используемую вашим приложением.
Осторожно используйте уведомления
События отправления полезны как триггеры, но отправка сообщения при каждом сканировании перевозчика может вызвать усталость от уведомлений. Определите бизнес-правила, например уведомление о создании отправления, значимом продвижении в пути, передаче курьеру для доставки, доставке и отдельных исключениях. Подавляйте дубликаты и задавайте минимальный интервал для повторных сообщений о задержке.
Разделяйте операционные оповещения и уведомления клиентов. Службе поддержки может потребоваться узнать, что статус отправления не менялся несколько дней, тогда как клиенту сообщение может понадобиться только при конкретном исключении, о котором сообщил перевозчик. Порог времени должен учитывать уровень сервиса, направление, перевозчика и способ доставки, а не универсальное число без операционного обоснования.
Тестируйте реальные сценарии доставки
Успешный ответ для одного номера отслеживания недостаточен для запуска в рабочей среде. Создайте матрицу тестирования, включающую нескольких перевозчиков, страны, типы отправлений и состояния событий. Протестируйте как минимум:
- Недавно созданное отправление без сканирования перевозчиком
- Обычное отправление в пути
- Отправление, переданное курьеру для доставки
- Доставленное отправление
- Исключение или событие, связанное с адресом
- Возвращённое отправление
- Недействительный номер отслеживания
- Дублирующее событие выполнения заказа
- Задержанный ответ поставщика или тайм-аут
- Событие, поступившее не по порядку
Измеряйте не только доступность API. Проверяйте, обновляется ли правильный заказ, видит ли клиент понятный текст, подавляются ли повторные уведомления и могут ли сотрудники поддержки определить исходное событие перевозчика. Сначала выполните ограниченный запуск, сохраните операционный резервный вариант и после выпуска отслеживайте категории ошибок.
Безопасность, конфиденциальность и обслуживание
Храните учётные данные в менеджере секретов или защищённой переменной окружения, а не в коде темы, мобильном коде, системе контроля версий или запросах браузера. Ограничивайте доступ к данным об отправлениях по ролям, используйте HTTPS и проверяйте, как долго хранятся исходные ответы и поля, связанные с клиентами.
Регулярно изучайте документацию поставщика и версию API вашей торговой платформы. Поддержка перевозчиков, названия событий, требования к аутентификации и поведение вебхуков платформы могут меняться. Сделайте правила сопоставления статусов настраиваемыми, документируйте лежащие в их основе предположения и обеспечьте возможность повторно обработать или сверить отправление без отправки ещё одного сообщения клиенту.
API 17TRACK — подходящий вариант для оценки, когда магазину требуется специализированная интеграция отслеживания для разных перевозчиков. Однако правильный выбор по-прежнему зависит от используемых перевозчиков, стран обслуживания, поведения обновлений, описанного для вашего аккаунта, ожидаемого объёма запросов и операционных средств контроля, необходимых вашей команде. Подтвердите эти моменты в официальной документации и в контролируемом proof of concept до принятия решения о проектировании рабочей системы.
Часто задаваемые вопросы
Следует ли создавать отслеживание при оформлении заказа?
Обычно нет. Создавайте или активируйте запись отправления, когда в процессе выполнения заказа уже определены перевозчик и номер отслеживания. Создание записи на этапе оформления заказа может привести к появлению записей для заказов, которые впоследствии отменяются, не выполняются или разделяются.
Может ли API отслеживания гарантировать информацию о доставке в реальном времени?
Нет. Ни один API не может гарантировать немедленное отображение каждого сканирования перевозчика. Поставщик зависит от данных перевозчика, а системы перевозчиков могут сообщать о событиях с задержками или пропусками. Точно указывайте временные отметки и статусы и не обещайте точное время обновления, если соответствующая документация и соглашение об обслуживании не поддерживают такое обещание.
Должен ли браузер напрямую обращаться к API отслеживания?
В большинстве реализаций — нет. Используйте интеграцию на стороне сервера, чтобы сохранить учётные данные в безопасности, нормализовать ответы, контролировать повторные попытки и фильтровать данные, предназначенные для клиентов. Интернет-магазин обычно должен считывать из вашего приложения одобренное представление данных об отправлении.
Как магазину обрабатывать несколько посылок в одном заказе?
Моделируйте каждое выполнение заказа или посылку как отдельное отправление, сохраняя при этом идентификатор родительского заказа. На странице заказа можно показывать общую сводку и отдельные шкалы событий для каждой посылки. Это не позволит скрыть задержанную посылку за статусом «доставлено» другой посылки.
Какой показатель следует контролировать первым после запуска?
Контролируйте полный процесс — от создания выполнения заказа до корректного обновления, видимого клиенту. Одного показателя успешности API недостаточно. Отслеживайте дублирующиеся записи, устаревшие отправления, несопоставленные события, сбои уведомлений и процент отправлений, требующих ручного исправления.
