Tracking API или Shipping API: что нужно вашему стеку электронной коммерции (или оба API)?

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

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

В чем разница между API отслеживания и API доставки?

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

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

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

Создание отправления — не то же самое, что наблюдение за его перемещением

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

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

Выберите возможность, которая устраняет текущее узкое место

Выбирайте API доставки, если отсутствует этап отправки

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

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

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

Выбирайте API отслеживания, если создание отправлений уже работает

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

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

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

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

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

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

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

Как оба API вписываются в ecommerce-стек

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

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

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

Назначьте одного ответственного за каждое последующее действие

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

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

Сравнивайте операционную пригодность, а не названия функций

Проверьте фактически используемых перевозчиков и услуги

Поддержка перевозчика — это не простой вопрос «да» или «нет». Сервис может поддерживать отслеживание для перевозчика, но не поддерживать создание этикеток для него. Создание этикеток также может зависеть от страны отправления, настроек учетной записи перевозчика или доступности услуги.

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

Изучите значение событий и полноту данных

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

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

Проверьте восстановление после сбоев с обеих сторон

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

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

Сравнивайте общую стоимость эксплуатации, не предполагая конкретную модель оплаты

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

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

Изучите безопасность и хранение данных

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

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

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

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

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

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

FAQ

Всегда ли API доставки включает отслеживание?

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

Могу ли я отслеживать посылки, этикетки которых создал партнер по выполнению заказов?

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

Сделает ли API отслеживания сканирование перевозчиком более быстрым?

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

Нужны ли мне два провайдера API, чтобы использовать обе возможности?

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

Может ли API отслеживания заменить систему управления заказами?

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

Источники

• Документация FedEx Ship API — справочник по созданию отправлений, этикеткам и требованиям процессов доставки.
• Документация FedEx tracking API — справочник по запросам отслеживания и информации о статусе отправлений.
• 17TRACK Tracking API — официальный справочник продукта для категории интеграций отслеживания.
• Документация 17TRACK API — справочник по регистрации отслеживания, данным отслеживания и интеграции push-уведомлений.