Βιτρίνα στον δικό σας κώδικα (headless)

Η συνήθης διαδρομή είναι η βιτρίνα μας ή τα widgets στον ιστότοπό σας. Αν όμως ο ιστότοπος γράφεται από τον προγραμματιστή ή το πρακτορείο σας και η διάταξη πρέπει να είναι εξ ολοκλήρου δική σας, λειτουργεί μια τρίτη επιλογή: παίρνετε από εμάς δεδομένα και αποδοχή παραγγελιών, και όλο το frontend το φτιάχνετε μόνοι σας, σε οποιοδήποτε stack.

Η ανάγνωση δεδομένων δεν απαιτεί κλειδιά και εξουσιοδότηση: ό,τι είναι δημόσιο στη βιτρίνα είναι δημόσιο και στο JSON.

Πού ρυθμίζεται: Μάρκετινγκ → «Ο ιστότοπός μου» → κάρτα «Βιτρίνα στον δικό σας κώδικα». Εκεί βρίσκεται και η διεύθυνση του manifest του καταστήματός σας, σύνδεσμοι προς την τεχνική τεκμηρίωση και τα JSON-schemas, και η ρύθμιση των webhooks. Δεν χρειάζεται να ενεργοποιήσετε τίποτα: τα δεδομένα δημοσιεύονται πάντα.

Manifest storefront.json#

Η μοναδική διεύθυνση που πρέπει να γνωρίζει ο προγραμματιστής:

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

Στο manifest βρίσκονται όλα τα υπόλοιπα:

Μπλοκ	Τι περιέχει
`location`	Αναγνωριστικό, slug, κάθετος τομέας (εστιατόριο, κατάστημα, ξενοδοχείο, σαλόνι)
`languages`	Προεπιλεγμένη γλώσσα και λίστα ενεργοποιημένων γλωσσών
`currency`	Κωδικός και σύμβολο νομίσματος
`cdnBase` + `data`	Διαδρομές προς μενού, προφίλ, σελίδες, συλλογές, κριτικές και προτάσεις «αγοράζονται μαζί με αυτό»
`catalog`	Λειτουργία καταλόγου: όλα σε αρχεία ή καρτέλες ανά αρχείο και API καταλόγου
`images`	Βάση εικόνων, πρότυπα διαδρομών (φωτογραφία είδους και γκαλερί, βίντεο, κατηγορίες, συλλογές, εξώφυλλο και λογότυπο, favicon) και διαθέσιμα μεγέθη
`api`	Διευθύνσεις του guest API, προδιαγραφές OpenAPI, του εμπορικού περιγράμματος, του MCP-endpoint και του WebSocket ζωντανών καταστάσεων παραγγελίας
`publishId`, `publishedAt`	Αναγνωριστικό δημοσίευσης: αλλάζει σε κάθε αναδημιουργία δεδομένων

Το συμβόλαιο έχει εκδόσεις (contractVersion), και δίπλα βρίσκονται JSON-schemas — με αυτά μπορείτε εύκολα να επικυρώνετε δεδομένα και να δημιουργείτε τύπους. Τα άγνωστα πεδία πρέπει να αγνοούνται: το συμβόλαιο επεκτείνεται χωρίς να σπάει η συμβατότητα.

Δεδομένα και εικόνες#

Ό,τι εμφανίζει η βιτρίνα είναι διαθέσιμο ως αρχεία: μενού και κατάλογος ανά γλώσσα, προφίλ καταστήματος (όνομα, διεύθυνση, ώρες λειτουργίας, επαφές, ρυθμίσεις), σελίδες και άρθρα, συλλογές, κριτικές.

Για μεγάλους καταλόγους το manifest περνά σε λειτουργία api: στο αρχείο μενού υπάρχει μια ελαφριά επιλογή, και οι πλήρεις καρτέλες λαμβάνονται ανά αρχείο ή μέσω του API καταλόγου με φίλτρα και υποκατηγορίες.

Οι εικόνες προέρχονται από το CDN μας, σε πολλά μεγέθη κατά το πρότυπο από το manifest· όταν ενημερώνεται μια φωτογραφία, η διαδρομή αποκτά νέα έκδοση, οπότε η cache μπορεί να κρατηθεί «για πάντα».

Δεν είναι υποχρεωτικό να γράφετε όλα αυτά τα αιτήματα με το χέρι: υπάρχει το npm-package @cenaly/storefront — ένας τυποποιημένος client του συμβολαίου (manifest, προφίλ, μενού και των δύο λειτουργιών καταλόγου, ολοκλήρωση παραγγελίας), ένας builder URL εικόνων και React-hooks. Το package έχει ξεχωριστό σημείο εισόδου για στατικές κατασκευές (@cenaly/storefront/static: χάρτης διευθύνσεων ιστότοπου, sitemap.xml, robots.txt, σύνδεσμοι εικόνων) και μια εντολή κονσόλας cenaly-storefront — ένα στιγμιότυπο όλων των δεδομένων του καταστήματος σε φάκελο, λίστα διευθύνσεων και λειτουργία watch, που παρακολουθεί το manifest και εκκινεί την κατασκευή σας μόλις αλλάξει το publishId. Βρίσκεται επίσης στη βάση του αρχικού έργου σε Next.js, το οποίο μπορείτε να κλωνοποιήσετε και απλώς να αλλάξετε χρώματα.

Παραγγελίες και guest API#

Η αποδοχή παραγγελιών, η κατάσταση παραγγελίας, η αναζήτηση και οι κρατήσεις γίνονται μέσω του guest API: χωρίς εξουσιοδότηση, η διεύθυνση λαμβάνεται από το manifest, η προδιαγραφή είναι OpenAPI 3.1. Ξεχωριστά υπάρχει το εμπορικό περίγραμμα: κουπόνια, υπολογισμός παράδοσης, φόρμες, συνδρομές. Περισσότερα — Guest API για AI-πράκτορες, η ίδια διεπαφή.

Η παραγγελία που δημιουργεί ο ιστότοπός σας καταλήγει στην κοινή ενότητα «Παραγγελίες» και λειτουργεί με τους συνήθεις κανόνες: καταστάσεις, κουζίνα, διανομείς, αποδείξεις, ειδοποιήσεις.

Webhooks για αλλαγές#

Για να μην κάνετε συνεχείς ερωτήματα στο CDN, εγγραφείτε σε συμβάντα:

menu.updated — το μενού ή ο κατάλογος αναδημιουργήθηκαν;
profile.updated — άλλαξε το προφίλ του καταστήματος;
pages.updated — άλλαξαν οι σελίδες και τα άρθρα.

Στο σώμα του συμβάντος έρχεται το publishId — με αυτό μπορείτε εύκολα να ξαναχτίσετε στατικές σελίδες ή να καθαρίσετε την cache του ISR. Αν έχετε ορίσει secret, το αίτημα υπογράφεται με HMAC-SHA256 και έρχεται με την κεφαλίδα X-Meni-Signature — ελέγξτε την υπογραφή πριν ξαναχτίσετε οτιδήποτε· για deploy-hook του Vercel/Netlify δεν χρειάζεται να ορίσετε secret. Έως πέντε διευθύνσεις ανά κατάστημα, και μετά από δέκα συνεχόμενες αποτυχίες η εγγραφή απενεργοποιείται μόνη της (στον λογαριασμό φαίνεται η τελευταία παράδοση και ο μετρητής σφαλμάτων· η εκ νέου αποθήκευση των ρυθμίσεων την ενεργοποιεί ξανά).

Ποια διεύθυνση δέχεται ο server. Μόνο https://, χωρίς login και password στο ίδιο το URL, και ο host πρέπει να είναι δημόσιος: τοπικές, εσωτερικές και υπηρεσιακές διευθύνσεις (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) απορρίπτονται κατά την αποθήκευση. Για αποσφαλμάτωση στον υπολογιστή σας, σηκώστε ένα tunnel με δημόσια διεύθυνση https.

Πότε γίνεται επανάληψη. Επαναλαμβάνονται τα timeouts και οι απαντήσεις 5xx, 408, 429 — δηλαδή ό,τι μοιάζει με προσωρινή βλάβη. Οποιαδήποτε άλλη απάντηση 4xx θεωρείται μόνιμο σφάλμα: δεν θα γίνει επανάληψη, η προσπάθεια πηγαίνει αμέσως στον μετρητή αποτυχιών.

Τα webhooks ρυθμίζονται στην κάρτα «Βιτρίνα στον δικό σας κώδικα» και είναι διαθέσιμα στα πλάνα επί πληρωμή· η ανάγνωση δεδομένων είναι διαθέσιμη πάντα.

Από πού να ξεκινήσετε#

Ανοίξτε Μάρκετινγκ → «Ο ιστότοπός μου» → «Βιτρίνα στον δικό σας κώδικα» και αντιγράψτε τη διεύθυνση του manifest.
Κατεβάστε το manifest και από αυτό — τα δεδομένα μενού και προφίλ (ή εγκαταστήστε το package @cenaly/storefront και περάστε του το slug του καταστήματος). Δεν χρειάζονται κλειδιά σε αυτό το βήμα.
Χτίστε τις σελίδες με το framework σας· για τις παραγγελίες χρησιμοποιήστε το guest API.
Προσθέστε ένα webhook, ώστε να ξαναχτίζετε τον ιστότοπο μετά από αλλαγές — ή, αν δεν υπάρχει δημόσια διεύθυνση για λήψη συμβάντων, εκτελέστε cenaly-storefront watch: παρακολουθεί μόνο του το publishId στο manifest και εκκινεί την κατασκευή σας.

Η πλήρης τεχνική περιγραφή βρίσκεται στον σύνδεσμο «Τεκμηρίωση προγραμματιστή» στην ίδια κάρτα· δίπλα υπάρχουν σύνδεσμοι προς ξεχωριστό οδηγό για στατικό ιστότοπο και προς τα JSON-schemas. Υπάρχει έτοιμο αρχικό έργο σε Next.js, και όλη η τεκμηρίωση αντιγράφεται σε μορφή llms.txt για τους AI-assistants του προγραμματιστή — συμπεριλαμβανομένου του προσωπικού llms.txt του καταστήματός σας στο CDN.

Σχετικές ενότητες#

Ο ιστότοπός μου — widgets, αν δεν χρειάζεται να ξαναγράψετε ολόκληρο τον ιστότοπο
Guest API για AI agents — το ίδιο guest API
API και MCP του δικού σας τηλεφωνικού κέντρου — πρόσβαση AI agents και CRM στην τηλεφωνία
Ηλεκτρονικό κατάστημα — τι ακριβώς φτάνει στα δεδομένα του καταλόγου

Συχνές ερωτήσεις#

Χρειάζεται να πληρώνω για την ανάγνωση δεδομένων; Όχι. Τα δημόσια JSON είναι διαθέσιμα σε οποιοδήποτε πλάνο — είναι τα ίδια αρχεία που χρησιμοποιεί η βιτρίνα μας. Χρεώσιμα είναι τα webhooks.

Τι γίνεται με το SEO; Είναι εξ ολοκλήρου δική σας ευθύνη: συναρμολογείτε τις σελίδες μόνοι σας και διαχειρίζεστε μόνοι σας τη σήμανση. Δεδομένα για μικροσήμανση (JSON-LD) υπάρχουν στο συμβόλαιο.

Μπορώ να το συνδυάσω με τη δική μου βιτρίνα; Ναι. Η βιτρίνα μας, τα widgets και ο δικός σας ιστότοπος λειτουργούν με τα ίδια δεδομένα και το ίδιο καλάθι παραγγελιών.