Izdvojena prodavnica na sopstvenom kodu (headless)

Uobičajen put je naša prodavnica ili vidžeti na vašem sajtu. Ali ako sajt piše vaš programer ili agencija i ako raspored treba da bude potpuno sopstven, radi i treća opcija: od nas uzimate podatke i prijem porudžbina, a ceo frontend pravite sami, na bilo kom steku.

Čitanje podataka ne zahteva ključeve ni autorizaciju: sve što je javno u prodavnici, javno je i u JSON-u.

Gde se podešava: Marketing → „Moj sajt“ → kartica „Izdvojena prodavnica na sopstvenom kodu“. Tu je i adresa manifesta vaše lokacije, linkovi ka tehničkoj dokumentaciji i JSON šemama i podešavanje vebhukova. Ništa ne treba uključivati: podaci se objavljuju uvek.

Manifest storefront.json#

Jedina adresa koju programer treba da zna:

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

U manifestu je sve ostalo:

Ugovor je verzionisan (contractVersion), a pored njega su i JSON šeme — po njima je zgodno validirati podatke i generisati tipove. Nepoznata polja treba ignorisati: ugovor se širi bez narušavanja kompatibilnosti.

Podaci i slike#

Sve što prodavnica prikazuje dostupno je u fajlovima: meni i katalog po jezicima, profil lokacije (naziv, adresa, radno vreme, kontakti, podešavanja), stranice i članci, kolekcije, recenzije.

Za velike kataloge manifest se prebacuje u režim api: u fajlu menija je olakšani izbor, a pune kartice se uzimaju po fajlu ili preko API-ja kataloga sa filterima i potkategorijama.

Slike su sa našeg CDN-a, u nekoliko veličina po šablonu iz manifesta; pri ažuriranju fotografije putanja se verzionise, pa keš može da se drži „zauvek“.

Nije obavezno da sve te zahteve pišete ručno: postoji npm paket @cenaly/storefront — tipizovani klijent ugovora (manifest, profil, meni oba režima kataloga, kreiranje porudžbine), graditelj URL-ova slika i React hookovi. Paket ima posebnu ulaznu tačku za statičke buildove (@cenaly/storefront/static: mapa adresa sajta, sitemap.xml, robots.txt, linkovi ka slikama) i konzolnu komandu cenaly-storefront — snimak svih podataka lokacije u fasciklu, listu adresa i režim watch, koji prati manifest i pokreće vaš build čim se promeni publishId. On je i osnova startnog projekta na Next.js-u, koji možete da klonirate i samo prebojite.

Porudžbine i gostujući API#

Prijem porudžbina, status porudžbine, pretraga i rezervacije — preko gostujućeg API-ja: bez autorizacije, adresa se uzima iz manifesta, specifikacija je OpenAPI 3.1. Odvojeno postoji komercijalni kontur: kuponi, obračun dostave, forme, pretplate. Više — Guest API za AI agente, isti interfejs.

Porudžbina koju kreira vaš sajt dospeva u zajednički odeljak „Porudžbine“ i živi po uobičajenim pravilima: statusi, kuhinja, kuriri, računi, obaveštenja.

Vebhukovi o izmenama#

Da ne biste anketirali CDN, pretplatite se na događaje:

• menu.updated — meni ili katalog su ponovo generisani;
• profile.updated — promenjen je profil lokacije;
• pages.updated — promenjene su stranice i članci.

U telu događaja stiže publishId — po njemu je zgodno ponovo graditi statičke stranice ili resetovati ISR keš. Ako ste zadali tajnu, zahtev se potpisuje HMAC-SHA256 i stiže sa zaglavljem X-Meni-Signature — proverite potpis pre nego što bilo šta ponovo gradite; za deploy hook Vercel/Netlify tajna ne mora da se postavlja. Do pet adresa po lokaciji, a posle deset uzastopnih neuspeha pretplata se sama isključuje (u nalogu se vidi poslednja dostava i brojač grešaka; ponovno čuvanje podešavanja je uključuje nazad).

Koju adresu će server prihvatiti. Samo https://, bez korisničkog imena i lozinke u samom URL-u, i host mora biti javni: lokalne, interne i servisne adrese (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) se odbijaju pri čuvanju. Za debagovanje na sopstvenoj mašini podignite tunel sa javnom https adresom.

Kada dolazi do ponavljanja. Ponavljaju se tajmauti i odgovori 5xx, 408, 429 — dakle ono što liči na privremeni zastoj. Svaki drugi odgovor 4xx smatra se trajnom greškom: ponavljanja neće biti, pokušaj odmah ide u brojač neuspeha.

Vebhukovi se podešavaju u kartici „Izdvojena prodavnica na sopstvenom kodu“ i dostupni su na plaćenim planovima; čitanje podataka je dostupno uvek.

Odakle početi#

1. Otvorite Marketing → „Moj sajt“ → „Izdvojena prodavnica na sopstvenom kodu“ i kopirajte adresu manifesta.
2. Učitajte manifest i od njega — podatke menija i profila (ili postavite paket @cenaly/storefront i prosledite mu slag lokacije). Nikakvi ključevi u ovom koraku nisu potrebni.
3. Izgradite stranice svojim frejmvorkom; za porudžbine koristite gostujući API.
4. Dodajte vebhuk da ponovo gradite sajt po izvršenoj izmeni — ili, ako nemate javnu adresu za prijem događaja, pokrenite cenaly-storefront watch: on sam prati publishId u manifestu i pokreće vaš build.

Potpuni tehnički opis je na linku „Dokumentacija za programere“ u istoj kartici; pored su linkovi ka posebnom uputstvu za statički sajt i ka JSON šemama. Postoji i gotov startni projekat na Next.js-u, a cela dokumentacija se duplira kao llms.txt za AI asistente programera — uključujući lični llms.txt vaše lokacije na CDN-u.

Povezani odeljci#

• Moj sajt — vidžeti, ako ne želite da prepisujete ceo sajt
• Guest API za AI agente — isti gostujući API
• API i MCP vaše telefonije — pristup AI agenata i CRM-a telefoniji
• Internet prodavnica — šta tačno stiže u podacima kataloga

Česta pitanja#

Da li se čitanje podataka plaća? Ne. Javni JSON je dostupan na svakom planu — to su isti fajlovi koje koristi i naša vitrina. Veebhukovi se plaćaju.

Šta je sa SEO? On je potpuno na vašoj strani: sami sastavljate stranice i sami upravljate označavanjem. Podaci za mikromarkup (JSON-LD) postoje u ugovoru.

Može li se kombinovati sa sopstvenom vitrinom? Da. Naša vitrina, vidžeti i vaš sopstveni sajt rade sa istim podacima i istom korpom porudžbina.