Escaparate con su propio código (headless)

La vía habitual es nuestro escaparate o los widgets en su sitio web. Pero si el sitio lo desarrolla su programador o agencia y la maquetación debe ser totalmente propia, existe una tercera opción: usted toma de nosotros los datos y la recepción de pedidos, y todo el frontend lo hace usted mismo, con cualquier stack.

La lectura de datos no requiere claves ni autorización: todo lo que es público en el escaparate es público también en JSON.

Dónde se configura: Marketing → «Mi sitio» → tarjeta «Escaparate con su propio código». Ahí mismo están la dirección del manifiesto de su local, los enlaces a la documentación técnica y a los esquemas JSON, y la configuración de webhooks. No hay que activar nada: los datos se publican siempre.

Manifiesto storefront.json#

La única dirección que el desarrollador necesita conocer:

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

En el manifiesto está todo lo demás:

Bloque	Qué contiene
`location`	Identificador, slug, vertical (restaurante, tienda, hotel, salón)
`languages`	Idioma por defecto y lista de idiomas activados
`currency`	Código y símbolo de la moneda
`cdnBase` + `data`	Rutas al menú, perfil, páginas, colecciones, reseñas y recomendaciones «se compra con esto»
`catalog`	Modo de catálogo: todo en archivos o fichas por archivo y API de catálogo
`images`	Base de imágenes, plantillas de rutas (foto del artículo y galerías, vídeo, categorías, colecciones, portada y logotipo, favicon) y tamaños disponibles
`api`	Direcciones de la API de invitados, especificaciones OpenAPI, contorno comercial, endpoint MCP y WebSocket de estados del pedido en vivo
`publishId`, `publishedAt`	Identificador de publicación: cambia con cada regeneración de los datos

El contrato está versionado (contractVersion) y junto a él están los esquemas JSON: con ellos es cómodo validar los datos y generar tipos. Los campos desconocidos deben ignorarse: el contrato se amplía sin romper la compatibilidad.

Datos e imágenes#

Todo lo que muestra el escaparate está disponible en archivos: menú y catálogo por idiomas, perfil del local (nombre, dirección, horario, contactos, ajustes), páginas y artículos, colecciones, reseñas.

Para catálogos grandes, el manifiesto cambia al modo api: en el archivo del menú hay una selección ligera, y las fichas completas se toman por archivo o mediante la API de catálogo con filtros y subcategorías.

Las imágenes proceden de nuestro CDN, en varios tamaños según la plantilla del manifiesto; al actualizar una foto, la ruta se versiona, por lo que la caché puede mantenerse «para siempre».

No es obligatorio escribir todas estas consultas a mano: existe el paquete npm @cenaly/storefront — un cliente tipado del contrato (manifiesto, perfil, menú de ambos modos de catálogo, formalización del pedido), un generador de URL de imágenes y hooks de React. El paquete tiene un punto de entrada aparte para compilaciones estáticas (@cenaly/storefront/static: mapa de direcciones del sitio, sitemap.xml, robots.txt, enlaces a imágenes) y un comando de consola cenaly-storefront — una instantánea de todos los datos del local en una carpeta, la lista de direcciones y el modo watch, que vigila el manifiesto y lanza su compilación en cuanto cambia publishId. También es la base del proyecto de inicio en Next.js, que puede clonar y simplemente recolorear.

Pedidos y API de invitados#

La recepción de pedidos, el estado del pedido, la búsqueda y las reservas se realizan a través de la API de invitados: sin autorización, la dirección se toma del manifiesto, la especificación es OpenAPI 3.1. Aparte existe el contorno comercial: cupones, cálculo de envío, formularios, suscripciones. Más detalles en Guest API para agentes de IA, la misma interfaz.

El pedido creado por su sitio llega a la sección común «Pedidos» y vive según las reglas habituales: estados, cocina, repartidores, recibos, notificaciones.

Webhooks sobre cambios#

Para no sondear el CDN, suscríbase a los eventos:

menu.updated — el menú o el catálogo se han regenerado;
profile.updated — ha cambiado el perfil del local;
pages.updated — han cambiado las páginas y los artículos.

En el cuerpo del evento llega publishId: con él es cómodo recompilar las páginas estáticas o restablecer la caché ISR. Si ha definido un secreto, la solicitud se firma con HMAC-SHA256 y llega con la cabecera X-Meni-Signature: verifique la firma antes de recompilar nada; para el hook de despliegue de Vercel/Netlify no es necesario crear un secreto. Hasta cinco direcciones por local, y tras diez fallos consecutivos la suscripción se desactiva sola (en la cuenta se ve la última entrega y el contador de errores; volver a guardar los ajustes la reactiva).

Qué dirección aceptará el servidor. Solo https://, sin usuario ni contraseña en la propia URL, y el host debe ser público: las direcciones locales, internas y de servicio (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) se rechazan al guardar. Para depurar en su propia máquina, levante un túnel con una dirección https pública.

Cuándo hay reintento. Se reintentan los tiempos de espera agotados y las respuestas 5xx, 408, 429, es decir, lo que parece un fallo temporal. Cualquier otra respuesta 4xx se considera un error permanente: no habrá reintento, el intento va directamente al contador de fallos.

Los webhooks se configuran en la tarjeta «Escaparate con su propio código» y están disponibles en los planes de pago; la lectura de datos está disponible siempre.

Por dónde empezar#

Abra Marketing → «Mi sitio» → «Escaparate con su propio código» y copie la dirección del manifiesto.
Cargue el manifiesto y, a partir de él, los datos del menú y del perfil (o instale el paquete @cenaly/storefront y pásele el slug del local). En este paso no se necesita ninguna clave.
Monte las páginas con su framework; para los pedidos use la API de invitados.
Añada un webhook para recompilar el sitio cuando haya cambios o, si no dispone de una dirección pública para recibir eventos, ejecute cenaly-storefront watch: él mismo vigila el publishId del manifiesto y lanza su compilación.

La descripción técnica completa está en el enlace «Documentación para desarrolladores» de esa misma tarjeta; junto a él hay enlaces a una guía aparte sobre el sitio estático y a los esquemas JSON. Hay un proyecto de inicio listo en Next.js, y toda la documentación se duplica en forma de llms.txt para los asistentes de IA del desarrollador, incluido el llms.txt personal de su local en el CDN.

Secciones relacionadas#

Mi sitio web — widgets, si no necesita reescribir el sitio web por completo
Guest API para agentes de AI — la misma API de invitados
API y MCP de su centralita — acceso de agentes de IA y CRM a la telefonía
Tienda en línea — qué llega exactamente en los datos del catálogo

Preguntas frecuentes#

¿Hay que pagar por leer los datos? No. Los JSON públicos están disponibles en cualquier plan: son los mismos archivos que utiliza nuestra vitrina. Lo que es de pago son los webhooks.

¿Y el SEO? Está completamente de su lado: usted arma las páginas por su cuenta y gestiona el marcado por su cuenta. Los datos para el microdatos (JSON-LD) están en el contrato.

¿Se puede combinar con su propia vitrina? Sí. Nuestra vitrina, los widgets y su propio sitio web funcionan con los mismos datos y un mismo carrito de pedidos.