Vitrină pe cod propriu (headless)

Calea obișnuită este vitrina noastră sau widgeturile pe site-ul dumneavoastră. Dar dacă site-ul este scris de dezvoltatorul sau agenția dumneavoastră și marcarea trebuie să fie complet proprie, funcționează a treia variantă: luați de la noi datele și preluarea comenzilor, iar întregul frontend îl faceți singur, pe orice stack.

Citirea datelor nu necesită chei și autorizare: tot ce este public pe vitrină este public și în JSON.

Unde se configurează: Marketing → „Site-ul meu” → cardul „Vitrină pe cod propriu”. Acolo se află și adresa manifestului punctului dumneavoastră de lucru, linkuri către documentația tehnică și schemele JSON și configurarea webhook-urilor. Nu trebuie să activați nimic: datele sunt publicate întotdeauna.

Manifestul storefront.json#

Singura adresă pe care trebuie să o știe dezvoltatorul:

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

În manifest se află tot restul:

Bloc	Ce conține
`location`	Identificator, slug, verticală (restaurant, magazin, hotel, salon)
`languages`	Limba implicită și lista limbilor activate
`currency`	Codul și simbolul valutei
`cdnBase` + `data`	Căi către meniu, profil, pagini, colecții, recenzii și recomandări „se cumpără cu aceasta”
`catalog`	Modul catalogului: totul în fișiere sau carduri individuale și API de catalog
`images`	Baza imaginilor, șabloanele căilor (foto articolului și galerii, video, categorii, colecții, copertă și logo, favicon) și dimensiunile disponibile
`api`	Adresele API-ului pentru oaspeți, specificațiile OpenAPI, conturul comercial, endpoint-ul MCP și WebSocket pentru statusurile live ale comenzii
`publishId`, `publishedAt`	Identificatorul publicării: se schimbă la fiecare regenerare a datelor

Contractul este versionat (contractVersion), iar alături se află schemele JSON — după ele este comod să validați datele și să generați tipuri. Câmpurile necunoscute trebuie ignorate: contractul se extinde fără a rupe compatibilitatea.

Date și imagini#

Tot ce afișează vitrina este disponibil ca fișiere: meniu și catalog pe limbi, profilul punctului de lucru (denumire, adresă, ore de funcționare, contacte, setări), pagini și articole, colecții, recenzii.

Pentru cataloage mari, manifestul comută în modul api: în fișierul de meniu se află o selecție simplificată, iar cardurile complete se iau individual sau prin API-ul de catalog cu filtre și subcategorii.

Imaginile sunt de pe CDN-ul nostru, în mai multe dimensiuni după șablonul din manifest; la actualizarea unei fotografii calea este versionată, astfel încât cache-ul poate fi păstrat „pentru totdeauna”.

Nu este obligatoriu să scrieți toate aceste cereri manual: există pachetul npm @cenaly/storefront — un client tipizat al contractului (manifest, profil, meniu în ambele moduri de catalog, plasarea comenzii), constructor de URL-uri pentru imagini și hook-uri React. Pachetul are o intrare separată pentru build-uri statice (@cenaly/storefront/static: harta adreselor site-ului, sitemap.xml, robots.txt, linkuri către imagini) și o comandă de consolă cenaly-storefront — un instantaneu al tuturor datelor punctului de lucru într-un folder, lista adreselor și modul watch, care urmărește manifestul și pornește build-ul dumneavoastră de îndată ce se schimbă publishId. Tot el stă la baza proiectului de start pe Next.js, care poate fi clonat și pur și simplu recolora.

Comenzi și API-ul pentru oaspeți#

Preluarea comenzilor, statusul comenzii, căutarea și rezervările — prin API-ul pentru oaspeți: fără autorizare, adresa se ia din manifest, specificația este OpenAPI 3.1. Separat există conturul comercial: cupoane, calculul livrării, formulare, abonamente. Mai multe — Guest API pentru agenți AI, aceeași interfață.

Comanda creată de site-ul dumneavoastră ajunge în secțiunea comună „Comenzi” și funcționează după regulile obișnuite: statusuri, bucătărie, curieri, chitanțe, notificări.

Webhook-uri despre modificări#

Pentru a nu interoga CDN-ul, abonați-vă la evenimente:

menu.updated — meniul sau catalogul au fost regenerate;
profile.updated — profilul punctului de lucru s-a modificat;
pages.updated — paginile și articolele s-au modificat.

În corpul evenimentului vine publishId — după el este comod să reconstruiți paginile statice sau să resetați cache-ul ISR. Dacă ați setat un secret, cererea este semnată cu HMAC-SHA256 și vine cu header-ul X-Meni-Signature — verificați semnătura înainte de a reconstrui ceva; pentru deploy-hook-ul Vercel/Netlify secretul poate să nu fie creat. Până la cinci adrese per punct de lucru, iar după zece eșecuri consecutive abonamentul se dezactivează singur (în cont se vede ultima livrare și contorul de erori; salvarea din nou a setărilor îl reactivează).

Ce adresă va accepta serverul. Doar https://, fără login și parolă în URL, iar hostul trebuie să fie public: adresele locale, interne și de serviciu (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) sunt respinse la salvare. Pentru depanare pe propria mașină, ridicați un tunel cu o adresă https publică.

Când are loc o repetare. Se repetă timeout-urile și răspunsurile 5xx, 408, 429 — adică ceea ce pare a fi o defecțiune temporară. Orice alt răspuns 4xx este considerat eroare permanentă: nu va exista repetare, încercarea intră imediat în contorul de eșecuri.

Webhook-urile se configurează în cardul „Vitrină pe cod propriu” și sunt disponibile pe planurile plătite; citirea datelor este disponibilă întotdeauna.

De unde să începeți#

Deschideți Marketing → „Site-ul meu” → „Vitrină pe cod propriu” și copiați adresa manifestului.
Încărcați manifestul și, de la el, datele meniului și ale profilului (sau instalați pachetul @cenaly/storefront și transmiteți-i slug-ul punctului de lucru). Nu sunt necesare chei la acest pas.
Construiți paginile cu framework-ul dumneavoastră; pentru comenzi folosiți API-ul pentru oaspeți.
Adăugați un webhook pentru a reconstrui site-ul la fiecare modificare — sau, dacă nu există o adresă publică pentru primirea evenimentelor, rulați cenaly-storefront watch: el urmărește singur publishId din manifest și pornește build-ul dumneavoastră.

Descrierea tehnică completă — la linkul „Documentație pentru dezvoltatori” din același card; alături sunt linkuri către un ghid separat pentru site static și către schemele JSON. Există un proiect de start gata făcut pe Next.js, iar toată documentația este duplicată sub formă de llms.txt pentru asistenții AI ai dezvoltatorului — inclusiv llms.txt personal al punctului dumneavoastră de lucru pe CDN.

Secțiuni conexe#

Site-ul meu — widgeturi, dacă nu este nevoie să rescrieți întregul site
Guest API pentru agenți AI — același API pentru oaspeți
API și MCP ale propriei centrale telefonice — accesul agenților AI și al CRM la telefonie
Magazin online — ce anume ajunge în datele catalogului

Întrebări frecvente#

Trebuie să plătiți pentru citirea datelor? Nu. Fișierele JSON publice sunt disponibile pe orice plan — sunt aceleași fișiere pe care le folosește vitrina noastră. Contra cost sunt webhook-urile.

Ce se întâmplă cu SEO? Este complet de partea dumneavoastră: construiți singuri paginile și gestionați singuri marcajul. Datele pentru microdate (JSON-LD) există în contract.

Se poate combina cu propria vitrină? Da. Vitrina noastră, widgeturile și site-ul dumneavoastră propriu funcționează cu aceleași date și cu aceeași coș de comenzi.