MenuNode para desenvolvedores
Conecte o caixa, o estoque, o delivery ou uma automação a um restaurante no MenuNode. Tudo o que segue funciona hoje e está descrito na especificação OpenAPI.
A API (/api/v1)
Uma API REST para um restaurante: ler o cardápio, os pedidos, as reservas e as avaliações, e mudar preços ou pratos esgotados. O endereço base é https://menunode.com/api/v1.
- Cada chamada leva
Authorization: Bearer <chave>. Os cookies do painel nunca servem para esta API. - Limite: 120 chamadas por minuto por chave. Cada resposta traz
X-RateLimit-Limit,X-RateLimit-RemainingeX-RateLimit-Reset; ao passar, 429 comRetry-After. - Os erros sempre são
{"error": {"code": "...", "message": "..."}}. Um id de outro restaurante responde 404, igual a um que não existe. Um método que a rota não aceita responde 405 com o cabeçalhoAllow. - Os valores são texto com duas casas decimais (
"12.50") na moeda do restaurante. - As listas vêm em páginas: mande o
next_cursorda resposta comocursorpara trazer a seguinte.
curl https://menunode.com/api/v1/restaurant \
-H "Authorization: Bearer pat_…"| Rota | Método | O que faz | Permissão |
|---|---|---|---|
/restaurant | GET | O restaurante da chave. Funciona com qualquer permissão. | — |
/hours | GET | Horários, dias especiais, horário de pedidos e regras de reserva de um local (branch_id). | — |
/menu | GET | O cardápio inteiro com o preço e a disponibilidade deste momento. | menu:read |
/items/{id} | PATCH | Mudar o preço de um prato ou marcá-lo esgotado (sold_out_today, sold_out, available). | menu:write |
/orders | GET | Pedidos confirmados, do mais novo ao mais antigo, com filtros por data, status e pagamento. | orders:read |
/order-links | POST | Um link para a página de pedido com o carrinho já montado: o cliente confirma e paga lá. | menu:read |
/reservations | GET | Reservas confirmadas em ordem de calendário. | reservations:read |
/reviews | GET | As respostas dos clientes a "Como foi?". | reviews:read |
/webhooks | GET POST | Listar e criar endereços de aviso. | webhooks:write |
/webhooks/{id} | GET PATCH DELETE | Ver, mudar (avisos, local, pausa) ou apagar um endereço de aviso. | webhooks:write |
/webhooks/{id}/test · /rotate-secret | POST | Mandar um aviso de teste ou trocar a chave de assinatura. | webhooks:write |
/webhooks/{id}/deliveries · …/resend | GET POST | Histórico de envios e reenviar um. | webhooks:write |
/feeds/menu.json · /feeds/menu.csv | GET | O cardápio em colunas fixas, JSON ou CSV, com os pratos ocultos. | menu:read |
Como obter uma chave
O dono a cria no painel, em Configurações → Integrações → API para integrações: um nome e as permissões. A chave começa com pat_ e aparece uma vez só; o MenuNode guarda apenas a sua impressão, então se ela se perder, cria-se outra e apaga-se a antiga.
- Uma chave é de um restaurante. Nenhum parâmetro a aponta para outro.
- Uma permissão de escrita inclui a de leitura (
menu:writetambém lê o cardápio). - Uma chave de um único local vê só os pedidos e reservas desse local. Não pode mudar o preço nem o esgotado do cardápio inteiro (403
branch_scoped) nem gerenciar avisos (403branch_token_not_allowed).
| Permissão | O que faz |
|---|---|
menu:read | Ler o cardápio, os horários e os arquivos de cardápio. |
menu:write | O anterior e mudar preços e pratos esgotados. |
orders:read | Ler pedidos e receber os avisos de pedidos e de contas de mesa. |
reservations:read | Ler reservas e a lista de espera. |
reviews:read | Ler avaliações (trazem nome e e-mail do cliente). |
webhooks:write | Criar e gerenciar endereços de aviso. |
Servidores MCP para assistentes de IA
MCP é o protocolo com que um assistente de IA (Claude, ChatGPT e outros) usa ferramentas. O MenuNode tem dois servidores.
O público, em https://menunode.com/mcp, não pede chave. Serve para buscar restaurantes, ler o cardápio e as informações, perguntar algo que o cardápio não responde, ver horários livres e, onde o restaurante ativou, pedir, reservar ou entrar na lista de espera. Pedidos, reservas e lista de espera sempre se confirmam com um código de 6 números que chega por e-mail ao cliente.
- Leitura:
search_restaurants,get_restaurant_info,get_menu,get_menu_structured(comavoid, os alérgenos que o cliente evita),quote_group,list_available_slots,check_availability. - Pedidos:
prepare_order_link,create_ordereconfirm_order,get_order_status. - Reservas:
create_reservationeconfirm_reservation,get_reservation,change_reservation,cancel_reservation,create_availability_alerteconfirm_availability_alert. - Lista de espera:
get_waitlist_status,join_waitlisteconfirm_waitlist,get_waitlist_position,leave_waitlist. - Perguntas:
ask_restaurant(a resposta do restaurante é publicada emget_restaurant_info).
O do dono, em https://menunode.com/mcp/owner, pede uma chave (Authorization: Bearer pat_…). Com menu:write o assistente monta e edita o cardápio: seções, pratos, preços por horário, esgotados, traduções, importar um cardápio a partir de texto (import_menu_from_raw_text) ou carregá-lo inteiro (bulk_upsert_menu). Outras ferramentas pedem a sua própria permissão: pedidos e reservas (orders:read, orders:status, reservations:read, reservations:status), avaliações, clientes (customers:read), lista de espera, pausa de pedidos, dias especiais e números do cardápio. No painel, Configurações → Integrações → Ensine sua IA a usar seu restaurante monta a chave e os passos para conectá-la.
Avisos para o seu sistema (webhooks)
O MenuNode manda um POST para um endereço https seu toda vez que algo acontece. Cadastre-o no painel (Configurações → Integrações) ou com POST /webhooks. Até 10 endereços por restaurante; cada um escolhe seus avisos e, se o restaurante tem vários locais, um só: então recebe os pedidos, reservas, lista de espera, contas, horários, avaliações e esgotados desse local, e as mudanças do cardápio inteiro.
O corpo é {id, type, api_version, timestamp, restaurant_id, data}. Uma chave só pode assinar os avisos que poderia ler com suas permissões.
- Para ligar um endereço a um local: escolha-o em "Qual local" no painel, ou mande
branch_idao criar ou mudar o endereço (null= todos os locais). - Assinatura (Standard Webhooks): os cabeçalhos
webhook-id,webhook-timestampewebhook-signature. A assinatura év1,e o HMAC-SHA256 em base64 deid.timestamp.corpo, com a parte em base64 da sua chavewhsec_…como chave. Rejeite horários com mais de 5 minutos de diferença. - Responda com um 2XX em menos de 10 segundos. Se não, tenta-se de novo 5 vezes (1 min, 5 min, 30 min, 2 h e 12 h) com o mesmo
webhook-id: use-o para não processar duas vezes a mesma coisa. Redirecionamentos não são seguidos. - Um endereço que responde 410, ou que falha sem parar por mais de um dia, se desliga sozinho e o dono recebe um e-mail.
menu.updatedé agrupado: muitas mudanças seguidas mandam um só, mais ou menos um minuto depois da última (no máximo 5 minutos depois da primeira).hours.updatedé agrupado por local por uns 10 segundos.- Pelo painel ou pela API você pode mandar um aviso de teste, ver os últimos envios e reenviar um. A chave de assinatura aparece uma vez só; se se perder, troque-a por outra.
const { createHmac, timingSafeEqual } = require('node:crypto');
// headers: the request headers; rawBody: the body exactly as received (before JSON.parse).
function verify(secret, headers, rawBody) {
const id = headers['webhook-id'];
const ts = headers['webhook-timestamp'];
if (Math.abs(Date.now() / 1000 - Number(ts)) > 300) return false;
const key = Buffer.from(secret.slice('whsec_'.length), 'base64');
const expected = createHmac('sha256', key).update(id + '.' + ts + '.' + rawBody).digest();
return headers['webhook-signature'].split(' ').some((part) => {
const given = Buffer.from(part.split(',')[1] ?? '', 'base64');
return part.startsWith('v1,') && given.length === expected.length && timingSafeEqual(given, expected);
});
}| Aviso | O que faz | Permissão |
|---|---|---|
order.created | Pedido novo | orders:read |
order.status_changed | Mudança de status de um pedido | orders:read |
reservation.created | Reserva nova | reservations:read |
reservation.updated | Mudanças em uma reserva | reservations:read |
waitlist.joined | Alguém entrou na lista de espera | reservations:read |
waitlist.updated | Mudanças na lista de espera | reservations:read |
menu.updated | Mudanças no cardápio (agrupadas por minuto) | menu:read |
item.sold_out | Prato esgotado | menu:read |
item.available | Prato disponível de novo | menu:read |
order.payment_changed | Pagamento de um pedido (avisado, recebido, devolvido) | orders:read |
hours.updated | Horário alterado | menu:read |
review.received | Chegou uma avaliação | reviews:read |
order.updated | Pedido alterado (falta um prato ou ele saiu) | orders:read |
bill.issued | A conta de uma mesa foi feita | orders:read |
bill.paid | A conta de uma mesa foi paga | orders:read |
bill.voided | A conta de uma mesa foi anulada | orders:read |
Arquivos de cardápio e calendário
- Públicos, sem chave:
/m/<restaurante>/menu.jsone/m/<restaurante>/menu.csv, com o mesmo que o cardápio mostra (langpara o idioma,branchpara um local). - Com chave
menu:read:/api/v1/feeds/menu.jsone.csv, com os pratos ocultos ebranch_idpara um local.format=metadevolve o formato do catálogo da Meta (WhatsApp e Instagram). - Um calendário de reservas (.ics) com endereço secreto, que o dono cria e anula no painel.
- Os arquivos respondem
ETage 304 quando nada mudou.
Receitas para n8n e Make
Para automatizar sem programar. No painel, Configurações → Integrações, cada receita baixa um modelo para n8n ou para Make e o conecta a um aviso:
- Cada pedido novo para uma planilha do Google (
order.created). - Cada reserva nova para um grupo do Telegram (
reservation.created). - Cada pedido novo por e-mail para outra pessoa (
order.created). - Cada pagamento de um pedido para uma planilha do Google (
order.payment_changed). - Cada mudança de horário por e-mail para quem atualiza suas outras páginas (
hours.updated).
Os modelos do n8n saem com um endereço próprio para cada download.
Falta alguma coisa?
Se uma integração precisa de um dado ou de uma rota que não existe, escreva para nós pelo contato ou em support@menunode.com.