Pular para o conteúdo

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.

Abrir a 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-Remaining e X-RateLimit-Reset; ao passar, 429 com Retry-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çalho Allow.
  • 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_cursor da resposta como cursor para trazer a seguinte.
Uma chamada com a sua chave
curl https://menunode.com/api/v1/restaurant \
  -H "Authorization: Bearer pat_…"
Rotas de /api/v1
RotaMétodoO que fazPermissão
/restaurantGETO restaurante da chave. Funciona com qualquer permissão.—
/hoursGETHorários, dias especiais, horário de pedidos e regras de reserva de um local (branch_id).—
/menuGETO cardápio inteiro com o preço e a disponibilidade deste momento.menu:read
/items/{id}PATCHMudar o preço de um prato ou marcá-lo esgotado (sold_out_today, sold_out, available).menu:write
/ordersGETPedidos confirmados, do mais novo ao mais antigo, com filtros por data, status e pagamento.orders:read
/order-linksPOSTUm link para a página de pedido com o carrinho já montado: o cliente confirma e paga lá.menu:read
/reservationsGETReservas confirmadas em ordem de calendário.reservations:read
/reviewsGETAs respostas dos clientes a "Como foi?".reviews:read
/webhooksGET POSTListar e criar endereços de aviso.webhooks:write
/webhooks/{id}GET PATCH DELETEVer, mudar (avisos, local, pausa) ou apagar um endereço de aviso.webhooks:write
/webhooks/{id}/test · /rotate-secretPOSTMandar um aviso de teste ou trocar a chave de assinatura.webhooks:write
/webhooks/{id}/deliveries · …/resendGET POSTHistórico de envios e reenviar um.webhooks:write
/feeds/menu.json · /feeds/menu.csvGETO 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:write també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 (403 branch_token_not_allowed).
Permissões de uma chave
PermissãoO que faz
menu:readLer o cardápio, os horários e os arquivos de cardápio.
menu:writeO anterior e mudar preços e pratos esgotados.
orders:readLer pedidos e receber os avisos de pedidos e de contas de mesa.
reservations:readLer reservas e a lista de espera.
reviews:readLer avaliações (trazem nome e e-mail do cliente).
webhooks:writeCriar 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 (com avoid, os alérgenos que o cliente evita), quote_group, list_available_slots, check_availability.
  • Pedidos: prepare_order_link, create_order e confirm_order, get_order_status.
  • Reservas: create_reservation e confirm_reservation, get_reservation, change_reservation, cancel_reservation, create_availability_alert e confirm_availability_alert.
  • Lista de espera: get_waitlist_status, join_waitlist e confirm_waitlist, get_waitlist_position, leave_waitlist.
  • Perguntas: ask_restaurant (a resposta do restaurante é publicada em get_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_id ao criar ou mudar o endereço (null = todos os locais).
  • Assinatura (Standard Webhooks): os cabeçalhos webhook-id, webhook-timestamp e webhook-signature. A assinatura é v1, e o HMAC-SHA256 em base64 de id.timestamp.corpo, com a parte em base64 da sua chave whsec_… 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.
Verificar a assinatura de um aviso (Node.js)
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);
  });
}
Avisos que você pode receber
AvisoO que fazPermissão
order.createdPedido novoorders:read
order.status_changedMudança de status de um pedidoorders:read
reservation.createdReserva novareservations:read
reservation.updatedMudanças em uma reservareservations:read
waitlist.joinedAlguém entrou na lista de esperareservations:read
waitlist.updatedMudanças na lista de esperareservations:read
menu.updatedMudanças no cardápio (agrupadas por minuto)menu:read
item.sold_outPrato esgotadomenu:read
item.availablePrato disponível de novomenu:read
order.payment_changedPagamento de um pedido (avisado, recebido, devolvido)orders:read
hours.updatedHorário alteradomenu:read
review.receivedChegou uma avaliaçãoreviews:read
order.updatedPedido alterado (falta um prato ou ele saiu)orders:read
bill.issuedA conta de uma mesa foi feitaorders:read
bill.paidA conta de uma mesa foi pagaorders:read
bill.voidedA conta de uma mesa foi anuladaorders:read

Arquivos de cardápio e calendário

  • Públicos, sem chave: /m/<restaurante>/menu.json e /m/<restaurante>/menu.csv, com o mesmo que o cardápio mostra (lang para o idioma, branch para um local).
  • Com chave menu:read: /api/v1/feeds/menu.json e .csv, com os pratos ocultos e branch_id para um local. format=meta devolve 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 ETag e 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.