Витрина на собствен код (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) има в контракта.

Може ли да се съчетава със собствена витрина? Да. Нашата витрина, уиджетите и вашият собствен сайт работят с едни и същи данни и една кошница за поръчки.