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

Это руководство предназначено для разработчиков и операционных команд электронной коммерции, создающих такой процесс. Цель не в том, чтобы пересылать каждый скан перевозчика. Нужно сообщать клиентам, когда происходит что-то важное, что означает это изменение и требуется ли им действие.
Спроектируйте процесс уведомлений до подключения API
API отслеживания отправлений предоставляет информацию об отслеживании; ваше приложение решает, как её использовать. Рассматривайте видимость отправления и коммуникацию с клиентом как отдельные задачи, даже если выбранный вами сервис предлагает обе функции.
Практическая архитектура состоит из шести этапов:
- Связывание с заказом: при необходимости свяжите трек-номер и идентификатор перевозчика с внутренней записью об отправлении.
- Регистрация отслеживания: отправьте или зарегистрируйте отправление в соответствии с требованиями интеграции поставщика.
- Получение обновлений: принимайте обратные вызовы webhook, получайте обновления через API-запросы или сочетайте оба подхода.
- Обработка событий: проверяйте, нормализуйте, удаляйте дубликаты и оценивайте входящие события.
- Решение об уведомлении: определяйте, нужно ли отправлять уведомление, кому, через какой канал и с каким шаблоном.
- Доставка сообщения: отправляйте уведомление и сохраняйте ответ сервиса сообщений.
Храните контактные данные клиентов в собственной системе заказов или сообщений, если интеграция действительно не требует их передачи. Сервису отслеживания обычно не нужен адрес электронной почты клиента только для того, чтобы ваше приложение связало событие отслеживания с заказом.
1. Подтвердите условия интеграции
Перед написанием обработчика изучите документацию поставщика: аутентификацию, регистрацию отправлений, идентификацию перевозчика, поддерживаемые методы обновления, форматы ответов, ограничения запросов и обработку ошибок. Для интеграций webhook также проверьте, как аутентифицируются обратные вызовы, какой ответ подтверждает получение и как обрабатываются неуспешные доставки.
Для реализации с 17TRACK начните со страницы API отслеживания 17TRACK и официальной документации API. Используйте документированные условия интеграции, а не воспринимайте приведённые в руководстве названия полей как поля запросов или ответов 17TRACK. До реализации подтвердите настройки обратных вызовов, требования безопасности и ограничения конкретной учётной записи.
Выбирайте метод обновления в соответствии с условиями интеграции:
- Webhooks: используйте обратные вызовы, если они поддерживаются и подходят вашей инфраструктуре. Это позволяет приложению обрабатывать обновления при их отправке поставщиком без повторных запросов одного и того же отправления.
- Опрос: получайте информацию об отслеживании по расписанию, если обратные вызовы недоступны или не подходят. Соблюдайте документированные ограничения запросов.
- Комбинированный подход: используйте обратные вызовы для обычной обработки и выборочное получение данных через API для сверки отправлений, обновления которых выглядят устаревшими, если поставщик поддерживает такой процесс.
Не обещайте клиентам мгновенные уведомления только потому, что используете webhooks. Приложение не может сообщить о событии перевозчика до того, как исходные данные отслеживания станут доступны.
2. Создайте запись об отправлении, устойчивую к реальным заказам
Используйте внутренний идентификатор отправления как основной reference, а не только трек-номер. Заказ может содержать несколько посылок, и нельзя считать, что трек-номера всегда глобально уникальны.
Полезная внутренняя запись включает:
- Внутренние идентификаторы заказа и отправления.
- Трек-номер и идентификатор перевозчика, если известен.
- Идентификатор отправления у поставщика, если он предоставляется.
- Текущий нормализованный статус и последнее важное событие.
- Время события у перевозчика, включая часовой пояс или смещение, если доступны.
- Время получения обновления вашей системой.
- Ссылку на настройки коммуникации клиента.
- Историю уведомлений и активный процесс обработки исключений.
Храните время события отдельно от времени получения. Сканирование, произошедшее раньше, может прийти после более нового сканирования. Если приложение сортирует события только по порядку поступления, оно может ошибочно изменить статус доставленного отправления обратно на «в пути».
Для разделённых заказов связывайте уведомления с соответствующей посылкой. Если другая посылка ещё в пути, фраза «Одна посылка из вашего заказа доставлена» точнее, чем «Ваш заказ доставлен».
3. Сопоставляйте события отслеживания с решениями клиента
Описания перевозчика — это операционные данные, а не готовые сообщения для клиентов. Создайте слой нормализации, который сохраняет исходное событие и одновременно присваивает ему внутреннюю категорию, понятную правилам уведомлений.
Ниже приведены рекомендуемые прикладные категории, а не универсальный словарь статусов API:
| Внутренняя категория | Решение об уведомлении | Граница формулировки |
|---|---|---|
| Информация об отправлении получена | Отправляйте сообщение о подготовке, только если это полезно. | Не создавайте впечатление, что перевозчик физически получил отправление, только на основании создания этикетки. |
| В пути | Рассмотрите уведомление о первом значимом перемещении. | Подавляйте обычные сканы на объектах, если они не меняют следующий шаг клиента. |
| Передано курьеру для доставки | Уведомляйте, когда поддерживаемое событие указывает на этот статус. | Не превращайте статус в гарантированное время прибытия. |
| Попытка доставки или требуется получение | Отправляйте уведомление с конкретным действием. | Включайте сроки или инструкции по получению только после проверки. |
| Исключение при доставке | Оцените причину и необходимость действий клиента. | Не описывайте каждое исключение как потерю посылки. |
| Доставлено | Отправляйте подтверждение на уровне посылки. | Не выдумывайте получателя, место доставки или подтверждение доставки. |
Сохраняйте неопределённость. Нераспознанное событие должно попасть на проверку или в резервный процесс, а не принудительно относиться к ближайшей знакомой категории. Сохраняйте исходное описание для специалистов поддержки.
4. Получайте обновления без потери или дублирования работы
Конечная точка webhook должна проверять запрос, надёжно сохранять принятое обновление и возвращать подтверждение, требуемое поставщиком. Формируйте сообщения асинхронно, не ожидая ответа сервиса электронной почты или SMS во время обработки обратного вызова.
Реализуйте документированный поставщиком метод проверки обратных вызовов. Не придумывайте заголовок подписи и не предполагайте, что все поставщики используют одинаковую схему аутентификации. Также применяйте HTTPS, ограничения размера запроса, проверку полезной нагрузки и соответствующие средства контроля доступа.
Упрощённый процесс обработки выглядит так. Это операции на уровне приложения, а не рабочий пример SDK:
receive callback
verify request using documented provider mechanism
validate payload
persist accepted payload and enqueue processing atomically
return documented acknowledgment
process queued update
find internal shipment
normalize relevant events
ignore already-processed events
evaluate chronology and state transition
create notification job if policy permits
commit state and job together
send notification job
check recipient preferences and suppression rules
submit message to messaging service
record result and retry only when appropriateАтомарные шаги имеют значение. Если приложение сохранит изменение статуса, но завершится до создания задания уведомления, клиент может никогда не получить сообщение. Транзакционный outbox — один из вариантов проектирования: сохраняйте изменение состояния и ожидающее задание в одной транзакции базы данных, а затем поручайте worker отправку задания.
Явно обрабатывайте неизвестные ссылки на отправления. Помещайте их в карантин для расследования или сверки вместо того, чтобы угадывать, какой клиент должен получить уведомление.
5. Добавьте защиту от дубликатов и проверки хронологии
Проектируйте обработчик так, чтобы он выдерживал повторные обратные вызовы и повторные попытки worker. Если поставщик документирует стабильный идентификатор события, отдавайте ему предпочтение. В противном случае создавайте детерминированный отпечаток события из подходящих полей, например внутреннего идентификатора отправления, кода события, времени события и местоположения. Проверьте этот отпечаток на реальных полезных нагрузках, прежде чем полагаться на него.
Удаление дубликатов событий и подавление уведомлений решают разные задачи. Удаление дубликатов не позволяет обработать одно событие дважды. Подавление не даёт нескольким различным сканам создавать практически одинаковое сообщение клиенту.
Определяйте идентичность уведомления вокруг бизнес-события. Для подтверждения доставки можно использовать идентификатор отправления и этап доставки. Для попытки доставки может потребоваться идентификатор конкретной попытки, поскольку следующая попытка может быть действительно новым событием.
Для обновлений, поступивших не по порядку, сравнивайте временные метки событий и проверяйте допустимые переходы состояний. Не предполагайте, что обратный вызов содержит только новый скан; выясняйте, представляет ли его документированная структура отдельное событие, снимок или историю. Противоречивые обновления направляйте на сверку, а не молча отбрасывайте все исправления.
6. Пишите сообщения, объясняющие следующий шаг
Каждое уведомление должно указывать соответствующую посылку, подтверждённое изменение и следующий шаг клиента. Добавляйте безопасную ссылку отслеживания и понятную ссылку на заказ. Не раскрывайте полные адреса или лишнюю личную информацию в SMS и предварительных уведомлениях на экране блокировки.
Например:
- Передано курьеру для доставки: «Ваша посылка по заказу {order_reference} передана для доставки. Следите за её перемещением здесь: {tracking_link}.»
- Предпринята попытка доставки: «Перевозчик сообщил о попытке доставки вашей посылки. Проверьте страницу отслеживания, чтобы узнать доступные следующие шаги: {tracking_link}.»
- Доставлено: «Перевозчик отметил вашу посылку по заказу {order_reference} как доставленную. Просмотрите доступные сведения о доставке: {tracking_link}.»
Выводите placeholders только на основе проверенных данных. Если доступна и подходит для отображения оценка доставки, помечайте её как оценочную. Если она отсутствует, не указывайте её вместо того, чтобы выдумывать дату.
Для исключений различайте проблему с отправлением и задачу клиента. Сбой может требовать только объяснения; подтверждённая проблема с адресом может требовать действия. Не отправляйте клиентов на страницу оплаты или загрузки документов только на основании непроверенного текстового содержимого отслеживания.
Выбирайте каналы с учётом предпочтений клиента, разрешений канала, срочности и применимых правил. Проверьте требования к согласию, отказу от рассылки и тихим часам для используемых юрисдикций и каналов сообщений. Отделяйте уведомления службы доставки от рекламных кампаний, а не предполагайте, что одни и те же разрешения распространяются на оба типа сообщений.
7. Определите, что происходит, когда обновления отслеживания прекращаются
Проактивная коммуникация должна охватывать не только новые события, но и отсутствие прогресса, однако само по себе молчание не доказывает, что отправление задержано или потеряно.
Создайте правило устаревшего отслеживания с учётом уровня сервиса, маршрута, последнего значимого события и доступной оценки доставки. Устанавливайте пороги на основе операционных данных и процесса поддержки, а не применяйте один универсальный период ожидания ко всем отправлениям.
Когда правило срабатывает, проверьте пропущенную обработку, выполните сверку с источником отслеживания, если это поддерживается, и решите, нужно ли создать внутреннюю задачу поддержки. Если вы уведомляете клиента, используйте формулировку, соответствующую известным фактам: «Мы не получили нового обновления отслеживания» отличается от «Ваша посылка потеряна».
Назначайте ответственного за нерешённые исключения. Система уведомлений, которая постоянно сообщает о проблеме, не создавая пути к её решению, может усилить раздражение клиентов.
8. Протестируйте полный процесс до включения автоматической отправки
Сначала запустите процесс в теневом режиме: принимайте реальные или одобренные тестовые события, формируйте предлагаемые уведомления и проверяйте результаты, не связываясь с клиентами.
- Повторите идентичный обратный вызов и убедитесь, что новое сообщение не создаётся.
- Обработайте более старое событие перемещения после события доставки и проверьте итоговое состояние.
- Протестируйте отсутствующие временные метки, неизвестные статусы и некорректные полезные нагрузки.
- Смоделируйте сбой базы данных до подтверждения и сбой worker после сохранения.
- Протестируйте тайм-ауты службы сообщений, включая неопределённый ответ, когда сервис уже мог принять сообщение.
- Убедитесь, что для разделённых отправлений используются формулировки для конкретной посылки.
- Проверьте получателей, отказавшихся от рассылки, недействительные контактные данные и обработку тихих часов.
- Убедитесь, что ссылки отслеживания не раскрывают данные заказа другого клиента.
Отслеживайте принятые обратные вызовы, ошибки обработки, возраст очереди, задания уведомлений, подавление дубликатов и результаты отправки сообщений. Измеряйте задержку обработки от времени получения вашей системой отдельно от возраста события перевозчика. Это помогает определить, возникла ли задержка уведомления из-за доступности исходных данных или из-за собственного конвейера.
Начните с небольшого набора хорошо понятных этапов. Расширяйте правила только после того, как команды поддержки и операционного управления согласуют, что сообщения точны, полезны и заслуживают получения.
Часто задаваемые вопросы
Отправляет ли API отслеживания отправлений электронные письма или SMS автоматически?
Не обязательно. Доступ к данным отслеживания и обмен сообщениями с клиентами — отдельные возможности. Проверьте документированный охват сервиса. В пользовательской интеграции приложение может обрабатывать обновления отслеживания и отправлять уведомления через отдельный сервис сообщений.
Следует ли уведомлять клиентов о каждом сканировании отслеживания?
Обычно нет. Отдавайте приоритет значимым этапам и событиям, требующим действия. Несколько сканов на объектах могут означать обычное перемещение, не меняя того, что клиенту нужно знать. Подробную историю храните на странице отслеживания.
Могу ли я гарантировать уведомления о доставке в реальном времени?
Вы можете установить и контролировать целевое время обработки после получения обновления системой. Но нельзя гарантировать, когда перевозчик запишет или опубликует сканирование. Описывайте сервис с учётом этой зависимости.
Как предотвратить дублирование сообщений о доставке?
Используйте постоянное удаление дубликатов событий, отдельную идентичность уведомления для каждого бизнес-этапа и транзакционное создание заданий. Если сервис сообщений поддерживает идемпотентность, используйте её как дополнительную защиту. Одна лишь проверка дубликатов в памяти не переживёт перезапуски или работу нескольких worker.
Что должно произойти, если перевозчик исправит статус «доставлено»?
Сохраните оба события и выполните сверку состояния отправления. Если исправление существенно влияет на клиента, отправьте понятное исправление или передайте ситуацию в поддержку согласно вашей политике. Не делайте статус «доставлено» навсегда необратимым только ради упрощения кода.
Источники
Следующие официальные ресурсы являются справочными материалами для реализации интеграции с 17TRACK, рассмотренной выше. Внутренняя схема, правила уведомлений и процесс обработки в этом руководстве — архитектурные рекомендации, а не цитаты из контрактов API.
- API отслеживания 17TRACK — официальная отправная точка для оценки интеграции API.
- Документация API 17TRACK — справочник по форматам запросов поставщика, аутентификации, операциям отслеживания и требованиям интеграции.


