Яндекс: merchants (YCP) Чекаут

Яндекс Merchants (YCP) — плагин для Shop-Script, который подключает ваш магазин к Яндекс Merchants и стандарту Yandex Commerce Protocol (YCP) . Покупатели могут оформить заказ кнопкой «Купить в 1 клик» в сервисах Яндекса (Поиск, Алиса AI, Яндекс Ритм), а вы получаете заказ, оплату и данные клиента прямо в Shop-Script — без ручного переноса из личного кабинета Яндекса.

Плагин поднимает на сайте API магазина для Яндекса (каталог, склады, проверка корзины, варианты доставки и ПВЗ, чекаут, статусы заказа), отдаёт YML/JSON-выгрузку товаров и синхронизирует статусы между YCP и разделом «Заказы» Shop-Script. Настройки можно задать глобально или отдельно для групп доменов (мультивитрина).

Важно про кабинет Яндекса. Чтобы пользоваться интеграцией, сначала зарегистрируйте магазин (store) в checkout.merchants.yandex.ru/stores . Дальнейшая настройка подключения и токенов выполняется в экосистеме merchants.yandex.ru / разделе YCP . Без регистрации кабинета Яндекс не сможет вызывать API вашего магазина.

Что даёт покупателям в сервисах Яндекса :

Кнопка «Купить в 1 клик» на карточке товара в Поиске, в сценариях Алисы AI и в рекомендациях Яндекс Ритма (по правилам и доступности YCP у Яндекса).

Оформление и оплата в интерфейсе Яндекса (в т.ч. Яндекс Пэй / Сплит — если вы включили онлайн-оплату в настройках).

Курьерская доставка и доставка до пункта выдачи (ПВЗ), если магазин отдаёт тарифы по протоколу YCP.

Магазин продаёт напрямую: заказ и контакты приходят к вам, а не «теряются» только в ЛК Яндекса.

Что даёт магазину на стороне Shop-Script :

API по адресу вида https://ваш-домен/merchants/ (в ЛК YCP — без api/v1 ; Яндекс сам дописывает эндпоинты).

Публичный YML-фид каталога с уникальным ключом для контекста (глобально или группа доменов).

JSON-каталог товаров для проверки и отладки выгрузки.

Заказы из YCP в разделе «Заказы» Shop-Script (по вашим правилам: сразу при checkout и/или после оплаты).

Склады из остатков Shop-Script, резерв и возврат остатков при отмене.

Доставка «считает магазин»: курьер и ПВЗ (в т.ч. из СДЭК и других плагинов доставки), наценки, кэш каталога ПВЗ и cron-пересборка.

Двусторонняя логика статусов: события Яндекса меняют статус в магазине; статусы магазина отдаются обратно в YCP.

Лог запросов YCP для диагностики и кнопка «Проверить API».

Отдельный раздел в «Импорт/экспорт» для фида, фото и выбора категорий выгрузки.

Где настраивать :

Плагины → Яндекс: merchants (YCP) (основные настройки по вкладкам) и Импорт/экспорт → Яндекс: merchants (YCP) (ссылки на фид, фото и категории для выгрузки).

Как это работает «простыми словами»

Вы регистрируете магазин в кабинете stores и настраиваете подключение YCP на стороне Яндекса.

В плагине копируете «URL для API» и «Токен доступа», вставляете их в ЛК YCP; «Токен API YCP» из кабинета Яндекса вставляете в настройки плагина.

Яндекс забирает каталог (YML/JSON), спрашивает склады и остатки, запрашивает варианты доставки / ПВЗ, проверяет корзину и создаёт заказ через API магазина.

Плагин создаёт (или обновляет) заказ в Shop-Script, резервирует остатки (если включено) и ставит нужный статус.

Вы обрабатываете заказ как обычный: сборка, отправка, завершение. Яндекс видит актуальный статус через опрос заказа.

Основные сценарии использования

Подключить магазин с нуля :

Зарегистрируйтесь в https://checkout.merchants.yandex.ru/stores .

Откройте материалы и кабинет на https://merchants.yandex.ru/ и раздел https://merchants.yandex.ru/ycp .

В плагине включите «Включить интеграцию YCP».

Скопируйте «URL для API» ( https://домен/merchants/ ) и «Токен доступа» в поля ЛК YCP.

Вставьте «Токен API YCP» из личного кабинета Яндекса в плагин.

Нажмите «Проверить API» — убедитесь, что ответы успешные.

В «Импорт/экспорт» скопируйте ссылку YML-фида и укажите её там, где это требует Яндекс (если нужно отдельно от API).

Сохраните настройки и дождитесь проверки/активации со стороны Яндекса.

Настроить каталог для выгрузки :

Откройте Импорт/экспорт → Яндекс: merchants (YCP) .

Выберите контекст: глобальный или группа доменов.

Режим «все категории» или «определённые категории» (дерево с выбором, каскад на дочерние).

Включите передачу фото, число картинок, тип файла (эскиз/оригинал) и размер эскиза.

В выгрузку попадают только товары в наличии (есть остаток и цена > 0).

Сохраните категории. При необходимости сделайте «Тестовую выгрузку».

Работать с несколькими доменами / витринами :

Создайте «Группы доменов» и объедините витрины с одинаковыми правилами YCP.

Для группы можно задать свои токены, фид, склады, статусы и набор категорий.

Пустые поля в группе обычно наследуют глобальный контекст.

Принимать заказы и обрабатывать их в Shop-Script :

Включите «Создавать заказы в Shop-Script».

При необходимости включите «Создавать неоплаченные заказы на checkout» — заказ появится до оплаты.

После оплаты / подтверждения в YCP статус сменится по таблице на вкладке «Статусы».

Дальше работайте в «Заказы» как с обычными заказами магазина.

Включить курьера и ПВЗ по протоколу магазина :

Режим доставки: «Рассчитывает магазин».

Включите «Доставка по YCP протоколу», курьер и/или пункты выдачи (как в ЛК YCP → логистика).

Выберите способы доставки Shop-Script (например, СДЭК) и включите экспорт ПВЗ из тарифов.

При необходимости задайте наценку на курьера / ПВЗ и пересоберите каталог ПВЗ (кнопка или cron).

Разделы настроек плагина (по вкладкам)

Включить интеграцию YCP — главный выключатель. Если выключено, API отвечает ошибкой недоступности (как «сервис выключен»).

Токен API YCP — токен из личного кабинета Яндекса («Ваш токен API»). Нужен магазину, чтобы обращаться к API Яндекса (например, сверка заказов).

URL для API — адрес вида https://домен/merchants/ (без api/v1 ). Копируется в ЛК YCP.

Токен доступа — секрет, который Яндекс передаёт при вызовах вашего API. Сгенерируйте в плагине и вставьте в ЛК YCP. Можно перевыпустить кнопкой обновления.

Проверить API — быстрая самопроверка связки URL + токены (склады, корзина, каталог, доставка, ПВЗ).

Режим ID товара для YCP : «Артикул (SKU)», «ID товара» или «ID артикула (SKU ID)». Должен совпадать с идентификатором оффера в YML. При нескольких артикулах у одного товара режим «ID товара» даёт основному SKU id товара, остальным — составной id; для полной уникальности удобнее «ID артикула».

Габариты по умолчанию — вес (г), ширина / высота / глубина (мм), если у товара в магазине размеры не заданы.

Фото и категории выгрузки — в Импорт/экспорт → Яндекс: merchants .

Онлайн-оплата (Яндекс Пэй / Сплит) — принимать заказы с онлайн-оплатой; в магазине такие заказы создаются как оплаченные (по статусу «После онлайн-оплаты»).

Оплата при получении — принимать on_delivery ; заказ уходит менеджеру по выбранному статусу COD.

Создавать заказы в Shop-Script — без галочки заказы в магазин не пишутся (только API-ответы Яндексу).

Создавать неоплаченные заказы на checkout — заказ появляется в «Заказы» уже при открытии оплаты, до финального подтверждения.

Резервировать остатки при checkout / Возвращать остатки при отмене .

Подсказка по Callback URL Яндекс Пэй: обычно на integration.yastore.yandex.net ; статус оплаты в магазин приходит от YCP ( POST /checkout/placed ).

Режим доставки : считает магазин (варианты через API) или делегировано Яндексу.

Доставка по YCP протоколу — мастер-переключатель; отдельно курьер и пункты выдачи (должны совпадать с ЛК YCP).

Склады по умолчанию и автоимпорт складов из остатков Shop-Script.

Часовой пояс и интервал дат доставки (start/end) для ответа Kit.

Способы доставки Shop-Script для расчёта тарифов; экспорт ПВЗ из СДЭК и др.

Наценка % отдельно на курьера и на ПВЗ.

Кэш каталога ПВЗ (nationwide): статус, размер, кнопка «Пересобрать сейчас» и пример cron CLI.

YCP → магазин — какой статус Shop-Script ставить при событиях Яндекса:

неоплаченный заказ (checkout);

после онлайн-оплаты;

при оплате при получении;

при отмене;

при доставке / выполнении.

Магазин → YCP

Отдавать статусы Shop-Script в YCP — Яндекс при опросе заказа видит статус по таблице маппинга.

Маппинг статусов — для каждого статуса магазина: new , in_progress , arrived_to_pickup_point , delivered , cancelled .

Логировать запросы YCP — журнал обращений API (файлы по дням).

Максимум записей в логе — сколько последних строк показывать в интерфейсе.

Режим отладки — упрощённая передача токена для тестов (в бою обычно выключают).

Таблица складов с редактированием адреса, телефона и описания.

Кнопки: импорт складов из БД магазина, тестовая выгрузка товаров, сверка заказов YCP → магазин.

Подсказка по cron-сверке заказов (если нужно догонять пропуски автоматически).

Последние запросы: время, endpoint, HTTP-код, длительность.

Очистка лога одной кнопкой.

Импорт/экспорт: каталог и фид

YML-фид — постоянная ссылка с ключом для текущего контекста; копируется в буфер.

JSON-каталог — тот же ассортимент в JSON для проверки.

Категории — все или выбранные; выделение/снятие, развернуть/свернуть дерево.

Фото — включать картинки, лимит на товар, тип файла и размер эскиза.

Лимит тестовой выгрузки — сколько офферов в тесте (0 = все). Публичный YML-фид всегда полный.

Счётчики — сколько товаров и офферов в наличии попадает в выгрузку сейчас.

Тестовая выгрузка — быстро проверить формат без ожидания полного обхода ассортимента.

Что видно в карточке заказа Shop-Script

Если заказ пришёл из YCP, в заказе показывается блок с параметрами интеграции (идентификаторы сессии/источника и связанные данные).

Уведомления Shop-Script (письма/SMS по правилам магазина) для таких заказов работают штатно — настраивайте их в «Настройки → Уведомления».

Рекомендуемый порядок первой настройки

Кабинет: регистрация store → дальше Merchants / YCP .

Плагин → вкладка «Основные»: включить, обменять токены и URL, «Проверить API».

«Товары»: режим ID и габариты по умолчанию.

«Оплата»: способы оплаты и создание заказов.

«Логистика»: режим доставки, YCP-протокол, склады, курьер/ПВЗ.

«Статусы»: таблица соответствий под ваш workflow.

«Импорт/экспорт»: категории, фото и ссылка на YML.

Сделать тестовый заказ в контуре Яндекса и убедиться, что он появился в «Заказы» с нужным статусом.

Частые вопросы

Чем отличается merchants.yandex.ru и /ycp? Общий портал Merchants — входная точка экосистемы; раздел YCP — стандарт и сценарии «Купить в 1 клик» / агентной коммерции. Плагин рассчитан на работу с обоими контурами через API магазина.

Зачем checkout.merchants.yandex.ru/stores? Там регистрируется кабинет/магазин (store), без которого не получить токены и не завершить подключение.

Какой URL указывать в ЛК? https://домен/merchants/ — без api/v1 . Яндекс сам допишет /api/v1/warehouses и остальные пути.

Почему 401 «Не авторизован»? Не передан или не совпал токен доступа. Скопируйте актуальный токен из плагина в ЛК YCP (или проверьте, что тестируете с тем же Bearer).

Почему мало товаров в фиде? Смотрите фильтр категорий, наличие остатков и цену > 0, а также режим ID и дубли артикулов.

Заказ не появился в магазине? Проверьте «Создавать заказы…», «неоплаченные на checkout», логи запросов и сверку заказов на вкладке «Склады».

Статус в Яндексе не меняется? Включите «Отдавать статусы Shop-Script в YCP» и проверьте маппинг на вкладке «Статусы».

ПВЗ «Недоступно» / пустой список? Включите доставку по YCP протоколу и пункты выдачи, экспорт ПВЗ из способов доставки, пересоберите кэш ПВЗ; в ЛК YCP должны быть включены те же переключатели.

Несколько сайтов на одном Shop-Script? Используйте группы доменов и отдельные контексты настроек/фида.

Нужно ли менять тему дизайна? Для приёма заказов через Яндекс — нет. Кнопка «Купить в 1 клик» показывается в интерфейсах Яндекса; сайт продолжает работать как обычно.

Полезные ссылки

https://merchants.yandex.ru/ — портал Merchants

https://merchants.yandex.ru/ycp — Yandex Commerce Protocol

https://checkout.merchants.yandex.ru/stores — регистрация кабинета / магазина

Документация YCP — официальная справка

Нужна помощь с настройкой под ваш сайт? Пишите на почту scc.lac@mail.ru или в Telegram @web_stu .