Вітрина на власному коді (headless)

Звичайний шлях — наша вітрина або віджети на вашому сайті. Але якщо сайт пише ваш розробник або агенція і верстка має бути повністю своєю, працює третій варіант: ви берете в нас дані та приймання замовлень, а весь фронтенд робите самі, на будь-якому стеку.

Читання даних не потребує ключів і авторизації: усе, що публічно на вітрині, публічно і в JSON.

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

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

Єдина адреса, яку потрібно знати розробнику:

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

У маніфесті — усе інше:

Блок	Що всередині
`location`	Ідентифікатор, слаг, вертикаль (ресторан, магазин, готель, салон)
`languages`	Мова за замовчуванням і список увімкнених мов
`currency`	Код і символ валюти
`cdnBase` + `data`	Шляхи до меню, профілю, сторінок, колекцій, відгуків і рекомендацій «з цим купують»
`catalog`	Режим каталогу: усе у файлах або пофайлові картки й каталожний API
`images`	База зображень, шаблони шляхів (фото товару та галереї, відео, категорії, колекції, обкладинка й логотип, favicon) і доступні розміри
`api`	Адреси гостьового API, специфікації OpenAPI, комерційного контуру, MCP-ендпоінта й WebSocket живих статусів замовлення
`publishId`, `publishedAt`	Ідентифікатор публікації: змінюється за кожної перегенерації даних

Контракт версіонується (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 вважається постійною помилкою: повтору не буде, спроба одразу йде до лічильника невдач.

Вебхуки налаштовуються в картці «Вітрина на власному коді» і доступні на платних планах; читання даних доступне завжди.

З чого почати#

Відкрийте Маркетинг → «Мій сайт» → «Вітрина на власному коді» і скопіюйте адресу маніфесту.
Завантажте маніфест і від нього — дані меню та профілю (або поставте пакет @cenaly/storefront і передайте йому слаг точки). Жодних ключів на цьому кроці не потрібно.
Зберіть сторінки своїм фреймворком; для замовлень використовуйте гостьовий API.
Додайте вебхук, щоб перезбирати сайт за фактом змін, — або, якщо публічної адреси для приймання подій немає, запустіть cenaly-storefront watch: він сам стежить за publishId у маніфесті й запускає вашу збірку.

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

Пов'язані розділи#

Мій сайт — віджети, якщо переписувати сайт повністю не потрібно
Guest API для AI-агентів — той самий гостьовий API
API і MCP своєї АТС — доступ ШІ-агентів і CRM до телефонії
Інтернет-магазин — що саме надходить у даних каталогу

Часті запитання#

Чи потрібно платити за читання даних? Ні. Публічні JSON доступні на будь-якому плані — це ті самі файли, якими користується наша вітрина. Платними є вебхуки.

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

Чи можна поєднувати зі своєю вітриною? Так. Наша вітрина, віджети та ваш власний сайт працюють з одними й тими самими даними та одним кошиком замовлень.