Интеграция продавца с ACP: сессии оформления заказа, делегированные токены и безопасные повторы

Что это

Сведения актуальны на 25 октября 2026 года. В статье используется датированная редакция спецификации ACP 2026-04-17 и её список изменений. Перед интеграцией заново проверьте согласованную версию API, схемы обработчиков платежей и примечания к выпуску. Не подменяйте их незаметно примерами со старой страницы сайта или из каталога репозитория с ещё не выпущенными материалами.

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

Почему это важно

Согласование заказа и делегирование платёжных реквизитов — отдельные операции. Delegate Payment API токенизирует реквизиты для использования платёжным провайдером продавца в установленных пределах. Ответ содержит идентификатор токена хранилища. Разрешённые условия использования включают максимальную сумму, валюту, идентификатор сессии оформления заказа, идентификатор продавца и срок действия; указанное в документации назначение — one_time.

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

Как применять

• Предоставьте операции с сессией. Реализуйте создание по адресу /checkout_sessions, получение и обновление ресурса сессии, а также операции /complete и /cancel. Возвращайте актуальные итоговые суммы, сведения об исполнении заказа, сообщения и статус. Сохраняйте различие между ready_for_payment, authentication_required, complete_in_progress и completed.
• Согласуйте обработку платежей. Используйте обработчик, объявленный при оформлении заказа, и передавайте платёжные данные для завершения с его handler_id и схемой платёжного инструмента. Одного токена хранилища недостаточно для полноценного запроса на оформление заказа. Прежде чем включать этот способ оплаты, убедитесь, что провайдер умеет обрабатывать токен.
• Настройте аутентификацию интеграции. Документация по безопасности предусматривает HTTPS и аутентификацию с bearer-токеном. Передавайте обязательный заголовок API-Version из выбранного контракта; разрешайте доступ к сессии в рамках аутентифицированного взаимодействия продавца и агента.
• Реализуйте безопасные повторные запросы. В этом выпуске заголовок Idempotency-Key обязателен для POST-запросов. Повторно используйте ключ только для той же операции с тем же телом запроса. При отсутствии ключа возвращается idempotency_key_required; если такой же запрос ещё выполняется — idempotency_in_flight; при изменённом теле с тем же ключом — idempotency_conflict.
• Проверяйте уведомления о заказе. В выпуске определена аутентификация вебхуков через Merchant-Signature по временной метке и исходному телу запроса, с проверкой допустимого временного окна для защиты от повторного воспроизведения. Прежде чем менять локальное состояние исполнения заказа, свяжите обновления, подлинность которых проверена, с сессией оформления и заказом.

Подводные камни

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

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