Разбираю архитектуру интеграции магазина на WordPress + WooCommerce с YCP — протоколом Яндекса для покупок через Алису AI, Поиск и Ритм
В конце мая 2026 Яндекс открыл Yandex Commerce Protocol для всех — теперь любой онлайн-магазин может подключить продажи через Алису AI, Поиск и рекомендательную ленту Ритм. Из коробки готовые решения есть для Яндекс KIT, Яндекс Маркета и 1С-Битрикс. Для всего остального — API.
У меня магазин на WooCommerce, и решения «нажать кнопку и заработало» для меня не было. Я мог либо ждать, пока Яндекс или кто-то ещё сделает интеграцию для WordPress (с непредсказуемым ETA), либо разобраться с API и написать плагин сам. Выбрал второе. На разработку ушло около двух недель работы по вечерам, плюс ещё неделя на отладку с тестовым кабинетом Яндекса. По итогу получился open-source плагин на GPL-2.0, в котором закрыты все 10 эндпоинтов спецификации YCP v1: github.com/perfinn/YCP-Yandex-Commerce-Woocommerce.
В статье разберу не «как поставить» (это в README), а как технически устроена интеграция: какие эндпоинты протокол требует реализовать, как маппить заказы из Яндекса в WC, где можно наступить на грабли (статусы заказов, письма, HPOS-совместимость), и почему я добавил идемпотентность по session_id с самого начала. Может, кому-то поможет либо взять плагин под свой проект, либо написать аналог под другую платформу.
Что вообще делает YCP с точки зрения архитектуры
Чтобы было понятно, что мы реализуем — короткий обзор протокола.
YCP — это HTTPS REST API от Яндекса к вашему сайту. Не наоборот. То есть когда покупатель в Алисе или Поиске нажимает «Купить в 1 клик», запросы летят от инфраструктуры Яндекса к серверу магазина. Магазин должен предоставить набор эндпоинтов, через которые Яндекс получает информацию о товарах, рассчитывает доставку, оформляет заказ и потом синхронизирует его статус.
В отличие от классических маркетплейс-интеграций (где магазин выгружает фид и забывает), тут двусторонний live-протокол. Каждый раз, когда пользователь видит товар в результатах Алисы — Яндекс делает запрос к магазину «уточни актуальную цену и наличие». Каждый раз, когда что-то меняется со статусом заказа — синхронизация через API.
Это значит, что плагин должен держать REST API всегда доступным, быстрым и идемпотентным. И тут начинается интересное.
Структура плагина
Прежде чем разбирать конкретные эндпоинты, покажу общий скелет. WordPress-плагин строится по стандартной схеме: главный PHP-файл с заголовком плагина, классы под отдельные ответственности, action/filter хуки для интеграции с WP и WooCommerce.
yandex-ycp-woo/├── yandex-ycp-woo.php # Главный файл, хуки активации, регистрация├── includes/│ ├── class-ycp-rest.php # Регистрация REST API эндпоинтов│ ├── class-ycp-auth.php # Bearer-токен авторизация│ ├── class-ycp-checkout.php # Логика создания заказа из Яндекса│ ├── class-ycp-delivery.php # Варианты доставки (СДЭК, ПВЗ)│ ├── class-ycp-orders.php # Маппинг товаров, обновление статусов│ ├── class-ycp-logger.php # Лог в WP option (для отладки)│ └── class-ycp-admin.php # Страница настроек в админке├── assets/│ └── admin.css└── readme.txt # Стандарт WordPress.org
Регистрация эндпоинтов идёт через стандартный для WP механизм register_rest_route в action rest_api_init:
add_action( 'rest_api_init', function() { $namespace = 'ycp/v1'; // GET /ycp/v1/warehouses register_rest_route( $namespace, '/warehouses', [ 'methods' => 'GET', 'callback' => [ 'YCP_Rest', 'get_warehouses' ], 'permission_callback' => [ 'YCP_Auth', 'check_bearer' ], ]); // POST /ycp/v1/checkout register_rest_route( $namespace, '/checkout', [ 'methods' => 'POST', 'callback' => [ 'YCP_Rest', 'create_checkout' ], 'permission_callback' => [ 'YCP_Auth', 'check_bearer' ], ]); // ... ещё 8 эндпоинтов});
Здесь важный момент с permission_callback. Это не опциональная штука, это обязательный механизм безопасности WP REST API. Если поставить туда __return_true, WordPress будет ругаться, и эндпоинт станет публично доступным без авторизации. Что для платёжного API недопустимо.
Авторизация в YCP идёт по Bearer-токену, который Яндекс генерирует в кабинете и присылает в каждом запросе:
class YCP_Auth { public static function check_bearer( WP_REST_Request $request ) { $stored_token = get_option( 'ycpy_bearer_token' ); if ( empty( $stored_token ) ) { return new WP_Error( 'no_token_configured', 'Token not set', [ 'status' => 503 ] ); } // Основной заголовок — Authorization: Bearer ... $auth = $request->get_header( 'authorization' ); if ( $auth && stripos( $auth, 'Bearer ' ) === 0 ) { $token = trim( substr( $auth, 7 ) ); if ( hash_equals( $stored_token, $token ) ) { return true; } } // Fallback на X-API-Key — иногда так удобнее тестировать через curl $api_key = $request->get_header( 'x_api_key' ); if ( $api_key && hash_equals( $stored_token, $api_key ) ) { return true; } return new WP_Error( 'unauthorized', 'Invalid token', [ 'status' => 401 ] ); }}
Использование hash_equals вместо обычного === — это защита от timing attacks. Для платёжного API такая мелочь критична, и WordPress-разработчики часто её забывают.
Эндпоинт 1: warehouses
Самый простой. Яндекс при подключении магазина первым делом запрашивает список ваших складов. Из админки настройки нашего плагина я даю заполнить только один основной склад — для большинства мелких магазинов на WooCommerce этого достаточно.
public static function get_warehouses( WP_REST_Request $request ) { $warehouse = [ 'id' => 'main', 'name' => get_option( 'ycpy_warehouse_name', 'Основной склад' ), 'address' => [ 'country' => 'RU', 'city' => get_option( 'ycpy_warehouse_city' ), 'street' => get_option( 'ycpy_warehouse_street' ), 'building' => get_option( 'ycpy_warehouse_building' ), ], 'phone' => get_option( 'ycpy_warehouse_phone' ), ]; return rest_ensure_response([ 'warehouses' => [ $warehouse ], ]);}
Тут ничего сложного, но обращу внимание на rest_ensure_response() — это WP-обёртка, которая гарантирует правильный формат ответа с заголовками. Без неё может улететь голый array, и Яндекс не распарсит.
Эндпоинт 2: basket/check — проверка корзины
Вот это уже интересно. Когда пользователь смотрит товар в Алисе и нажимает «Купить», Яндекс перед показом универсального чекаута спрашивает магазин: «у нас в корзине вот эти товары — они актуальные, цены те же, наличие есть, габариты для расчёта доставки какие?».
public static function basket_check( WP_REST_Request $request ) { $body = $request->get_json_params(); $items = $body['items'] ?? []; $checked_items = []; $unavailable = []; foreach ( $items as $item ) { $product = self::find_product( $item['id'] ); if ( ! $product || ! $product->is_in_stock() ) { $unavailable[] = [ 'id' => $item['id'], 'reason' => 'out_of_stock' ]; continue; } $checked_items[] = [ 'id' => $item['id'], 'price' => self::format_money( $product->get_price() ), 'currency' => 'RUB', 'quantity' => $item['quantity'], 'available' => $product->get_stock_quantity() ?? 999, 'dimensions' => self::get_product_dimensions( $product ), ]; } return rest_ensure_response([ 'items' => $checked_items, 'unavailable' => $unavailable, ]);}
Маппинг товаров — отдельная история. Яндекс присылает id товара, и непонятно, что это: SKU в WC или числовой post_id WooCommerce-продукта. Я сделал двойной поиск:
private static function find_product( $id ) { // 1. Пробуем как SKU (артикул) $product_id = wc_get_product_id_by_sku( $id ); if ( $product_id ) { return wc_get_product( $product_id ); } // 2. Если ID числовой — пробуем как post_id if ( is_numeric( $id ) ) { $product = wc_get_product( (int) $id ); if ( $product && $product->exists() ) { return $product; } } return null;}
Это гибкое поведение — мерчант может в фиде Яндекса указывать что удобнее: SKU или числовой ID WC-товара. Главное, чтобы при маппинге в обратную сторону всё нашлось.
С габаритами тоже есть нюанс. WooCommerce из коробки даёт поля weight, length, width, height — но многие магазины их не заполняют. А без габаритов Яндекс не сможет посчитать стоимость доставки СДЭК, и заказ не оформится. Я добавил дефолтные значения для товаров без указанных размеров:
private static function get_product_dimensions( $product ) { $weight = $product->get_weight() ?: get_option( 'ycpy_default_weight', 0.5 ); $length = $product->get_length() ?: get_option( 'ycpy_default_length', 15 ); $width = $product->get_width() ?: get_option( 'ycpy_default_width', 10 ); $height = $product->get_height() ?: get_option( 'ycpy_default_height', 5 ); return [ 'weight' => (float) $weight, 'length' => (float) $length, 'width' => (float) $width, 'height' => (float) $height, ];}
Дефолты задаются в админке плагина — это компромисс между «магазин обязан заполнить размеры всех товаров» и «давайте просто что-то отдадим, чтобы заказ хотя бы прошёл». Я выбираю «лучше отдать дефолт и предупредить мерчанта», чем «отказать в покупке».
Эндпоинт 3: checkout — создание заказа
Самый ответственный эндпоинт. Это когда Яндекс реально хочет создать у нас в WC новый заказ. И тут самая большая ловушка, на которую я наступил во время разработки.
Ловушка 1: письма «Новый заказ на 0 ₽».
Если просто создавать заказ в WC через wc_create_order() со статусом pending, WooCommerce немедленно срабатывает на хуки order-created и шлёт письмо администратору магазина «Новый заказ #1234 на сумму 0 ₽». Почему 0? Потому что Яндекс ещё не прислал финальную сумму — она будет известна позже, после расчёта доставки и применения промокодов.
Решение — создавать заказ в нестандартном статусе checkout-draft, который WC использует для «висящих» корзин:
public static function create_checkout( WP_REST_Request $request ) { $body = $request->get_json_params(); $session_id = $body['session_id'] ?? ''; // Идемпотентность: проверяем, не создан ли уже заказ по этой сессии $existing = self::find_order_by_session( $session_id ); if ( $existing ) { return rest_ensure_response([ 'order_id' => $existing->get_id(), 'status' => 'exists', ]); } // Создаём заказ в специальном статусе draft $order = wc_create_order( [ 'status' => 'checkout-draft', ] ); // Сохраняем session_id для последующего поиска $order->update_meta_data( '_ycp_session_id', $session_id ); $order->update_meta_data( '_ycp_origin', 'yandex' ); // Добавляем товары из запроса foreach ( $body['items'] as $item_data ) { $product = self::find_product( $item_data['id'] ); if ( $product ) { $order->add_product( $product, $item_data['quantity'] ); } } // Адрес доставки if ( ! empty( $body['delivery_address'] ) ) { $order->set_address( self::map_address( $body['delivery_address'] ), 'shipping' ); } $order->calculate_totals(); $order->save(); return rest_ensure_response([ 'order_id' => $order->get_id(), 'status' => 'created', 'session_id' => $session_id, ]);}
Статус checkout-draft WC не показывает на странице «Заказы» по умолчанию (это технический статус), не шлёт писем, и не считает заказ «реально оформленным». Только когда придёт запрос на placed, мы переведём заказ в pending, и вот тогда WC отработает все стандартные хуки.
Ловушка 2: идемпотентность.
API Яндекса гарантирует at-least-once delivery — то есть запрос может прийти дважды, например если у магазина был timeout на ответ. Если просто создавать заказ каждый раз, получим два дубля одного и того же заказа.
Решение — поиск по session_id перед созданием:
private static function find_order_by_session( $session_id ) { if ( empty( $session_id ) ) { return null; } // HPOS-совместимый запрос $orders = wc_get_orders([ 'limit' => 1, 'meta_key' => '_ycp_session_id', 'meta_value' => $session_id, 'status' => [ 'checkout-draft', 'pending', 'processing', 'on-hold' ], ]); return ! empty( $orders ) ? $orders[0] : null;}
Тут второй важный момент — HPOS (High-Performance Order Storage). WooCommerce с версии 8.0 поддерживает новое хранилище заказов на основе кастомных таблиц вместо wp_posts. На новых сайтах оно включено по умолчанию. Если писать запросы через прямой SQL к wp_postmeta (как многие старые плагины), на HPOS-сайтах ничего не найдётся.
Поэтому я использую везде высокоуровневые wc_get_orders(), $order->update_meta_data(), $order->get_meta() — они работают в обоих хранилищах. Это требует чуть больше дисциплины, но плагин становится совместимым «навсегда».
Эндпоинт 4: checkout/placed — заказ подтверждён
Когда пользователь нажал «Оплатить» в виджете Яндекса, прилетает placed. Финальная сумма, выбранный способ доставки, статус оплаты — всё уже сформировано на стороне Яндекса. Наша задача — перевести WC-заказ из checkout-draft в нормальный статус.
public static function checkout_placed( WP_REST_Request $request ) { $body = $request->get_json_params(); $session_id = $body['session_id'] ?? ''; $order = self::find_order_by_session( $session_id ); if ( ! $order ) { return new WP_Error( 'order_not_found', 'No draft order for session', [ 'status' => 404 ] ); } // Записываем финальные данные $order->update_meta_data( '_ycp_yandex_order_id', $body['yandex_order_id'] ); $order->update_meta_data( '_ycp_payment_method', $body['payment_method'] ); $order->set_total( $body['total_amount'] ); // Способ оплаты определяет статус if ( $body['payment_status'] === 'paid' ) { // Оплата прошла на стороне Яндекса (Яндекс Пэй, Сплит) → processing $order->update_status( 'processing', 'Оплачено через Яндекс Чекаут' ); } else { // Наложенный платёж → pending (магазин обработает сам) $order->update_status( 'pending', 'Заказ оформлен, оплата при получении' ); } return rest_ensure_response([ 'status' => 'ok', 'order_id' => $order->get_id(), ]);}
Когда статус заказа переходит из checkout-draft в pending или processing, WooCommerce автоматически отправляет администратору письмо с правильной финальной суммой. Это и есть тот «флоу checkout-draft → pending», который решает проблему пустых писем.
Эндпоинты 5–10: остальная синхронизация
Чтобы не превращать статью в reference manual, остальные эндпоинты опишу кратко:
POST /checkout/cancel — пользователь закрыл виджет, не оформив. Удаляем draft-заказ или помечаем его как cancelled.
POST /checkout/delivery/options — возвращаем варианты доставки. Тут я подтягиваю активные методы из WC Shipping, плюс отдельно поддерживаю «самовывоз из ПВЗ».
GET /checkout/delivery/pickup_points — для магазинов с собственными ПВЗ. Я добавил в админке простой UI «список ПВЗ магазина» с CRUD-операциями.
GET /order — Яндекс синхронизирует статусы. Возвращаем историю изменений статуса заказа.
POST /order/cancel — отмена оформленного заказа. Переводим WC-заказ в cancelled, восстанавливаем сток.
POST /order/delivered — заказ доставлен. Переводим заказ в completed.
Все эти эндпоинты идемпотентны по тому же session_id или yandex_order_id, чтобы повторные запросы не делали ничего вредного.
Логирование: главный инструмент отладки
Когда работаешь с внешним API, без логов жить нельзя. На моей стороне нет способа повторить запрос Яндекса вручную — я могу только реагировать на то, что прилетело. Поэтому логирование критично.
Я не стал тащить файловую запись или БД — для маленьких магазинов это лишний overhead. Сделал лог в WP option с ротацией по последним 100 записям:
class YCP_Logger { const OPTION_NAME = 'ycpy_log'; const MAX_ENTRIES = 100; public static function log( $type, $endpoint, $request_body, $response, $error = null ) { $log = get_option( self::OPTION_NAME, [] ); array_unshift( $log, [ 'timestamp' => current_time( 'mysql' ), 'type' => $type, // REQUEST, RESPONSE, EXCEPTION 'endpoint' => $endpoint, 'request_body' => is_string( $request_body ) ? $request_body : wp_json_encode( $request_body ), 'response' => is_string( $response ) ? $response : wp_json_encode( $response ), 'error' => $error, ]); // Оставляем только последние N записей if ( count( $log ) > self::MAX_ENTRIES ) { $log = array_slice( $log, 0, self::MAX_ENTRIES ); } update_option( self::OPTION_NAME, $log, false ); // autoload = false }}
Вызывается перед каждым ответом эндпоинта, плюс из глобального try-catch на случай исключений. В админке плагина — таблица с фильтрацией по типу. Когда мерчант приходит с проблемой «заказ не оформляется», первое, что я прошу — открыть лог и найти запись с типом EXCEPTION. Чаще всего там сразу видно, что прислал Яндекс и где упало.
autoload = false — важный нюанс. По умолчанию WP-опции загружаются вместе с каждым запросом к сайту. Если лог огромный, это замедлит каждую страницу. Отключаем autoload — опция читается только когда явно запрошена.
Чему я научился за это время
Несколько уроков из разработки.
WC HPOS — это будущее, и игнорировать его нельзя. Если бы я писал плагин «по-старому» через $wpdb->postmeta, он бы не работал у половины современных магазинов. Все обращения к данным заказов — только через WC API.
Идемпотентность с первого дня. Я мог бы добавить проверку на дубли «когда-нибудь потом». В реальности это бы означало пачку дублированных заказов на боевых магазинах в первый же день. Делай идемпотентность с первого коммита.
Локальные дефолты для нестабильных данных. Магазины — это всегда грязные данные. Половина товаров без габаритов, четверть — без артикулов, в каждом десятом — пустые описания. Плагин, который требует «все товары должны быть идеально заполнены», не взлетит. Плагин с разумными дефолтами и понятными warning-ами — взлетит.
Лог в админке важнее любой документации. Когда у мерчанта что-то не работает, никто не будет лезть в FTP смотреть /wp-content/uploads/ycp-logs/. Кнопка «Лог последних запросов» прямо в админке решает 80% запросов в поддержку.
Статус checkout-draft — недооценённая фишка WooCommerce. До этой работы я о нём не знал. Это очень удобно для любых сценариев «отложенного оформления заказа» — корзины с saved later, multi-step checkout, и теперь — внешние чекауты вроде Яндекса.
Что дальше
Плагин сейчас закрывает все 10 эндпоинтов YCP v1 и работает на нескольких боевых магазинах, включая мой. Из планов:
-
Поддержка multi-warehouse (Яндекс это поддерживает, но я пока вынес наружу только один склад)
-
Интеграция с WC Multilingual для магазинов на нескольких языках
-
Bulk-операции по массовому экспорту товаров в Яндекс Товары (сейчас это делается через стандартный YML-фид)
-
Поддержка партиал-оплат и подписочных моделей, если Яндекс их откроет в YCP v2 Если у вас тоже WooCommerce, и вы хотите подключить продажи через Алису AI — попробуйте плагин. GPL-2.0, бесплатно, поддержка по issue в репозитории: github.com/perfinn/YCP-Yandex-Commerce-Woocommerce.
PR и баг-репорты приветствую. Особенно полезно было бы получить фидбек от магазинов с большим ассортиментом (10k+ товаров) — на моих тестовых стендах таких объёмов не было, и где-то могут вылезти узкие места по производительности.
Полезные ссылки:
-
Репозиторий плагина: github.com/perfinn/YCP-Yandex-Commerce-Woocommerce
-
Документация YCP от Яндекса: merchants.yandex.ru/ycp
-
WooCommerce HPOS docs: woocommerce.com/document/high-performance-order-storage
ссылка на оригинал статьи https://habr.com/ru/articles/1037654/