Витрина на своём коде (headless)

Обычный путь — наша витрина или виджеты на вашем сайте. Но если сайт пишет ваш разработчик или агентство и вёрстка должна быть полностью своей, работает третий вариант: вы берёте у нас данные и приём заказов, а весь фронтенд делаете сами, на любом стеке.

Чтение данных не требует ключей и авторизации: всё, что публично на витрине, публично и в JSON.

Где настраивается: Маркетинг → «Мой сайт» → карточка «Витрина на своём коде». Там же — адрес манифеста вашей локации, ссылки на техническую документацию и JSON-схемы и настройка вебхуков. Включать ничего не нужно: данные публикуются всегда.

Манифест storefront.json#

Единственный адрес, который нужно знать разработчику:

https://cdn.cenaly.ru/{ДОМЕН}/storefront.json

В манифесте — всё остальное:

Контракт версионируется (contractVersion), а рядом лежат JSON-схемы — по ним удобно валидировать данные и генерировать типы. Неизвестные поля нужно игнорировать: контракт расширяется без слома совместимости.

Данные и изображения#

Всё, что показывает витрина, доступно файлами: меню и каталог по языкам, профиль локации (название, адрес, часы работы, контакты, настройки), страницы и статьи, коллекции, отзывы.

Для больших каталогов манифест переключается в режим api: в файле меню лежит облегчённая выборка, полные карточки берутся пофайлово или через каталожный API с фильтрами и подкатегориями.

Изображения — с нашего CDN, в нескольких размерах по шаблону из манифеста; при обновлении фото путь версионируется, поэтому кэш можно держать «навсегда».

Писать все эти запросы руками не обязательно: есть npm-пакет @cenaly/storefront — типизированный клиент контракта (манифест, профиль, меню обоих режимов каталога, оформление заказа), построитель URL изображений и React-хуки. У пакета есть отдельная точка входа для статических сборок (@cenaly/storefront/static: карта адресов сайта, sitemap.xml, robots.txt, ссылки на изображения) и консольная команда cenaly-storefront — снимок всех данных локации в папку, список адресов и режим watch, который следит за манифестом и запускает вашу сборку, как только меняется publishId. Он же лежит в основе стартового проекта на Next.js, который можно склонировать и просто перекрасить.

Заказы и гостевой API#

Приём заказов, статус заказа, поиск и брони — через гостевой API: без авторизации, адрес берётся из манифеста, спецификация — OpenAPI 3.1. Отдельно есть коммерческий контур: купоны, расчёт доставки, формы, подписки. Подробнее — Guest API для AI-агентов, тот же интерфейс.

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

Вебхуки об изменениях#

Чтобы не опрашивать CDN, подпишитесь на события:

• menu.updated — меню или каталог перегенерированы;
• profile.updated — изменился профиль локации;
• pages.updated — изменились страницы и статьи.

В теле события приходит publishId — по нему удобно пересобирать статические страницы или сбрасывать ISR-кэш. Если вы задали секрет, запрос подписывается HMAC-SHA256 и приходит с заголовком X-Meni-Signature — проверьте подпись, прежде чем что-то пересобирать; для deploy-хука Vercel/Netlify секрет можно не заводить. До пяти адресов на локацию, а после десяти неудач подряд подписка отключается сама (в кабинете видно последнюю доставку и счётчик ошибок; повторное сохранение настроек включает её обратно).

Какой адрес примет сервер. Только https://, без логина и пароля в самом URL, и хост обязан быть публичным: локальные, внутренние и служебные адреса (localhost, 10.0.0.0/8, 192.168.0.0/16, 172.16.0.0/12, 100.64.0.0/10, 169.254.169.254) отклоняются при сохранении. Для отладки на своей машине поднимите туннель с публичным https-адресом.

Когда бывает повтор. Повторяются таймауты и ответы 5xx, 408, 429 — то есть то, что похоже на временный сбой. Любой другой ответ 4xx считается постоянной ошибкой: повтора не будет, попытка сразу идёт в счётчик неудач.

Вебхуки настраиваются в карточке «Витрина на своём коде» и доступны на платных тарифах; чтение данных доступно всегда.

С чего начать#

1. Откройте Маркетинг → «Мой сайт» → «Витрина на своём коде» и скопируйте адрес манифеста.
2. Загрузите манифест и от него — данные меню и профиля (или поставьте пакет @cenaly/storefront и передайте ему слаг локации). Никаких ключей на этом шаге не нужно.
3. Соберите страницы своим фреймворком; для заказов используйте гостевой API.
4. Добавьте вебхук, чтобы пересобирать сайт по факту изменений, — либо, если публичного адреса для приёма событий нет, запустите cenaly-storefront watch: он сам следит за publishId в манифесте и запускает вашу сборку.

Полное техническое описание — по ссылке «Документация разработчика» в той же карточке; рядом ссылки на отдельное руководство по статическому сайту и на JSON-схемы. Есть готовый стартовый проект на Next.js, а вся документация дублируется в виде llms.txt для ИИ-ассистентов разработчика — включая персональный llms.txt вашей локации на CDN.

Связанные разделы#

• Мой сайт — виджеты, если переписывать сайт целиком не нужно
• Guest API для AI-агентов — тот же гостевой API
• MCP API — доступ ИИ-агентов к кабинету
• Интернет-магазин — что именно приезжает в данных каталога

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

Нужно ли платить за чтение данных? Нет. Публичные JSON доступны на любом тарифе — это те же файлы, которыми пользуется наша витрина. Платными являются вебхуки.

Что с SEO? Он полностью на вашей стороне: вы собираете страницы сами и сами управляете разметкой. Данные для микроразметки (JSON-LD) в контракте есть.

Можно ли совмещать со своей витриной? Да. Наша витрина, виджеты и ваш собственный сайт работают с одними и теми же данными и одной корзиной заказов.