Vitrinë me kodin tuaj (headless)

Rruga e zakonshme është vitrina jonë ose widget-et në faqen tuaj. Por nëse faqen e shkruan zhvilluesi apo agjencia juaj dhe paraqitja duhet të jetë plotësisht e juaja, ekziston një mundësi e tretë: merrni nga ne të dhënat dhe pranimin e porosive, ndërsa të gjithë ndërfaqen e ndërtoni vetë, me çfarëdo teknologjie.

Leximi i të dhënave nuk kërkon çelësa apo autentikim: gjithçka që është publike në vitrinë është publike edhe në JSON.

Ku konfigurohet: Marketing → «Faqja ime» → karta «Vitrinë me kodin tuaj». Aty gjenden edhe adresa e manifestit të vendndodhjes suaj, lidhjet te dokumentacioni teknik dhe skemat JSON, si dhe konfigurimi i webhook-eve. Nuk duhet të aktivizoni asgjë: të dhënat publikohen gjithmonë.

Manifesti storefront.json#

E vetmja adresë që duhet të dijë zhvilluesi:

https://cdn.menugo.al/{ДОМЕН}/storefront.json

Gjithçka tjetër gjendet në manifest:

Blloku	Përmbajtja
`location`	Identifikuesi, slug-u, sektori (restorant, dyqan, hotel, sallon)
`languages`	Gjuha e parazgjedhur dhe lista e gjuhëve të aktivizuara
`currency`	Kodi dhe simboli i valutës
`cdnBase` + `data`	Shtigjet e menusë, profilit, faqeve, koleksioneve, vlerësimeve dhe rekomandimeve «blihen së bashku»
`catalog`	Mënyra e katalogut: gjithçka në skedarë ose kartela në skedarë të veçantë dhe API katalogu
`images`	Adresa bazë e imazheve, shabllonet e shtigjeve (fotot e artikujve dhe galerive, video, kategori, koleksione, kopertinë dhe logo, favicon) dhe madhësitë e disponueshme
`api`	Adresat e API-së për vizitorët, specifikimit OpenAPI, shërbimeve tregtare, endpoint-it MCP dhe WebSocket-it për statuset e porosive në kohë reale
`publishId`, `publishedAt`	Identifikuesi i publikimit: ndryshon sa herë që të dhënat rigjenerohen

Kontrata ka versione (contractVersion), dhe pranë saj gjenden skemat JSON — të dobishme për të validuar të dhënat dhe për të gjeneruar tipat. Fushat e panjohura duhen shpërfillur: kontrata zgjerohet pa prishur përputhshmërinë.

Të dhënat dhe imazhet#

Gjithçka që shfaq vitrina është e disponueshme në skedarë: menuja dhe katalogu sipas gjuhëve, profili i vendndodhjes (emri, adresa, orari, kontaktet, cilësimet), faqet dhe artikujt, koleksionet, vlerësimet.

Për katalogë të mëdhenj manifesti kalon në mënyrën api: skedari i menusë përmban një përzgjedhje të lehtësuar, ndërsa kartelat e plota merren në skedarë të veçantë ose përmes API-së së katalogut me filtra dhe nënkategori.

Imazhet vijnë nga CDN-ja jonë, në disa madhësi sipas shabllonit të manifestit; kur përditësohet fotoja, shtegu merr një version të ri, kështu që cache-i mund të mbahet «përgjithmonë».

Nuk duhet t'i shkruani me dorë të gjitha këto kërkesa: paketa npm @cenaly/storefront ofron një klient të tipizuar të kontratës (manifest, profil, menu në të dyja mënyrat e katalogut, përfundim porosie), ndërtues URL-sh të imazheve dhe React hooks. Paketa ka një pikë hyrjeje të veçantë për ndërtimet statike (@cenaly/storefront/static: harta e adresave të faqes, sitemap.xml, robots.txt, lidhjet e imazheve) dhe komandën e konsolës cenaly-storefront — ruan një kopje të të gjitha të dhënave të vendndodhjes në një dosje, liston adresat dhe ofron mënyrën watch, e cila vëzhgon manifestin dhe nis ndërtimin tuaj sapo ndryshon publishId. Kjo paketë është edhe baza e projektit fillestar në Next.js, të cilin mund ta klononi dhe thjesht t'i ndryshoni ngjyrat.

Porositë dhe API-ja për vizitorët#

Pranimi i porosive, statusi i porosisë, kërkimi dhe rezervimet — përmes API-së për vizitorët: pa autorizim, adresa merret nga manifesti, specifikimi — OpenAPI 3.1. Veçmas ekziston kontura komerciale: kupona, llogaritja e dërgesës, formularë, abonime. Më shumë — Guest API për agjentë AI, i njëjti ndërfaqe.

Porosia, e krijuar nga faqja juaj, futet në seksionin e përbashkët «Porositë» dhe jeton sipas rregullave të zakonshme: statuse, kuzhinë, korrierë, fatura, njoftime.

Webhook-et për ndryshimet#

Për të mos kontrolluar vazhdimisht CDN-në, abonohuni te ngjarjet:

menu.updated — menuja ose katalogu u rigjenerua;
profile.updated — profili i vendndodhjes ndryshoi;
pages.updated — faqet dhe artikujt ndryshuan.

Trupi i ngjarjes përmban publishId — i dobishëm për të rindërtuar faqet statike ose për të pastruar cache-in ISR. Nëse keni caktuar një sekret, kërkesa nënshkruhet me HMAC-SHA256 dhe mbërrin me header-in X-Meni-Signature — kontrolloni nënshkrimin para çdo rindërtimi; për një deploy hook të Vercel/Netlify mund të mos caktoni sekret. Lejohen deri në pesë adresa për vendndodhje; pas dhjetë dështimeve radhazi abonimi çaktivizohet vetë (në panel shfaqen dërgesa e fundit dhe numëruesi i gabimeve; ruajtja përsëri e cilësimeve e riaktivizon).

Çfarë adrese pranon serveri. Vetëm https://, pa emër përdoruesi apo fjalëkalim brenda URL-së, dhe host-i duhet të jetë publik: adresat lokale, të brendshme dhe të shërbimit (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) refuzohen gjatë ruajtjes. Për korrigjimin e gabimeve në kompjuterin tuaj, hapni një tunel me adresë publike https.

Kur provohet përsëri. Përsëriten kërkesat që skadojnë dhe përgjigjet 5xx, 408, 429 — pra rastet që duken si dështim i përkohshëm. Çdo përgjigje tjetër 4xx konsiderohet gabim i përhershëm: nuk ka riprovim dhe tentativa shtohet menjëherë te numëruesi i dështimeve.

Webhook-et konfigurohen te karta «Vitrinë me kodin tuaj» dhe janë të disponueshme në planet me pagesë; leximi i të dhënave është gjithmonë i disponueshëm.

Nga t'ia filloni#

Hapni Marketing → «Faqja ime» → «Vitrinë me kodin tuaj» dhe kopjoni adresën e manifestit.
Ngarkoni manifestin dhe, përmes tij, të dhënat e menusë dhe profilit (ose instaloni paketën @cenaly/storefront dhe jepini slug-un e vendndodhjes). Në këtë hap nuk nevojitet asnjë çelës.
Ndërtoni faqet me framework-un tuaj; për porositë përdorni API-në për vizitorët.
Shtoni një webhook për ta rindërtuar faqen kur të ketë ndryshime — ose, nëse nuk keni adresë publike për të marrë ngjarje, nisni cenaly-storefront watch: ai vëzhgon vetë publishId në manifest dhe nis ndërtimin tuaj.

Përshkrimi i plotë teknik gjendet te lidhja «Dokumentacioni për zhvilluesit» në të njëjtën kartë; pranë saj janë lidhjet te udhëzuesi i veçantë për faqen statike dhe skemat JSON. Ka një projekt fillestar të gatshëm në Next.js, dhe i gjithë dokumentacioni ofrohet edhe në formatin llms.txt për asistentët me IA të zhvilluesit — përfshirë llms.txt personal të vendndodhjes suaj në CDN.

Seksione të lidhura#

Faqja ime — widget-e, nëse nuk keni nevojë të rishkruani të gjithë faqen
Guest API për agjentë AI — i njëjti API për vizitorët
API dhe MCP e telefonisë — qasje e agjentëve AI dhe CRM në telefoni
Dyqani online — çfarë saktësisht vjen në të dhënat e katalogut

Pyetje të shpeshta#

A duhet të paguaj për leximin e të dhënave? Jo. JSON-et publike janë të disponueshme në çdo plan — janë të njëjtët skedarë që përdor vitrina jonë. Me pagesë janë vetëm webhook-et.

Po me SEO-në? Ajo është plotësisht në anën tuaj: ju vetë i mblidhni faqet dhe vetë menaxhoni markimin. Të dhënat për mikro-markimin (JSON-LD) gjenden në kontratë.

A mund ta kombinoj me vitrinën time? Po. Vitrina jonë, uixhetët dhe sajti juaj punojnë me të njëjtat të dhëna dhe me një shportë të vetme porosish.