Vitrine com código próprio (headless)

O caminho comum é a nossa vitrine ou os widgets no seu site. Mas se o site é feito pelo seu desenvolvedor ou agência e a interface deve ser totalmente sua, existe uma terceira opção: você pega de nós os dados e o recebimento de pedidos, e todo o frontend você mesmo faz, em qualquer stack.

A leitura de dados não exige chaves nem autorização: tudo o que é público na vitrine também é público em JSON.

Onde se configura: Marketing → "Meu site" → cartão "Vitrine com código próprio". Lá também estão o endereço do manifesto da sua unidade, os links para a documentação técnica e os esquemas JSON e a configuração dos webhooks. Não é preciso ativar nada: os dados são publicados sempre.

Manifesto storefront.json#

O único endereço que o desenvolvedor precisa conhecer:

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

No manifesto está todo o resto:

Bloco	O que contém
`location`	Identificador, slug, vertical (restaurante, loja, hotel, salão)
`languages`	Idioma padrão e lista de idiomas habilitados
`currency`	Código e símbolo da moeda
`cdnBase` + `data`	Caminhos para menu, perfil, páginas, coleções, avaliações e recomendações "comprados com este item"
`catalog`	Modo do catálogo: tudo em arquivos ou cards por arquivo e API de catálogo
`images`	Base de imagens, modelos de caminhos (foto do item e galerias, vídeo, categorias, coleções, capa e logotipo, favicon) e tamanhos disponíveis
`api`	Endereços da API de convidado, especificações OpenAPI, contorno comercial, endpoint MCP e WebSocket de status do pedido em tempo real
`publishId`, `publishedAt`	Identificador da publicação: muda a cada regeneração dos dados

O contrato é versionado (contractVersion), e ao lado ficam os esquemas JSON — com eles é prático validar os dados e gerar tipos. Campos desconhecidos devem ser ignorados: o contrato se expande sem quebrar a compatibilidade.

Dados e imagens#

Tudo o que a vitrine mostra está disponível em arquivos: menu e catálogo por idioma, perfil da unidade (nome, endereço, horário de funcionamento, contatos, configurações), páginas e artigos, coleções, avaliações.

Para catálogos grandes, o manifesto muda para o modo api: no arquivo de menu fica uma seleção simplificada, e os cards completos são obtidos por arquivo ou pela API de catálogo com filtros e subcategorias.

As imagens vêm do nosso CDN, em vários tamanhos conforme o modelo do manifesto; ao atualizar uma foto, o caminho é versionado, então o cache pode ser mantido "para sempre".

Não é obrigatório escrever todas essas requisições à mão: existe o pacote npm @cenaly/storefront — cliente tipado do contrato (manifesto, perfil, menu dos dois modos de catálogo, finalização de pedido), construtor de URL de imagens e hooks React. O pacote tem um ponto de entrada separado para builds estáticos (@cenaly/storefront/static: mapa de endereços do site, sitemap.xml, robots.txt, links de imagens) e o comando de console cenaly-storefront — um snapshot de todos os dados da unidade em uma pasta, a lista de endereços e o modo watch, que acompanha o manifesto e dispara seu build assim que o publishId muda. Ele também é a base do projeto inicial em Next.js, que pode ser clonado e simplesmente recolorido.

Pedidos e API de convidado#

Recebimento de pedidos, status do pedido, busca e reservas — pela API de convidado: sem autorização, o endereço vem do manifesto, a especificação é OpenAPI 3.1. Separadamente existe o contorno comercial: cupons, cálculo de entrega, formulários, assinaturas. Mais detalhes — Guest API para agentes de AI, a mesma interface.

O pedido criado pelo seu site entra na seção comum "Pedidos" e segue as regras habituais: status, cozinha, entregadores, recibos, notificações.

Webhooks sobre alterações#

Para não consultar o CDN repetidamente, assine os eventos:

menu.updated — menu ou catálogo regenerados;
profile.updated — o perfil da unidade mudou;
pages.updated — páginas e artigos mudaram.

No corpo do evento vem o publishId — com ele é prático reconstruir páginas estáticas ou limpar o cache ISR. Se você definiu um segredo, a requisição é assinada com HMAC-SHA256 e chega com o cabeçalho X-Meni-Signature — verifique a assinatura antes de reconstruir qualquer coisa; para o deploy hook do Vercel/Netlify o segredo pode não ser criado. Até cinco endereços por unidade, e após dez falhas seguidas a assinatura é desativada sozinha (na conta é possível ver a última entrega e o contador de erros; salvar as configurações novamente a reativa).

Qual endereço o servidor aceita. Apenas https://, sem login e senha na própria URL, e o host precisa ser público: endereços locais, internos e de serviço (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) são rejeitados ao salvar. Para depurar na sua máquina, suba um túnel com endereço https público.

Quando há repetição. Repetem-se timeouts e respostas 5xx, 408, 429 — ou seja, o que parece uma falha temporária. Qualquer outra resposta 4xx é considerada erro permanente: não haverá repetição, a tentativa vai direto para o contador de falhas.

Os webhooks são configurados no cartão "Vitrine com código próprio" e estão disponíveis nos planos pagos; a leitura de dados está disponível sempre.

Por onde começar#

Abra Marketing → "Meu site" → "Vitrine com código próprio" e copie o endereço do manifesto.
Carregue o manifesto e, a partir dele, os dados de menu e perfil (ou instale o pacote @cenaly/storefront e passe a ele o slug da unidade). Nenhuma chave é necessária nesta etapa.
Monte as páginas com seu framework; para pedidos, use a API de convidado.
Adicione um webhook para reconstruir o site conforme as alterações — ou, se não houver endereço público para receber eventos, rode cenaly-storefront watch: ele mesmo acompanha o publishId no manifesto e dispara seu build.

A descrição técnica completa está no link "Documentação do desenvolvedor" no mesmo cartão; ao lado há links para um guia separado sobre site estático e para os esquemas JSON. Existe um projeto inicial pronto em Next.js, e toda a documentação é duplicada como llms.txt para assistentes de IA do desenvolvedor — incluindo o llms.txt personalizado da sua unidade no CDN.

Seções relacionadas#

Meu site — widgets, caso não seja necessário reescrever o site inteiro
Guest API para agentes de AI — a mesma API de convidados
API e MCP da sua central telefônica — acesso de agentes de IA e CRM à telefonia
Loja online — o que exatamente chega nos dados do catálogo

Perguntas frequentes#

É preciso pagar para ler os dados? Não. Os JSON públicos estão disponíveis em qualquer plano — são os mesmos arquivos que a nossa vitrine usa. Os webhooks é que são pagos.

E o SEO? Ele fica totalmente do seu lado: você mesmo monta as páginas e mesmo gerencia a marcação. Os dados para microdados (JSON-LD) estão no contrato.

É possível combinar com a sua própria vitrine? Sim. A nossa vitrine, os widgets e o seu próprio site funcionam com os mesmos dados e um único carrinho de pedidos.