Guest API para AI-agentes

API público do cenaly.com, pelo qual assistentes e agentes de AI atuam em nome do convidado: leem o menu do restaurante, pesquisam no catálogo, montam o carrinho, fazem o pedido e reservam uma mesa. Para tudo isso não é necessária autorização — são as mesmas operações disponíveis ao convidado no site do menu.

Endereçamento do restaurante#

O restaurante é endereçado pelo código da Unidade — é o segmento da URL do menu em letras maiúsculas. Se o menu abre em cenaly.com/MYCAFE, o código é MYCAFE. O mesmo código está embutido nos códigos QR das mesas.

Início rápido (REST)#

# O que a API faz
curl https://api.cenaly.com/llm/v1

# Menu do restaurante em russo
curl "https://api.cenaly.com/llm/v1/locations/MYCAFE/menu?lang=ru"

# Fazer um Pedido para retirada
curl -X POST https://api.cenaly.com/llm/v1/locations/MYCAFE/orders \
  -H 'Content-Type: application/json' \
  -d '{
    "items": [{"itemId": "abc123", "quantity": 2}],
    "orderType": "pickup",
    "customer": {"name": "Гость", "phone": "+995555123456"},
    "language": "ru"
  }'
# → {"accepted": true, "orderId": "…", "total": 24, "statusUrl": "…"}

# Status do Pedido (orderId — token secreto de acesso)
curl https://api.cenaly.com/llm/v1/locations/MYCAFE/orders/{orderId}

Especificação completa: OpenAPI 3.1 · documentação interativa (no idioma da marca; ?lang=en|ka|ru|tr|sq).

Endpoints#

Carrinho: montar o Pedido passo a passo#

O agente não precisa adivinhar a composição do Pedido de uma só vez — é possível manter o carrinho no servidor, como uma pessoa faz no carrinho web:

1. POST /carts com as primeiras linhas → cartId
2. PATCH /carts/{cartId} — adicionar, alterar a quantidade, remover (quantity: 0)
3. POST /orders com cartId — fazer o Pedido

Os preços no carrinho são sempre recalculados conforme o menu ao vivo, então ele não pode exibir um valor desatualizado. O carrinho dura 7 dias. Em cada resposta há um checkoutUrl — o link pode simplesmente ser entregue à pessoa para que ela conclua o Pedido no checkout comum.

Ao criar o Pedido, é possível passar uma idempotencyKey (8–64 caracteres): a repetição com a mesma chave em até 48 horas retorna o Pedido original, em vez de criar um segundo. O mesmo vale para as Reservas — a repetição na mesma janela retorna a Reserva original, em vez de ocupar uma segunda mesa.

Conexão via MCP#

Servidor: https://api.cenaly.com/llm/mcp — Model Context Protocol, streamable HTTP, stateless. As ferramentas de convidado funcionam sem autorização; o login via OAuth acrescenta a elas as ferramentas da sua Conta.

Configuração para Claude Desktop / Claude Code e clientes compatíveis:

{
  "mcpServers": {
    "meni-guest": {
      "type": "http",
      "url": "https://api.cenaly.com/llm/mcp"
    }
  }
}

Ferramentas de convidado (13, sem autorização):

Cenários típicos:

• Pedido rápido: get_menu → create_order → get_order_status (o Número de 4 dígitos aparece em alguns segundos).
• Pedido em diálogo: search_products → update_cart (um Item por vez, como numa conversa) → get_cart → create_order, ou entregar ao convidado o checkoutUrl e deixá-lo concluir o Pedido sozinho.
• Pergunta sobre o estabelecimento: get_store_info (endereço, horário, contatos) ou search_policies_and_faqs (condições de entrega, devolução, regras).
• Reserva de mesa: check_table_availability (mesas do mapa do salão, livre/ocupada no horário escolhido) → create_reservation com tableId → get_reservation_status (o restaurante confirma a solicitação) → se necessário, cancel_reservation.

Acesso aos seus dados#

Se você é proprietário do estabelecimento ou funcionário, às mesmas 13 ferramentas de convidado somam-se 12 ferramentas de trabalho com a sua conta — em dois grupos.

Dados da conta (6): resolve_domain, list_files, read_file, write_file, delete_file, write_signal. Elas abrem não só o menu e os pedidos, mas também o CRM, o estoque, a equipe, as configurações do caixa e da tela de cozinha, os documentos e quase todas as demais seções.

Site do cliente da unidade (6): get_site_settings, update_site_settings, list_site_templates, apply_site_template, check_domain_availability, rename_site_domain.

O login é o OAuth 2.1 comum sob a sua conta cenaly.com: o cliente MCP (Claude, ChatGPT, CLI) se registra sozinho e abre a janela de login. Não é preciso colar nada manualmente.

• Metadados do recurso: https://api.cenaly.com/.well-known/oauth-protected-resource
• Metadados do servidor de autorização: https://api.cenaly.com/.well-known/oauth-authorization-server
• Registro dinâmico de cliente (RFC 7591): POST https://api.cenaly.com/llm/oauth/register

Enquanto não houver token, tools/list mostra apenas as ferramentas de convidado — as autorizadas simplesmente não aparecem.

Regras e garantias#

• O pedido é validado com base no menu ao vivo: prato, variante ou adicional inexistente gera erro 400 com a lista de problemas; os preços e o total são calculados pelo servidor, o agente não tem como "definir" um preço.
• Para retirada no local e entrega, o nome e o telefone do convidado são obrigatórios; para entrega, também o endereço.
• orderId / reservationId são tokens secretos: por eles se verifica o status e se cancela a reserva. Não os publique.
• Pedidos e reservas chegam ao restaurante em tempo real — no painel administrativo, na tela de cozinha e nas notificações, como pedidos comuns do site.
• As reservas do convidado têm status pending até que o restaurante as confirme no painel administrativo.
• Na Rússia, não é possível pedir álcool pelo canal de agente. A venda remota de produtos alcoólicos é proibida por lei (pp. 14 p. 2 st. 16 171-ФЗ), portanto, em unidades com o país "Rússia", o pedido com um item alcoólico não passa na validação: na resposta 400 vem uma linha com o nome desse item e a explicação de que ele só pode ser pedido com o garçom no salão. O pedido precisa ser refeito sem álcool.

Descoberta legível por máquina#

• https://cenaly.com/llms.txt — mapa resumido da API para LLMs;
• GET https://api.cenaly.com/llm/v1 — documento de discovery: lista completa de endpoints, exemplos de pedido, reserva e trabalho com o carrinho, links para os metadados do OAuth.