Вебхуки API отслеживания UPS: что это такое, как они работают и варианты использования
Вебхуки API отслеживания UPS позволяют приложению получать обновления об отправлении, когда становится доступным событие отслеживания, вместо того чтобы постоянно запрашивать у сервиса отслеживания последний статус. Они полезны для интернет-магазинов, логистических команд, маркетплейсов и разработчиков, создающих рабочие процессы управления заказами. Практическая ценность заключается не только в более быстрой синхронизации статусов: правильно спроектированный поток вебхуков может обновлять страницы, доступные клиентам, запускать обработку исключений и сокращать количество ненужных запросов отслеживания.
Точный метод аутентификации, модель событий, ограничения запросов, поля полезной нагрузки и требования к учетной записи зависят от продукта для разработчиков UPS и среды интеграции. Перед созданием рабочего подключения разработчикам следует проверить эти сведения в актуальной документации UPS.
Что такое вебхук API отслеживания UPS?
API отслеживания предоставляет программный способ запрашивать информацию об отправлении. Вебхук добавляет шаблон исходящих уведомлений: после того как приложение подписывается на соответствующие обновления, сервис отправляет HTTP-запрос на конечную точку, управляемую этим приложением, когда происходит подходящее событие.
Например, система заказов может сохранить номер отслеживания UPS и зарегистрировать конечную точку вебхука. При изменении статуса отправления принимающая система может получить уведомление, содержащее некоторую комбинацию номера отслеживания, статуса, временной метки, местоположения, расчетного срока доставки или сведений об исключении. Затем принимающая система проверяет сообщение, обновляет собственную запись и определяет дальнейшее действие.
Вебхук — это не то же самое, что страница отслеживания. Страница отслеживания предназначена для просмотра человеком. Вебхук предназначен для обработки программным обеспечением. Он также не гарантирует, что каждое сканирование перевозчика будет доставлено ровно один раз и в идеальном порядке. Рабочие системы следует проектировать с учетом дублирующихся сообщений, задержек доставки, повторных попыток и периодической сверки.
Как обычно работает этот процесс
- Разработчик создает или настраивает доступ через соответствующую учетную запись разработчика UPS и получает учетные данные, необходимые API.
- Приложение передает или сохраняет идентификатор отправления, обычно номер отслеживания, вместе с внутренними ссылками на заказ и клиента.
- Разработчик настраивает общедоступную конечную точку HTTPS и выполняет процедуру подписки или регистрации поставщика, если это требуется.
- Сервис отслеживания отправляет HTTP-уведомление, когда становится доступным обновление, на которое оформлена подписка.
- Конечная точка аутентифицирует или проверяет запрос, анализирует полезную нагрузку и проверяет, известно ли системе это отправление.
- Приложение быстро подтверждает получение запроса, а затем обрабатывает бизнес-действие через очередь или фоновый обработчик.
- Система записывает событие, применяет правила идемпотентности и обновляет рабочий процесс заказа, склада, поддержки или уведомления клиента.
Разделение подтверждения и обработки имеет большое значение. Отправитель вебхука может повторить попытку, если конечная точка отвечает медленно или возвращает ошибку. Получатель, выполняющий значительные операции с базой данных, отправку электронной почты или обработку на складе до ответа, может создавать тайм-ауты и повторные доставки.
Уведомления вебхуков и опрос
| Подход | Как это работает | Основной компромисс |
|---|---|---|
| Опрос | Ваше приложение запрашивает последний статус по расписанию. | Этот подход прост для понимания, но повторные запросы могут добавлять задержки и создавать ненужный трафик. |
| Доставка вебхуков | Сервис отслеживания отправляет уведомление, когда доступно обновление. | Это может сократить плановые проверки, но требует защищенного, надежного получателя и процесса восстановления. |
| Гибридная модель | Вебхуки запускают обычную обработку, а опрос или сверка выявляют пропуски. | Она требует большего объема проектирования, но часто устойчивее, чем использование только одного канала доставки. |
Вебхук не устраняет автоматически необходимость в запросах API. Некоторые интеграции используют уведомление как сигнал, а затем вызывают API отслеживания для получения последней авторитетной записи. Это может быть полезно, если полезная нагрузка вебхука представляет собой компактное событие, если приложению нужны сведения об отправлении, не включенные в уведомление, или если бизнесу нужен единый путь нормализации всех обновлений.
Что должна содержать полезная нагрузка вебхука отслеживания?
Полезные нагрузки различаются в зависимости от поставщика и продукта. Не проектируйте базу данных на основе предполагаемых имен полей, пока не будут проверены актуальная документация и ответы тестовой среды. В целом событию отслеживания может потребоваться идентифицировать:
- Отправление или номер отслеживания
- Событие или статус отправления
- Время события и, если указано, местный часовой пояс
- Описание сканирования или операционное сообщение
- Сведения о местоположении, если они доступны
- Расчетный срок доставки или подтверждение доставки, если они указаны
- Индикатор исключения или описание исключения
- Идентификатор события поставщика или другое значение, полезное для удаления дубликатов
Рассматривайте текст статуса как данные поставщика, а не как универсальное бизнес-правило. Метки вроде «в пути», «исключение» или «доставлено» может потребоваться сопоставить с внутренней моделью статусов. Система должна сохранять как исходный статус перевозчика, так и нормализованный статус, чтобы сотрудники поддержки могли исследовать различия, не теряя исходное сообщение.
Практические варианты использования
Обновления о доставке для клиентов
Платформа электронной коммерции может использовать события отслеживания для обновления страницы статуса заказа или отправки уведомления клиенту. Лучший триггер зависит от бизнес-правила. Сканирование при приеме отправления может подтвердить продвижение выполнения заказа, тогда как событие исключения может требовать сообщения службы поддержки, а не стандартного письма о статусе. Не отправляйте уведомление о каждом сканировании, если клиенты явно не запросили такой уровень детализации.
Управление исключениями
Вебхук может направлять потенциальные проблемы с доставкой в очередь на проверку. Примеры включают исключение доставки, проблему, связанную с адресом, или отправление, которое не продвигается ожидаемым образом. Интеграция должна различать информационное сканирование и операционное исключение. Также необходимо определить ответственность: служба поддержки может заниматься коммуникацией, а команда выполнения заказов — исследовать отправление или адрес.
Синхронизация склада и управления заказами
Складская система или система управления заказами может использовать события отслеживания для обновления записи о выполнении заказа без необходимости ручной проверки сайта перевозчика. Это особенно полезно, когда один заказ содержит несколько посылок. Модель данных должна хранить записи отслеживания на уровне посылок, а не связывать один статус со всем заказом, поскольку посылки одного заказа могут перемещаться или прибывать в разное время.
Возвраты и обратная логистика
Процессы возврата могут использовать события отслеживания для определения момента, когда посылка движется обратно к продавцу или достигает пункта возврата. Само по себе событие не должно разрешать возврат средств, если только политика продавца прямо не использует это условие. После сообщения перевозчика о доставке возврат может потребовать проверки, сверки запасов или расследования мошенничества.
Операционная отчетность
Нормализованные события отслеживания могут поддерживать отчеты о продвижении отправлений, количестве исключений и результатах доставки. В отчетах следует четко указывать определения. Например, «доставлено» может означать событие доставки, о котором сообщил перевозчик, тогда как «вовремя» требует определения обещанной даты, крайнего срока, часового пояса и правил учета изменений адреса или задержек по запросу клиента.
Интеграция только с UPS или API нескольких перевозчиков?
Интеграция, предназначенная специально для UPS, может быть подходящей, если бизнес преимущественно отправляет грузы через UPS и хочет работать напрямую с официальной средой разработчика. Это также может быть самым простым выбором, если существующая система заказов уже имеет коннектор UPS, а требуемые рабочие процессы ограничены.
API отслеживания нескольких перевозчиков — это другой архитектурный выбор. Оно может предоставить единую модель интеграции для разных перевозчиков, но приложению все равно придется обрабатывать специфичную для перевозчика семантику статусов, различия в покрытии, требования к аутентификации и качество данных. Сервис нескольких перевозчиков не следует выбирать только потому, что он рекламирует вебхук. Проверьте поддерживаемых перевозчиков, нормализацию событий, документацию, тестовую среду, правила хранения данных и операционную поддержку.
Tracking API 17TRACK актуален для команд, оценивающих подход с несколькими перевозчиками, а его официальную документацию API следует использовать для проверки текущих возможностей, форматов запросов и требований к интеграции. Это не заменяет проверку того, поддерживаются ли перевозчики и события, необходимые для конкретного рабочего процесса UPS, в предполагаемом сценарии использования.
Контрольный список реализации
- Подтвердите область действия продукта. Проверьте, поддерживает ли выбранный сервис UPS необходимые приложению операции отслеживания и модель уведомлений.
- Используйте HTTPS. Получатель должен быть защищен при передаче данных, а учетные данные не должны раскрываться в URL или журналах.
- Проверяйте подлинность. Следуйте задокументированному поставщиком методу проверки подписи, токена или запроса. Если такой метод недоступен, используйте сетевые ограничения и проверку запросов, соответствующие сервису.
- Сделайте обработку идемпотентной. Сохраняйте идентификатор события, если он доступен, или создавайте консервативный ключ дедупликации из стабильных полей события.
- Принимайте события, поступившие не по порядку. Используйте временные метки событий и задокументированную политику переходов состояний, а не предполагайте, что порядок поступления равен порядку сканирования.
- Возвращайте быстрый ответ. Помещайте длительные задачи в очередь и отслеживайте неудачные доставки, повторные попытки и сообщения в очереди недоставленных сообщений.
- Сверяйте пропуски. Планируйте контролируемый процесс проверки отправлений без недавних обновлений, с неудачной доставкой или несогласованным состоянием.
- Защищайте персональные данные. Ограничивайте объем сохраняемых сведений об адресе и получателе, ограничивайте доступ и устанавливайте правила хранения в соответствии с потребностями бизнеса.
- Тестируйте реальные бизнес-сценарии. Включайте доставленные отправления, исключения, отмененные заказы, дублирующиеся события, неизвестные номера отслеживания и задержанные уведомления.
Распространенные ошибки, которых следует избегать
Самая распространенная ошибка проектирования — считать вебхук полным источником истины, не планируя обработку повторных попыток или пропущенных событий. Другая ошибка — напрямую обновлять статус заказа на основе текста в свободной форме без слоя сопоставления. Это может привести к неправильным сообщениям клиентам, если терминология перевозчика изменится или если событие относится только к одной посылке.
Командам также следует избегать публикации конечной точки вебхука без средств защиты от злоупотреблений, записи в журналы полных полезных нагрузок с ненужными персональными данными и отправки уведомлений клиентам до прохождения событием базовой проверки. Наконец, не обещайте даты доставки только потому, что ответ отслеживания содержит расчетный срок. Расчеты могут измениться, поэтому формулировка для клиента должна отражать эту неопределенность.
Как выбрать подход к интеграции
Выбирайте прямую интеграцию с UPS, если круг перевозчиков ограничен, команда готова поддерживать специфичную для перевозчика логику, а необходимые официальные функции доступны. Рассмотрите API отслеживания нескольких перевозчиков, если бизнесу нужен единый внутренний интерфейс для нескольких перевозчиков и объем или сложность операций оправдывают уровень абстракции. В любом случае сравнивайте фактическую документацию и поведение в тестовой среде, а не только названия функций.
Перед запуском в рабочей среде проведите проверку концепции с использованием типичных номеров отслеживания и сценариев сбоев. Убедитесь, как создаются подписки, как меняются учетные данные, как проверяются уведомления, как выглядят дублирующиеся события, как обрабатываются исторические обновления и что происходит, если получатель недоступен. Эти ответы определяют, останется ли интеграция надежной после первоначальной демонстрации.
Часто задаваемые вопросы
Вебхук API отслеживания UPS лучше опроса?
Ни один из подходов не является автоматически лучшим. Вебхуки могут сократить плановые проверки и обеспечить более быструю реакцию, тогда как опрос проще контролировать и он может помочь сверять пропущенные события. Многие рабочие системы используют уведомления вебхуков вместе с ограниченными запросами для сверки.
Нужен ли мне вебхук, если я отслеживаю небольшое количество отправлений?
Не обязательно. Для небольшого процесса с низкой частотой может быть достаточно задокументированного процесса опроса или существующей интеграции платформы. Вебхук становится привлекательнее, когда обновления должны запускать автоматические действия или регулярная ручная проверка создает операционную нагрузку.
Может ли вебхук гарантировать, что каждое сканирование UPS достигнет моей системы?
Не следует исходить из того, что это возможно. Поведение доставки, повторные попытки, порядок событий и сроки хранения зависят от конкретного сервиса. Встройте в интеграцию мониторинг, идемпотентность и сверку, а применимые гарантии уточните в актуальной документации UPS.
Должно ли каждое событие отслеживания запускать письмо клиенту?
Обычно нет. Сопоставляйте события перевозчика с правилами коммуникации с клиентами и оставляйте сообщения для важных этапов или исключений, полезных получателю. Сохраняйте исходное событие во внутренней истории, даже если оно не создает уведомление.
Когда бизнесу следует использовать API отслеживания нескольких перевозчиков?
Его стоит оценить, когда бизнес отправляет грузы через нескольких перевозчиков и хочет иметь общий процесс отслеживания. При принятии решения следует учитывать поддержку перевозчиков, нормализованные данные, поведение вебхуков, документацию, безопасность, тестирование и усилия, необходимые для обслуживания интеграции.
