Жизненный цикл заказа (после покупки)

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

конечная точка веб-перехватчика

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

POST https://shoppingdataintegration.googleapis.com/v1/webhooks/partners/PARTNER_ID/events/order?key=API_KEY

В процессе регистрации Google предоставляет вам конкретный PARTNER_ID и API_KEY . Предоставьте API-ключ одним из двух способов:

• В качестве параметра запроса URL: ?key=API_KEY
• Используется HTTP-заголовок: X-Goog-Api-Key: API_KEY

Обязательные события обновления заказов

Необходимо сообщать о следующих изменениях статуса заказа:

• Заказ создан: Запущен сразу после подтверждения заказа ( status: processing ).
• Заказ отправлен: Отправляется, когда товары из заказа покидают склад. Требуются tracking_number и tracking_url .
• Заказ доставлен: срабатывает, когда товары доставлены получателю.

Рекомендуемые события обновления заказа

Для обеспечения наилучшего пользовательского опыта мы также рекомендуем отправлять обновления по следующим событиям:

• События корректировки:

  • dispute : ситуация, когда клиент оспаривает платеж.

• Мероприятия по выполнению заказов:

  • canceled : Событие, когда выполнение заказа отменяется (отправляется в массиве fulfillment.events ).

Логика заказа и сопоставление статусов

Для корректного отображения страницы «Мои заказы» Google использует определенную логику сопоставления данных в вашем полезном трафике.

Требования к отдельным позициям

• Позиции в списке товаров не должны быть пустыми и должны содержать информацию о item .

• Согласно спецификации UCP , статус позиции в заказе должен точно отражать total и фактическое количество fulfilled товаров (где fulfilled означает "доставленные" товары):

  • processing : когда fulfilled равно 0, а total > 0 (например, total: 2 , fulfilled: 0 ).
  • partial : когда fulfilled больше 0, но меньше значения total (например, total: 2 , fulfilled: 1 ).
  • fulfilled : когда fulfilled равно total и total > 0 (например, total: 2 , fulfilled: 2 ).
  • removed : когда total равно 0 (например, total: 0 , fulfilled: 0 ).

События корректировки

Любые события, связанные с перемещением денежных средств, должны быть включены в массив adjustments .

• cancellation : Отмена всего заказа или отдельных товаров в заказе до его выполнения.
• return : ситуация, когда товары из заказа возвращаются покупателем после его выполнения.
• refund : Возврат денежных средств за заказ или отдельные товары.

Заказы, состоящие из нескольких товаров

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

группировка многокомпонентных пакетов

Товары на странице «Мои заказы» сгруппированы по посылкам (имеющим одинаковый tracking_url ). Если посылка возвращена частично, возвращенные товары вынесены в отдельный раздел на странице «Мои заказы».

Статус посылки

Для посылки отображаются следующие статусы: Заказано, Отправлено, Доставлено, Возвращено, Возмещено, Отменено. Статусы посылок определяются атрибутом type объектов событий fulfillment и adjustments .

Как определяется статус посылки

Если событие корректировки имеет status: completed , то в зависимости от типа события корректировки на упаковке отобразится соответствующий статус: «Возвращено», «Возмещено» или «Отменено».

Если корректировка не завершена, то статус будет определяться типом события выполнения:

Правила технической валидации

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

Причины отклонения заказа

Google проверяет входящие данные веб-хуков и отклоняет обновления, если они соответствуют любому из следующих условий:

• В теле запроса отсутствует сущность заказа.
• В полезной нагрузке отсутствует checkout_id или id ( идентификатор подтверждения заказа ).
• В полезной нагрузке содержится метка времени, более старая, чем последнее зарегистрированное обновление.
• Событие корректировки отправляется с типом, отличным от refund , return , credit , price_adjustment , dispute или cancellation .
• Любое описание доставки превышает 200 символов.

Цены указаны с учетом налогов.

Если вы работаете на рынках, где налог включен в промежуточную сумму, то в массиве totals по всем событиям веб-хука для каждого заказа должно отображаться следующее:

• Итого: Включите все применимые налоги в сумму subtotal и установите display_text в значение "Subtotal (including taxes)" .
• Выполнение заказа: Добавьте display_text поле для указания стоимости доставки или выполнения заказа (например, "Shipping" ).
• Налог: Исключите отдельные записи "tax" из массива totals .

Следующие шаги

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

• Реализация жизненного цикла заказа для версии 2026-04-08
• Реализация жизненного цикла заказа для версии 2026-01-23