Witryna na własnym kodzie (headless)

Standardowa droga to nasza witryna lub widżety na Twojej stronie. Jeśli jednak stronę pisze Twój deweloper lub agencja i układ ma być w pełni własny, działa trzeci wariant: bierzesz od nas dane i przyjmowanie zamówień, a cały frontend tworzysz samodzielnie, na dowolnym stosie.

Odczyt danych nie wymaga kluczy ani autoryzacji: wszystko, co jest publiczne w witrynie, jest publiczne również w JSON.

Gdzie to się konfiguruje: Marketing → „Moja strona” → karta „Witryna na własnym kodzie”. Tam też znajduje się adres manifestu Twojej placówki, linki do dokumentacji technicznej i schematów JSON oraz konfiguracja webhooków. Niczego nie trzeba włączać: dane są publikowane zawsze.

Manifest storefront.json#

Jedyny adres, który musi znać deweloper:

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

W manifeście jest wszystko pozostałe:

Kontrakt jest wersjonowany (contractVersion), a obok leżą schematy JSON — wygodnie według nich walidować dane i generować typy. Nieznane pola należy ignorować: kontrakt rozszerza się bez łamania zgodności.

Dane i obrazy#

Wszystko, co pokazuje witryna, jest dostępne w plikach: menu i katalog według języków, profil placówki (nazwa, adres, godziny pracy, kontakty, ustawienia), strony i artykuły, kolekcje, opinie.

W przypadku dużych katalogów manifest przełącza się w tryb api: w pliku menu znajduje się uproszczony wybór, pełne karty pobiera się po pliku lub przez API katalogowe z filtrami i podkategoriami.

Obrazy — z naszego CDN, w kilku rozmiarach według szablonu z manifestu; przy aktualizacji zdjęcia ścieżka jest wersjonowana, więc pamięć podręczną można trzymać „na zawsze”.

Nie trzeba pisać tych wszystkich zapytań ręcznie: jest pakiet npm @cenaly/storefront — typowany klient kontraktu (manifest, profil, menu obu trybów katalogu, składanie zamówienia), konstruktor adresów URL obrazów i hooki React. Pakiet ma osobny punkt wejścia dla statycznych buildów (@cenaly/storefront/static: mapa adresów strony, sitemap.xml, robots.txt, linki do obrazów) oraz polecenie konsolowe cenaly-storefront — zrzut wszystkich danych placówki do folderu, lista adresów i tryb watch, który śledzi manifest i uruchamia Twój build, gdy tylko zmieni się publishId. Leży on również u podstaw projektu startowego na Next.js, który można sklonować i po prostu przemalować.

Zamówienia i gościnne API#

Przyjmowanie zamówień, status zamówienia, wyszukiwanie i rezerwacje — przez gościnne API: bez autoryzacji, adres pochodzi z manifestu, specyfikacja — OpenAPI 3.1. Osobno istnieje obieg komercyjny: kupony, obliczanie dostawy, formularze, subskrypcje. Więcej — Guest API dla agentów AI, ten sam interfejs.

Zamówienie utworzone przez Twoją stronę trafia do wspólnej sekcji „Zamówienia” i działa według zwykłych zasad: statusy, kuchnia, kurierzy, paragony, powiadomienia.

Webhooki o zmianach#

Aby nie odpytywać CDN, zasubskrybuj zdarzenia:

• menu.updated — menu lub katalog zostały zregenerowane;
• profile.updated — zmienił się profil placówki;
• pages.updated — zmieniły się strony i artykuły.

W treści zdarzenia przychodzi publishId — wygodnie według niego przebudowywać strony statyczne lub resetować pamięć podręczną ISR. Jeśli ustawiłeś sekret, żądanie jest podpisywane HMAC-SHA256 i przychodzi z nagłówkiem X-Meni-Signature — sprawdź podpis, zanim cokolwiek przebudujesz; dla hooka deploy Vercel/Netlify sekretu można nie zakładać. Do pięciu adresów na placówkę, a po dziesięciu niepowodzeniach z rzędu subskrypcja wyłącza się sama (w koncie widać ostatnie dostarczenie i licznik błędów; ponowne zapisanie ustawień włącza ją z powrotem).

Jaki adres przyjmie serwer. Tylko https://, bez loginu i hasła w samym URL, a host musi być publiczny: adresy lokalne, wewnętrzne i usługowe (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) są odrzucane przy zapisie. Do debugowania na własnej maszynie uruchom tunel z publicznym adresem https.

Kiedy bywa powtórzenie. Powtarzają się przekroczenia limitu czasu i odpowiedzi 5xx, 408, 429 — czyli to, co wygląda na tymczasową awarię. Każda inna odpowiedź 4xx jest uznawana za błąd trwały: powtórzenia nie będzie, próba od razu idzie do licznika niepowodzeń.

Webhooki konfiguruje się w karcie „Witryna na własnym kodzie” i są dostępne w płatnych planach; odczyt danych jest dostępny zawsze.

Od czego zacząć#

1. Otwórz Marketing → „Moja strona” → „Witryna na własnym kodzie” i skopiuj adres manifestu.
2. Pobierz manifest, a od niego — dane menu i profilu (albo zainstaluj pakiet @cenaly/storefront i przekaż mu slug placówki). Na tym kroku nie są potrzebne żadne klucze.
3. Zbuduj strony swoim frameworkiem; do zamówień używaj gościnnego API.
4. Dodaj webhook, aby przebudowywać stronę po fakcie zmian — albo, jeśli nie ma publicznego adresu do odbierania zdarzeń, uruchom cenaly-storefront watch: sam śledzi publishId w manifeście i uruchamia Twój build.

Pełny opis techniczny — pod linkiem „Dokumentacja dewelopera” w tej samej karcie; obok linki do osobnego przewodnika po stronie statycznej i do schematów JSON. Jest gotowy projekt startowy na Next.js, a cała dokumentacja jest powielona w postaci llms.txt dla asystentów AI dewelopera — w tym osobisty llms.txt Twojej placówki na CDN.

Powiązane sekcje#

• Moja strona — widżety, jeśli nie trzeba przepisywać całej strony
• Guest API dla agentów AI — to samo gościnne API
• API i MCP własnej centrali telefonicznej — dostęp agentów AI i CRM do telefonii
• Sklep internetowy — co dokładnie przychodzi w danych katalogu

Częste pytania#

Czy trzeba płacić za odczyt danych? Nie. Publiczne JSON są dostępne w każdym planie — to te same pliki, z których korzysta nasza witryna. Płatne są webhooki.

Co z SEO? Jest całkowicie po waszej stronie: strony składacie sami i sami zarządzacie znacznikami. Dane do mikrodanych (JSON-LD) są w kontrakcie.

Czy można łączyć z własną witryną? Tak. Nasza witryna, widżety i wasza własna strona działają na tych samych danych i jednym koszyku zamówień.