Излог на сопствен код (headless)

Вообичаениот пат е нашиот излог или виџетите на вашиот сајт. Но ако сајтот го пишува вашиот развивач или агенција и верстката треба да биде целосно ваша, работи третата опција: вие од нас ги земате податоците и приемот на нарачки, а целиот фронтенд го правите сами, на кој било стек.

Читањето податоци не бара клучеви и авторизација: сѐ што е јавно на излогот, е јавно и во JSON.

Каде се поставува: Маркетинг → „Мојот сајт“ → картичката „Излог на сопствен код“. Таму е и адресата на манифестот на вашата локација, врските до техничката документација и JSON-шемите и поставувањето на вебхукови. Ништо не треба да се вклучува: податоците се објавуваат секогаш.

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

Единствената адреса што развивачот треба да ја знае:

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

Во манифестот е сѐ останато:

Блок	Што содржи
`location`	Идентификатор, слаг, вертикала (ресторан, продавница, хотел, салон)
`languages`	Јазик по default и список на вклучени јазици
`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) има во договорот.

Може ли да се комбинира со сопствена витрина? Да. Нашата витрина, виџетите и вашиот сопствен сајт работат со истите податоци и со истата кошничка за нарачки.