Vetrina su codice proprio (headless)

Il percorso abituale è la nostra vetrina o i widget sul vostro sito. Ma se il sito viene sviluppato dal vostro sviluppatore o da un'agenzia e l'impaginazione deve essere completamente propria, esiste una terza opzione: prendete da noi i dati e l'accettazione degli ordini, mentre realizzate tutto il frontend da soli, con qualsiasi stack.

La lettura dei dati non richiede chiavi né autorizzazione: tutto ciò che è pubblico nella vetrina è pubblico anche nel JSON.

Dove si configura: Marketing → «Il mio sito» → scheda «Vetrina su codice proprio». Qui si trovano anche l'indirizzo del manifest della vostra sede, i link alla documentazione tecnica e agli schemi JSON e la configurazione dei webhook. Non serve attivare nulla: i dati vengono pubblicati sempre.

Manifest storefront.json#

L'unico indirizzo che lo sviluppatore deve conoscere:

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

Nel manifest c'è tutto il resto:

Blocco	Cosa contiene
`location`	Identificatore, slug, verticale (ristorante, negozio, hotel, salone)
`languages`	Lingua predefinita ed elenco delle lingue abilitate
`currency`	Codice e simbolo della valuta
`cdnBase` + `data`	Percorsi a menu, profilo, pagine, collezioni, recensioni e consigli «acquistati insieme»
`catalog`	Modalità del catalogo: tutto nei file oppure schede per file e API del catalogo
`images`	Base delle immagini, modelli dei percorsi (foto dell'articolo e gallerie, video, categorie, collezioni, copertina e logo, favicon) e dimensioni disponibili
`api`	Indirizzi dell'API guest, specifiche OpenAPI, contorno commerciale, endpoint MCP e WebSocket degli stati dell'ordine in tempo reale
`publishId`, `publishedAt`	Identificatore della pubblicazione: cambia a ogni rigenerazione dei dati

Il contratto è versionato (contractVersion) e accanto si trovano gli schemi JSON: sono utili per validare i dati e generare i tipi. I campi sconosciuti vanno ignorati: il contratto si estende senza rompere la compatibilità.

Dati e immagini#

Tutto ciò che mostra la vetrina è disponibile come file: menu e catalogo per lingua, profilo della sede (nome, indirizzo, orari di apertura, contatti, impostazioni), pagine e articoli, collezioni, recensioni.

Per i cataloghi di grandi dimensioni il manifest passa alla modalità api: nel file del menu si trova una selezione alleggerita, mentre le schede complete si prendono per file o tramite l'API del catalogo con filtri e sottocategorie.

Le immagini provengono dal nostro CDN, in diverse dimensioni secondo il modello del manifest; quando una foto viene aggiornata il percorso viene versionato, quindi la cache può essere mantenuta «per sempre».

Non è obbligatorio scrivere tutte queste richieste a mano: esiste il pacchetto npm @cenaly/storefront — client tipizzato del contratto (manifest, profilo, menu di entrambe le modalità del catalogo, creazione dell'ordine), costruttore di URL delle immagini e hook React. Il pacchetto ha un punto di ingresso separato per le build statiche (@cenaly/storefront/static: mappa degli indirizzi del sito, sitemap.xml, robots.txt, link alle immagini) e un comando da console cenaly-storefront — snapshot di tutti i dati della sede in una cartella, elenco degli indirizzi e modalità watch, che sorveglia il manifest e avvia la vostra build non appena cambia publishId. È anche alla base del progetto iniziale su Next.js, che si può clonare e semplicemente ricolorare.

Ordini e API guest#

Accettazione degli ordini, stato dell'ordine, ricerca e prenotazioni passano attraverso l'API guest: senza autorizzazione, l'indirizzo si prende dal manifest, la specifica è OpenAPI 3.1. Separatamente esiste il contorno commerciale: coupon, calcolo della consegna, moduli, abbonamenti. Per approfondire — Guest API per agenti AI, la stessa interfaccia.

L'ordine creato dal vostro sito finisce nella sezione comune «Ordini» e segue le regole abituali: stati, cucina, corrieri, ricevute, notifiche.

Webhook sulle modifiche#

Per non interrogare il CDN, sottoscrivete gli eventi:

menu.updated — menu o catalogo rigenerati;
profile.updated — il profilo della sede è cambiato;
pages.updated — pagine e articoli sono cambiati.

Nel corpo dell'evento arriva publishId: è utile per ricostruire le pagine statiche o azzerare la cache ISR. Se avete impostato un segreto, la richiesta viene firmata con HMAC-SHA256 e arriva con l'intestazione X-Meni-Signature: verificate la firma prima di ricostruire qualcosa; per il deploy hook di Vercel/Netlify il segreto può non essere impostato. Fino a cinque indirizzi per sede, e dopo dieci errori consecutivi la sottoscrizione si disattiva da sola (nell'area riservata si vedono l'ultima consegna e il contatore degli errori; salvando di nuovo le impostazioni si riattiva).

Quale indirizzo accetta il server. Solo https://, senza login e password nell'URL stesso, e l'host deve essere pubblico: gli indirizzi locali, interni e di servizio (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) vengono rifiutati al salvataggio. Per il debug sulla propria macchina, avviate un tunnel con un indirizzo https pubblico.

Quando avviene un nuovo tentativo. Vengono ritentati i timeout e le risposte 5xx, 408, 429, cioè ciò che sembra un guasto temporaneo. Qualsiasi altra risposta 4xx è considerata un errore permanente: non ci sarà un nuovo tentativo, il tentativo va subito nel contatore degli errori.

I webhook si configurano nella scheda «Vetrina su codice proprio» e sono disponibili sui piani a pagamento; la lettura dei dati è disponibile sempre.

Da dove iniziare#

Aprite Marketing → «Il mio sito» → «Vetrina su codice proprio» e copiate l'indirizzo del manifest.
Scaricate il manifest e da esso i dati del menu e del profilo (oppure installate il pacchetto @cenaly/storefront e passategli lo slug della sede). In questo passaggio non serve alcuna chiave.
Costruite le pagine con il vostro framework; per gli ordini usate l'API guest.
Aggiungete un webhook per ricostruire il sito in base alle modifiche, oppure, se non avete un indirizzo pubblico per ricevere gli eventi, avviate cenaly-storefront watch: sorveglia da solo il publishId nel manifest e avvia la vostra build.

La descrizione tecnica completa è al link «Documentazione per sviluppatori» nella stessa scheda; accanto ci sono i link alla guida separata sul sito statico e agli schemi JSON. Esiste un progetto iniziale pronto su Next.js, e tutta la documentazione è duplicata come llms.txt per gli assistenti AI dello sviluppatore, incluso il llms.txt personale della vostra sede sul CDN.

Sezioni correlate#

Il mio sito — widget, se non è necessario riscrivere l'intero sito
Guest API per agenti AI — lo stesso guest API
API e MCP del proprio centralino — accesso di agenti AI e CRM alla telefonia
Negozio online — cosa arriva esattamente nei dati del catalogo

Domande frequenti#

Bisogna pagare per la lettura dei dati? No. I JSON pubblici sono disponibili su qualsiasi piano — sono gli stessi file utilizzati dalla nostra vetrina. A pagamento sono i webhook.

E per la SEO? È interamente dalla vostra parte: assemblate le pagine da soli e gestite voi stessi il markup. I dati per il microdata (JSON-LD) sono previsti nel contratto.

Si può combinare con la propria vetrina? Sì. La nostra vetrina, i widget e il vostro sito personale lavorano con gli stessi dati e un unico carrello degli ordini.