Saltar al contenido

MenuNode para desarrolladores

Conecta la caja, el stock, el delivery o una automatización con un restaurante en MenuNode. Todo lo que sigue funciona hoy y lo describe la especificación OpenAPI.

Abrir la especificación OpenAPI

La API (/api/v1)

Una API REST para un restaurante: leer la carta, los pedidos, las reservas y las opiniones, y cambiar precios o platos agotados. La dirección base es https://menunode.com/api/v1.

  • Cada llamada lleva Authorization: Bearer <clave>. Las cookies del panel nunca sirven para esta API.
  • Límite: 120 llamadas por minuto por clave. Cada respuesta trae X-RateLimit-Limit, X-RateLimit-Remaining y X-RateLimit-Reset; al pasarte, 429 con Retry-After.
  • Los errores siempre son {"error": {"code": "...", "message": "..."}}. Un id de otro restaurante responde 404, igual que uno que no existe. Un método que la ruta no acepta responde 405 con el encabezado Allow.
  • Los montos son texto con dos decimales ("12.50") en la moneda del restaurante.
  • Las listas van por páginas: manda el next_cursor de la respuesta como cursor para traer la siguiente.
Una llamada con tu clave
curl https://menunode.com/api/v1/restaurant \
  -H "Authorization: Bearer pat_…"
Rutas de /api/v1
RutaMétodoQué hacePermiso
/restaurantGETEl restaurante de la clave. Sirve con cualquier permiso.—
/hoursGETHorarios, días especiales, horario de pedidos y reglas de reserva de un local (branch_id).—
/menuGETLa carta entera con el precio y la disponibilidad de este momento.menu:read
/items/{id}PATCHCambiar el precio de un plato o marcarlo agotado (sold_out_today, sold_out, available).menu:write
/ordersGETPedidos confirmados, del más nuevo al más viejo, con filtros por fecha, estado y pago.orders:read
/order-linksPOSTUn link a la página de pedido con el carrito ya cargado: el comensal confirma y paga ahí.menu:read
/reservationsGETReservas confirmadas en orden de calendario.reservations:read
/reviewsGETLas respuestas de los clientes a "¿Cómo te fue?".reviews:read
/webhooksGET POSTListar y crear direcciones de aviso.webhooks:write
/webhooks/{id}GET PATCH DELETEVer, cambiar (eventos, local, pausa) o borrar una dirección de aviso.webhooks:write
/webhooks/{id}/test · /rotate-secretPOSTMandar un aviso de prueba o cambiar la clave de firma.webhooks:write
/webhooks/{id}/deliveries · …/resendGET POSTHistorial de envíos y reenviar uno.webhooks:write
/feeds/menu.json · /feeds/menu.csvGETLa carta en columnas fijas, JSON o CSV, con los platos ocultos.menu:read

Cómo sacar una clave

El dueño la crea en el panel, en Configuración → Integraciones → API para integraciones: le pone un nombre y elige los permisos. La clave empieza con pat_ y se muestra una sola vez; MenuNode guarda solo su huella, así que si se pierde se crea otra y se borra la vieja.

  • Una clave es de un restaurante. Ningún parámetro la apunta a otro.
  • Un permiso de escritura incluye el de lectura (menu:write también lee la carta).
  • Una clave de un solo local ve solo los pedidos y reservas de ese local. No puede cambiar el precio ni el agotado de toda la carta (403 branch_scoped) ni manejar avisos (403 branch_token_not_allowed).
Permisos de una clave
PermisoQué hace
menu:readLeer la carta, los horarios y los archivos de carta.
menu:writeLo anterior y cambiar precios y platos agotados.
orders:readLeer pedidos y recibir los avisos de pedidos y de cuentas de mesa.
reservations:readLeer reservas y la lista de espera.
reviews:readLeer opiniones (llevan nombre y mail del cliente).
webhooks:writeCrear y manejar direcciones de aviso.

Servidores MCP para asistentes de IA

MCP es el protocolo con el que un asistente de IA (Claude, ChatGPT y otros) usa herramientas. MenuNode tiene dos servidores.

El público, en https://menunode.com/mcp, no pide clave. Sirve para buscar restaurantes, leer su carta e información, preguntar algo que la carta no responde, ver horarios libres y, donde el restaurante lo activó, pedir, reservar o anotarse en la lista de espera. Pedidos, reservas y lista de espera siempre se confirman con un código de 6 números que le llega por mail al comensal.

  • Lectura: search_restaurants, get_restaurant_info, get_menu, get_menu_structured (con avoid, los alérgenos que el comensal evita), quote_group, list_available_slots, check_availability.
  • Pedidos: prepare_order_link, create_order y confirm_order, get_order_status.
  • Reservas: create_reservation y confirm_reservation, get_reservation, change_reservation, cancel_reservation, create_availability_alert y confirm_availability_alert.
  • Lista de espera: get_waitlist_status, join_waitlist y confirm_waitlist, get_waitlist_position, leave_waitlist.
  • Preguntas: ask_restaurant (la respuesta del restaurante se publica en get_restaurant_info).

El del dueño, en https://menunode.com/mcp/owner, pide una clave (Authorization: Bearer pat_…). Con menu:write el asistente arma y edita la carta: secciones, platos, precios por horario, agotados, traducciones, importar una carta desde texto (import_menu_from_raw_text) o cargarla entera (bulk_upsert_menu). Otras herramientas piden su propio permiso: pedidos y reservas (orders:read, orders:status, reservations:read, reservations:status), opiniones, clientes (customers:read), lista de espera, pausa de pedidos, días especiales y números de la carta. En el panel, Configuración → Integraciones → Enseñale a tu IA a usar tu restaurante arma la clave y los pasos para conectarla.

Avisos a tu sistema (webhooks)

MenuNode manda un POST a una dirección https tuya cada vez que pasa algo. Se registra desde el panel (Configuración → Integraciones) o con POST /webhooks. Hasta 10 direcciones por restaurante; cada una elige sus avisos y, si el restaurante tiene varios locales, uno solo: entonces le llegan los pedidos, reservas, lista de espera, cuentas, horarios, opiniones y agotados de ese local, y los cambios de toda la carta.

El cuerpo es {id, type, api_version, timestamp, restaurant_id, data}. Una clave solo puede suscribirse a los avisos que podría leer con sus permisos.

  • Para atar una dirección a un local: elígelo en "Qué local" del panel, o manda branch_id al crear o cambiar la dirección (null = todos los locales).
  • Firma (Standard Webhooks): los encabezados webhook-id, webhook-timestamp y webhook-signature. La firma es v1, y el HMAC-SHA256 en base64 de id.timestamp.cuerpo, con la parte en base64 de tu clave whsec_… como llave. Rechaza horas con más de 5 minutos de diferencia.
  • Responde con un 2XX en menos de 10 segundos. Si no, se reintenta 5 veces (1 min, 5 min, 30 min, 2 h y 12 h) con el mismo webhook-id: úsalo para no procesar dos veces lo mismo. Las redirecciones no se siguen.
  • Una dirección que responde 410, o que falla sin parar por más de un día, se apaga sola y el dueño recibe un mail.
  • menu.updated se junta: muchos cambios seguidos mandan uno, más o menos un minuto después del último (a lo sumo 5 minutos después del primero). hours.updated se junta por local unos 10 segundos.
  • Desde el panel o la API puedes mandar un aviso de prueba, ver los últimos envíos y reenviar uno. La clave de firma se muestra una sola vez; si se pierde, se cambia por otra.
Comprobar la firma de un 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 puedes recibir
AvisoQué hacePermiso
order.createdPedido nuevoorders:read
order.status_changedCambio de estado de un pedidoorders:read
reservation.createdReserva nuevareservations:read
reservation.updatedCambios en una reservareservations:read
waitlist.joinedAlguien se anotó en la lista de esperareservations:read
waitlist.updatedCambios en la lista de esperareservations:read
menu.updatedCambios en el menú (agrupados por minuto)menu:read
item.sold_outPlato agotadomenu:read
item.availablePlato disponible otra vezmenu:read
order.payment_changedPago de un pedido (avisado, recibido, devuelto)orders:read
hours.updatedCambió el horariomenu:read
review.receivedLlegó una opiniónreviews:read
order.updatedPedido cambiado (falta un plato o se sacó)orders:read
bill.issuedSe hizo la cuenta de una mesaorders:read
bill.paidSe pagó la cuenta de una mesaorders:read
bill.voidedSe anuló la cuenta de una mesaorders:read

Archivos de carta y calendario

  • Públicos, sin clave: /m/<restaurante>/menu.json y /m/<restaurante>/menu.csv, con lo mismo que muestra la carta (lang para el idioma, branch para un local).
  • Con clave menu:read: /api/v1/feeds/menu.json y .csv, con los platos ocultos y branch_id para un local. format=meta devuelve el formato del catálogo de Meta (WhatsApp e Instagram).
  • Un calendario de reservas (.ics) con dirección secreta, que el dueño crea y anula en el panel.
  • Los archivos responden ETag y 304 cuando nada cambió.

Recetas para n8n y Make

Para automatizar sin programar. En el panel, Configuración → Integraciones, cada receta baja una plantilla para n8n o para Make y la conecta a un aviso:

  • Cada pedido nuevo a una planilla de Google (order.created).
  • Cada reserva nueva a un grupo de Telegram (reservation.created).
  • Cada pedido nuevo por mail a otra persona (order.created).
  • Cada pago de un pedido a una planilla de Google (order.payment_changed).
  • Cada cambio de horario por mail a quien actualiza tus otras páginas (hours.updated).

Las plantillas de n8n salen con una dirección propia para cada descarga.

¿Te falta algo?

Si una integración necesita un dato o una ruta que no está, escríbenos desde contacto o a support@menunode.com.