Vitrine sur votre propre code (headless)

La voie habituelle est notre vitrine ou les widgets sur votre site. Mais si le site est écrit par votre développeur ou une agence et que l'intégration doit être entièrement la vôtre, une troisième option s'offre à vous : vous prenez chez nous les données et la prise de commandes, et vous réalisez tout le frontend vous-même, sur n'importe quelle stack.

La lecture des données ne nécessite ni clés ni autorisation : tout ce qui est public sur la vitrine est public en JSON.

Où cela se configure : Marketing → « Mon site » → carte « Vitrine sur votre propre code ». Vous y trouverez aussi l'adresse du manifeste de votre établissement, les liens vers la documentation technique et les schémas JSON, ainsi que la configuration des webhooks. Rien à activer : les données sont publiées en permanence.

Manifeste storefront.json#

La seule adresse que le développeur doit connaître :

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

Le manifeste contient tout le reste :

Bloc	Contenu
`location`	Identifiant, slug, vertical (restaurant, boutique, hôtel, salon)
`languages`	Langue par défaut et liste des langues activées
`currency`	Code et symbole de la devise
`cdnBase` + `data`	Chemins vers le menu, le profil, les pages, les collections, les avis et les recommandations « les clients achètent aussi »
`catalog`	Mode du catalogue : tout en fichiers, ou fiches par fichier et API de catalogue
`images`	Base des images, modèles de chemins (photo d'article et galeries, vidéo, catégories, collections, couverture et logo, favicon) et tailles disponibles
`api`	Adresses de l'API invité, spécifications OpenAPI, du contour commercial, de l'endpoint MCP et du WebSocket des statuts de commande en direct
`publishId`, `publishedAt`	Identifiant de publication : change à chaque régénération des données

Le contrat est versionné (contractVersion), et à côté se trouvent les schémas JSON — pratiques pour valider les données et générer des types. Les champs inconnus doivent être ignorés : le contrat s'étend sans casser la compatibilité.

Données et images#

Tout ce que la vitrine affiche est disponible sous forme de fichiers : menu et catalogue par langue, profil de l'établissement (nom, adresse, horaires, contacts, réglages), pages et articles, collections, avis.

Pour les grands catalogues, le manifeste bascule en mode api : le fichier de menu contient une sélection allégée, les fiches complètes sont récupérées fichier par fichier ou via l'API de catalogue avec filtres et sous-catégories.

Les images proviennent de notre CDN, en plusieurs tailles selon le modèle du manifeste ; lors d'une mise à jour de photo, le chemin est versionné, ce qui permet de conserver le cache « pour toujours ».

Pas besoin d'écrire toutes ces requêtes à la main : il existe un paquet npm @cenaly/storefront — un client typé du contrat (manifeste, profil, menu des deux modes de catalogue, passage de commande), un constructeur d'URL d'images et des hooks React. Le paquet dispose d'un point d'entrée dédié aux builds statiques (@cenaly/storefront/static : carte des adresses du site, sitemap.xml, robots.txt, liens vers les images) et d'une commande en ligne de commande cenaly-storefront — un instantané de toutes les données de l'établissement dans un dossier, la liste des adresses et un mode watch qui surveille le manifeste et lance votre build dès que publishId change. Il est aussi à la base du projet de démarrage Next.js, que vous pouvez cloner et simplement recolorer.

Commandes et API invité#

La prise de commandes, le statut de commande, la recherche et les réservations passent par l'API invité : sans autorisation, l'adresse provient du manifeste, la spécification est OpenAPI 3.1. Il existe séparément un contour commercial : coupons, calcul de livraison, formulaires, abonnements. Plus de détails — Guest API pour les agents AI, la même interface.

Une commande créée par votre site arrive dans la section commune « Commandes » et suit les règles habituelles : statuts, cuisine, coursiers, reçus, notifications.

Webhooks sur les changements#

Pour ne pas interroger le CDN, abonnez-vous aux événements :

menu.updated — le menu ou le catalogue a été régénéré ;
profile.updated — le profil de l'établissement a changé ;
pages.updated — les pages et articles ont changé.

Le corps de l'événement contient publishId — pratique pour reconstruire les pages statiques ou vider le cache ISR. Si vous avez défini un secret, la requête est signée en HMAC-SHA256 et arrive avec l'en-tête X-Meni-Signature — vérifiez la signature avant de reconstruire quoi que ce soit ; pour un deploy hook Vercel/Netlify, le secret n'est pas nécessaire. Jusqu'à cinq adresses par établissement, et après dix échecs consécutifs l'abonnement se désactive de lui-même (le compte affiche la dernière livraison et le compteur d'erreurs ; un nouvel enregistrement des réglages le réactive).

Quelle adresse le serveur acceptera. Uniquement https://, sans identifiant ni mot de passe dans l'URL elle-même, et l'hôte doit être public : les adresses locales, internes et de service (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) sont refusées à l'enregistrement. Pour déboguer sur votre machine, montez un tunnel avec une adresse https publique.

Quand une nouvelle tentative a lieu. Les timeouts et les réponses 5xx, 408, 429 sont réessayés — autrement dit ce qui ressemble à une panne temporaire. Toute autre réponse 4xx est considérée comme une erreur permanente : pas de nouvelle tentative, l'essai compte immédiatement dans le compteur d'échecs.

Les webhooks se configurent dans la carte « Vitrine sur votre propre code » et sont disponibles sur les plans payants ; la lecture des données est disponible en permanence.

Par où commencer#

Ouvrez Marketing → « Mon site » → « Vitrine sur votre propre code » et copiez l'adresse du manifeste.
Chargez le manifeste, puis à partir de lui — les données du menu et du profil (ou installez le paquet @cenaly/storefront et passez-lui le slug de l'établissement). Aucune clé n'est nécessaire à cette étape.
Construisez les pages avec votre framework ; pour les commandes, utilisez l'API invité.
Ajoutez un webhook pour reconstruire le site au fil des changements — ou, s'il n'y a pas d'adresse publique pour recevoir les événements, lancez cenaly-storefront watch : il surveille lui-même publishId dans le manifeste et lance votre build.

La description technique complète se trouve via le lien « Documentation développeur » dans la même carte ; à côté, des liens vers un guide séparé sur le site statique et vers les schémas JSON. Un projet de démarrage Next.js est prêt à l'emploi, et toute la documentation est dupliquée sous forme de llms.txt pour les assistants AI du développeur — y compris un llms.txt personnel de votre établissement sur le CDN.

Sections liées#

Mon site — les widgets, si vous ne voulez pas réécrire tout le site
Guest API pour les agents IA — la même API invité
API et MCP de votre standard téléphonique — accès des agents IA et du CRM à la téléphonie
Boutique en ligne — ce qui arrive exactement dans les données du catalogue

Questions fréquentes#

Faut-il payer pour lire les données ? Non. Les JSON publics sont disponibles avec n'importe quel plan — ce sont les mêmes fichiers que ceux utilisés par notre vitrine. Les webhooks, eux, sont payants.

Et le SEO ? Il est entièrement de votre côté : vous assemblez les pages vous-même et gérez vous-même le balisage. Les données pour le micro-balisage (JSON-LD) figurent dans le contrat.

Peut-on le combiner avec sa propre vitrine ? Oui. Notre vitrine, les widgets et votre propre site fonctionnent avec les mêmes données et un seul panier de commandes.