Schaufenster auf eigenem Code (headless)

Der übliche Weg ist unser Schaufenster oder Widgets auf Ihrer Website. Wenn die Website jedoch von Ihrem Entwickler oder einer Agentur geschrieben wird und das Layout vollständig eigen sein soll, funktioniert die dritte Variante: Sie beziehen von uns Daten und Bestellannahme, und das gesamte Frontend erstellen Sie selbst, auf jedem Stack.

Das Lesen der Daten erfordert keine Schlüssel und keine Autorisierung: Alles, was im Schaufenster öffentlich ist, ist auch im JSON öffentlich.

Wo dies konfiguriert wird: Marketing → „Meine Website“ → Karte „Schaufenster auf eigenem Code“. Dort finden Sie auch die Adresse des Manifests Ihres Standorts, Links zur technischen Dokumentation und zu den JSON-Schemas sowie die Konfiguration der Webhooks. Es muss nichts aktiviert werden: Die Daten werden immer veröffentlicht.

Manifest storefront.json#

Die einzige Adresse, die der Entwickler kennen muss:

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

Im Manifest steht alles Weitere:

Block	Was darin enthalten ist
`location`	Identifikator, Slug, Vertikale (Restaurant, Geschäft, Hotel, Salon)
`languages`	Standardsprache und Liste der aktivierten Sprachen
`currency`	Währungscode und Währungssymbol
`cdnBase` + `data`	Pfade zu Menü, Profil, Seiten, Kollektionen, Bewertungen und Empfehlungen „damit kaufen Kunden auch“
`catalog`	Katalogmodus: alles in Dateien oder dateiweise Karten und Katalog-API
`images`	Bildbasis, Pfadvorlagen (Foto des Artikels und Galerien, Video, Kategorien, Kollektionen, Titelbild und Logo, favicon) und verfügbare Größen
`api`	Adressen der Gast-API, OpenAPI-Spezifikationen, des kommerziellen Konturs, des MCP-Endpunkts und des WebSocket für Live-Bestellstatus
`publishId`, `publishedAt`	Identifikator der Veröffentlichung: ändert sich bei jeder Neugenerierung der Daten

Der Vertrag ist versioniert (contractVersion), und daneben liegen JSON-Schemas — mit ihnen lassen sich Daten bequem validieren und Typen generieren. Unbekannte Felder müssen ignoriert werden: Der Vertrag wird ohne Bruch der Kompatibilität erweitert.

Daten und Bilder#

Alles, was das Schaufenster anzeigt, ist als Dateien verfügbar: Menü und Katalog nach Sprachen, Standortprofil (Name, Adresse, Öffnungszeiten, Kontakte, Einstellungen), Seiten und Artikel, Kollektionen, Bewertungen.

Für große Kataloge wechselt das Manifest in den Modus api: In der Menüdatei liegt eine erleichterte Auswahl, vollständige Karten werden dateiweise oder über die Katalog-API mit Filtern und Unterkategorien bezogen.

Bilder stammen von unserem CDN, in mehreren Größen nach der Vorlage aus dem Manifest; bei Aktualisierung eines Fotos wird der Pfad versioniert, daher kann der Cache „für immer“ gehalten werden.

Es ist nicht zwingend, all diese Anfragen von Hand zu schreiben: Es gibt das npm-Paket @cenaly/storefront — ein typisierter Client des Vertrags (Manifest, Profil, Menü beider Katalogmodi, Bestellabwicklung), einen URL-Builder für Bilder und React-Hooks. Das Paket hat einen separaten Einstiegspunkt für statische Builds (@cenaly/storefront/static: Adresskarte der Website, sitemap.xml, robots.txt, Bildlinks) und den Konsolenbefehl cenaly-storefront — einen Schnappschuss aller Standortdaten in einen Ordner, eine Adressliste und den Modus watch, der das Manifest überwacht und Ihren Build startet, sobald sich publishId ändert. Er liegt auch dem Startprojekt auf Next.js zugrunde, das geklont und einfach umgefärbt werden kann.

Bestellungen und Gast-API#

Bestellannahme, Bestellstatus, Suche und Reservierungen — über die Gast-API: ohne Autorisierung, die Adresse wird aus dem Manifest bezogen, die Spezifikation ist OpenAPI 3.1. Separat gibt es den kommerziellen Kontur: Coupons, Lieferberechnung, Formulare, Abonnements. Mehr dazu — Guest API für AI-Agenten, dieselbe Schnittstelle.

Eine Bestellung, die von Ihrer Website erstellt wird, landet im gemeinsamen Bereich „Bestellungen“ und lebt nach den üblichen Regeln: Status, Küche, Kuriere, Belege, Benachrichtigungen.

Webhooks über Änderungen#

Um das CDN nicht abzufragen, abonnieren Sie Ereignisse:

menu.updated — Menü oder Katalog wurden neu generiert;
profile.updated — das Standortprofil hat sich geändert;
pages.updated — Seiten und Artikel haben sich geändert.

Im Ereignisrumpf kommt publishId mit — damit lassen sich statische Seiten bequem neu bauen oder der ISR-Cache zurücksetzen. Wenn Sie ein Secret gesetzt haben, wird die Anfrage mit HMAC-SHA256 signiert und kommt mit dem Header X-Meni-Signature — prüfen Sie die Signatur, bevor Sie etwas neu bauen; für einen Deploy-Hook von Vercel/Netlify muss kein Secret angelegt werden. Bis zu fünf Adressen pro Standort, und nach zehn Fehlschlägen in Folge wird das Abonnement selbst deaktiviert (im Konto sind die letzte Zustellung und der Fehlerzähler sichtbar; erneutes Speichern der Einstellungen aktiviert es wieder).

Welche Adresse der Server annimmt. Nur https://, ohne Login und Passwort in der URL selbst, und der Host muss öffentlich sein: lokale, interne und Dienstadressen (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) werden beim Speichern abgelehnt. Für die Fehlersuche auf Ihrem Rechner richten Sie einen Tunnel mit öffentlicher https-Adresse ein.

Wann es eine Wiederholung gibt. Wiederholt werden Timeouts und Antworten 5xx, 408, 429 — also das, was wie eine vorübergehende Störung aussieht. Jede andere Antwort 4xx gilt als dauerhafter Fehler: Es gibt keine Wiederholung, der Versuch geht sofort in den Fehlerzähler ein.

Webhooks werden in der Karte „Schaufenster auf eigenem Code“ konfiguriert und sind in den kostenpflichtigen Plänen verfügbar; das Lesen der Daten ist immer verfügbar.

Womit anfangen#

Öffnen Sie Marketing → „Meine Website“ → „Schaufenster auf eigenem Code“ und kopieren Sie die Manifest-Adresse.
Laden Sie das Manifest und daraus die Menü- und Profildaten (oder installieren Sie das Paket @cenaly/storefront und übergeben Sie ihm den Slug des Standorts). In diesem Schritt sind keine Schlüssel nötig.
Bauen Sie die Seiten mit Ihrem Framework; für Bestellungen verwenden Sie die Gast-API.
Fügen Sie einen Webhook hinzu, um die Website bei Änderungen neu zu bauen — oder, wenn keine öffentliche Adresse für den Empfang von Ereignissen vorhanden ist, starten Sie cenaly-storefront watch: Er überwacht selbst publishId im Manifest und startet Ihren Build.

Die vollständige technische Beschreibung finden Sie unter dem Link „Entwicklerdokumentation“ in derselben Karte; daneben Links zu einer separaten Anleitung für statische Websites und zu den JSON-Schemas. Es gibt ein fertiges Startprojekt auf Next.js, und die gesamte Dokumentation ist auch als llms.txt für die KI-Assistenten des Entwicklers verfügbar — einschließlich einer persönlichen llms.txt Ihres Standorts auf dem CDN.

Häufige Fragen#

Muss man für das Lesen der Daten bezahlen? Nein. Die öffentlichen JSON sind in jedem Plan verfügbar — es sind dieselben Dateien, die unser Storefront verwendet. Kostenpflichtig sind die Webhooks.

Wie sieht es mit SEO aus? Das liegt vollständig bei Ihnen: Sie bauen die Seiten selbst und steuern das Markup selbst. Die Daten für das Microdata-Markup (JSON-LD) sind im Vertrag enthalten.

Kann man es mit dem eigenen Storefront kombinieren? Ja. Unser Storefront, die Widgets und Ihre eigene Website arbeiten mit denselben Daten und demselben Warenkorb für Bestellungen.

Schaufenster mit eigenem Code