Documentación para desarrolladores

Primeros pasos

Crea un token de API desde tu panel en Tokens de API y webhooks. Elige las read y/o write capacidades y copia el token — solo se muestra una vez.

Una comprobación rápida de que tu token funciona:

curl https://www.menubarcode.com/api/v1/restaurants \
  -H "Authorization: Bearer YOUR_TOKEN"

Autenticación

Envía tu token como cabecera Bearer en cada petición:

Authorization: Bearer YOUR_TOKEN

Para pruebas rápidas puedes pasar en su lugar ?api_token=YOUR_TOKEN como parámetro de consulta, pero se recomienda encarecidamente usar la cabecera para que los tokens nunca se filtren en los registros.

Tokens con ámbito

Más allá del genérico read/write, un token puede limitarse a recursos específicos con resource:action capacidades. Recursos: restaurants, menu, orders, customers, analytics, drivers, webhooks; Acciones read, write. Selecciónalos al crear el token en el panel.

Reglas de cobertura: * otorga todo; un :write ámbito también otorga su :read; genérico read/write se comportan como *:read / *:write. Una petición que carezca del ámbito requerido devuelve 403. Heredado read/write los tokens no se ven afectados.

Los tokens se cifran en reposo (SHA-256) y pueden llevar una caducidad opcional. Revoca cualquier token al instante desde el panel.

Límites de frecuencia

La API permite 120 peticiones por minuto por token. Superarlo devuelve 429 Too Many Requests con una Retry-After cabecera. Se incluyen cabeceras estándar de límite de tasa en cada respuesta:

X-RateLimit-Limit: 120
X-RateLimit-Remaining: 118

Errores

Cada error en una /api/v1 ruta devuelve códigos de estado HTTP convencionales y un único envoltorio JSON — un mensaje legible para humanos message, un valor estable legible por máquina code, y (en la validación) un desglose por campo errors Mapa

{ "message": "Invalid or expired token.", "code": "unauthenticated" }

{ "message": "The given data was invalid.",
  "code": "validation_failed",
  "errors": { "title": ["The title field is required."] } }

Paginación

Los endpoints de lista devuelven envoltorios paginados al estilo de Laravel. Usa el ?page= parámetro de consulta para recorrer las páginas.

{
  "data": [ ... ],
  "current_page": 1,
  "last_page": 3,
  "per_page": 20,
  "total": 47
}

Leer restaurantes y menú

Lista los restaurantes del token, paginados (20 por página).

{
  "data": [
    { "id": 12, "title": "Nova Bistro", "slug": "nova-bistro",
      "url": "https://.../nova-bistro", "template": "linen",
      "created_at": "2026-06-01T10:22:00+00:00" }
  ],
  "current_page": 1, "last_page": 1, "total": 1
}

Un solo restaurante con sus categorías de menú y el número de artículos.

El menú activo completo agrupado por categoría.

[
  { "id": 3, "name": "Starters",
    "items": [
      { "id": 88, "name": "Bruschetta", "price": 6.50,
        "is_sold_out": false, "is_popular": true, "is_vegan": true,
        "is_halal": true, "calories": 210 }
    ]
  }
]

Gestionar Menú Escribir

CRUD completo para categorías y artículos — todo lo que una app de comercio necesita para gestionar el menú. Todos los endpoints de escritura requieren un write token y están limitados a un restaurante de tu propiedad. La subida de imágenes queda fuera del alcance de JSON; pasa una URL ya alojada en image.

curl -X POST https://www.menubarcode.com/api/v1/restaurants/12/menu/items \
  -H "Authorization: Bearer YOUR_TOKEN" -H "Content-Type: application/json" \
  -d '{
    "category_id": 3, "name": "Margherita", "price": 11.00,
    "description": "San Marzano, mozzarella, basil",
    "is_vegan": true, "is_halal": true, "calories": 850
  }'

Interruptor rápido "86". Envía {"is_sold_out": true}, u omite el cuerpo para alternar.

Pedidos

Pedidos, del más reciente al más antiguo, paginados (30/página). Filtra con ?status=.

Detalle completo del pedido con líneas, extras, repartidor y cronología de entrega.

Crea un pedido — así es como una app de cliente envía un carrito (el backend del comercio guarda el token). Cada artículo se valida contra el menú activo del restaurante; los artículos agotados o ajenos rechazan todo el pedido (422). Dispara order.created y devuelve el pedido completo, incluido su track_token.

curl -X POST https://www.menubarcode.com/api/v1/restaurants/12/orders \
  -H "Authorization: Bearer YOUR_TOKEN" -H "Content-Type: application/json" \
  -d '{
    "type": "delivery",
    "customer_name": "A. Idriss",
    "phone": "+15551234567",
    "address": "9 Cedar Road",
    "tip_amount": 3.00,
    "note": "Ring the bell",
    "source": "customer_app",
    "items": [
      { "item_id": 88, "quantity": 2, "variation": 5, "extras": [12], "note": "no onion" },
      { "item_id": 91, "quantity": 1 }
    ]
  }'

Pedido type es uno de on-table, takeaway, delivery. para on-table pasa table_number; para delivery pasa address.

Idempotencia. Envía una Idempotency-Key cabecera (o un cuerpo client_uuid) en cualquier llamada de creación de pedido. Reintentar con la misma clave devuelve el pedido original y nunca crea un duplicado — seguro ante respuestas perdidas y reenvíos sin conexión. Las claves tienen ámbito por restaurante.

Actualiza el estado de cocina (new|preparing|ready|delivered|completed|cancelled). Dispara order.status_changed.

API del sitio web (token por restaurante)

Una API pública independiente autenticada por un token de sitio web por restaurante enviado como X-Storefront-Token (no el token Bearer del propietario). Emítelos desde tu panel; cada token solo puede acceder a su propio restaurante. El ámbito de lectura es menu:read; para realizar pedidos se necesita el order:write Alcance

Menú completo del restaurante del token (variantes, extras, grupos, galería).

Información básica del restaurante del token.

Envía un carrito en nombre de un comensal. Con precios calculados en el servidor y sin pagar (el comensal paga al recibir); takeaway o on-table únicamente. Cada artículo se valida contra el menú activo — los artículos agotados o ajenos rechazan todo el pedido (422). Límites: 40 artículos/pedido, 30 de cantidad/línea. Opcional coupon_code aplica un descuento del propietario en el servidor. Dispara order.created y devuelve track_token + continue_url.

curl -X POST https://www.menubarcode.com/api/v1/storefront/orders \
  -H "X-Storefront-Token: YOUR_STOREFRONT_TOKEN" -H "Content-Type: application/json" \
  -d '{
    "type": "takeaway",
    "customer_name": "A. Idriss",
    "phone": "+15551234567",
    "coupon_code": "WELCOME10",
    "items": [
      { "item_id": 88, "quantity": 2, "variation": 5, "extras": [12] },
      { "item_id": 91, "quantity": 1 }
    ]
  }'

Analíticas y clientes

Resumen de ventas en un rango de fechas (?from=YYYY-MM-DD&to=YYYY-MM-DD, por defecto, los últimos 30 días): número de pedidos por estado/tipo, ingresos brutos y pagados, valor medio del pedido y artículos más vendidos.

{
  "range": { "from": "2026-06-02", "to": "2026-07-02" },
  "orders": { "total": 214, "paid": 198, "by_status": {...}, "by_type": {...} },
  "revenue": { "gross": 8420.50, "paid": 7990.00, "avg_order_value": 39.35 },
  "top_items": [ { "item_id": 88, "name": "Margherita", "quantity": 143 } ]
}

La lista de clientes del restaurante (CRM), paginada. Filtra con ?search=.

Gestionar repartidores Escribir

Los repartidores te pertenecen y (opcionalmente) a un restaurante. Crear o rotar un repartidor devuelve un token de repartidor sin cifrar exactamente una vez — entrégalo a la app del repartidor; se autentican con él (ver más abajo).

curl -X POST https://www.menubarcode.com/api/v1/drivers \
  -H "Authorization: Bearer YOUR_TOKEN" -H "Content-Type: application/json" \
  -d '{"name":"Alex","phone":"+15550001111","restaurant_id":12}'

# → { "id": 7, "name": "Alex", ..., "token": "RAW_DRIVER_TOKEN_SHOWN_ONCE" }

Invalida el token antiguo y devuelve uno nuevo.

Asigna y sigue una entrega

Pedidos de entrega, filtrables por ?delivery_status= y ?driver_id=.

Asignar un repartidor {"driver_id": 7}. Establece delivery_status=assigned y dispara order.driver_assigned.

Sobrescribe la etapa de entrega: pending | assigned | picked_up | out_for_delivery | delivered | failed.

API de la app de repartidor

La app del repartidor se autentica con un Token de repartidor (no un token de propietario) emitido arriba. Ruta base https://www.menubarcode.com/api/v1/driver. Cada respuesta está limitada a ese único repartidor.

Authorization: Bearer RAW_DRIVER_TOKEN

El perfil del repartidor autenticado.

Pedidos asignados a este repartidor. Añade ?active=1 para ocultar entregados/fallidos.

Avanza la entrega: {"delivery_status":"out_for_delivery"} luego "delivered" o "picked_up" / "failed", opcional note). Dispara los mismos webhooks que el endpoint del propietario.

Envía la posición en vivo: {"lat":25.2048,"lng":55.2708}. Mostrada en la vista de seguimiento del cliente mientras está en reparto.

Cuentas de clientes

A app de cliente independiente autentica a sus propios usuarios con un token por cliente (estilo Sanctum: varios dispositivos, revocables individualmente). No interviene ningún token de propietario. Los clientes tienen ámbito por restaurante, así que la autenticación está bajo /restaurants/{id}/customer/…. Explora primero el menú con el endpoint público:

Menú activo agrupado por categoría (se omiten los artículos agotados). Sin autenticación.

Registrarse / iniciar sesión

curl -X POST https://www.menubarcode.com/api/v1/restaurants/12/customer/login \
  -H "Content-Type: application/json" \
  -d '{"email":"sam@example.com","password":"secret123","device":"iPhone 15"}'

# → { "token": "RAW_CUSTOMER_TOKEN", "customer": { "id": 42, "name": "Sam", ... } }

Sin contraseña (OTP por SMS)

Solicita un código para un número de teléfono y luego verifícalo. La verificación busca o crea al cliente y devuelve un token. Los endpoints de autenticación tienen límite de tasa (inicio/registro 10/min, solicitud de OTP 6/min).

API de la app de cliente

Autentícate con el token de cliente. Ruta base https://www.menubarcode.com/api/v1/customer. Todo está limitado al cliente autenticado — el cuerpo del pedido nunca puede suplantar el id de otro cliente.

Authorization: Bearer RAW_CUSTOMER_TOKEN

Lectura / actualización del perfil (nombre, correo, teléfono, cumpleaños, consentimientos).

Realiza un pedido como este cliente (mismo formato de artículo que el endpoint de creación del comercio; la identidad se toma del token). Devuelve el pedido con su track_token.

El historial de pedidos del propio cliente, paginado.

Direcciones de entrega guardadas (la primera pasa a ser la predeterminada; admite lat/lng).

Revoca el token usado en la petición (solo ese dispositivo).

Seguimiento de pedidos Público

Sin autenticación — el acceso se controla mediante el track_token impredecible del pedido (devuelto al crear el pedido). Esto alimenta una app de cliente pantalla de seguimiento en vivo.

{
  "id": 5501, "status": "preparing", "delivery_status": "out_for_delivery",
  "is_paid": true, "total": 42.00,
  "timeline": { "preparing_at": "...", "out_for_delivery_at": "..." },
  "items": [ { "name": "Margherita", "quantity": 2 } ],
  "driver": { "name": "Alex", "lat": 25.2, "lng": 55.27, "location_updated_at": "..." }
}

El bloque del repartidor (con coordenadas en vivo) aparece solo una vez que el pedido se ha recogido / está en reparto.

Acceso del personal

A app del personal (POS / KDS / camarero) autentica a cada miembro del personal con un token por empleado. Dos vías reflejan el panel: correo + contraseña, o un PIN numérico rápido para tablets de cocina compartidas. El personal tiene ámbito por restaurante.

curl -X POST https://www.menubarcode.com/api/v1/restaurants/12/staff/pin \
  -H "Content-Type: application/json" -d '{"pin":"4321","device":"Kitchen iPad"}'

# → { "token": "RAW_STAFF_TOKEN",
#     "staff": { "id": 3, "role": "kitchen", "permissions": ["kds"] } }

La respuesta lista los permisos efectivos del miembro del personal Permisos — un subconjunto de orders, menu_edit, coupons, analytics, kds, customers derivados de su rol (gerente / cajero / cocina / camarero) más cualquier anulación por empleado. Los endpoints están protegidos por permisos (403 en caso contrario).

API de la app del personal

Autentícate con el token de personal. Ruta base https://www.menubarcode.com/api/v1/staff. Todas las acciones están limitadas al restaurante del miembro del personal.

Authorization: Bearer RAW_STAFF_TOKEN

Perfil con rol y lista de permisos.

Lista pedidos y actualiza el estado de cocina. Requiere el permiso orders permiso.

Tickets de cocina en vivo agrupados por pedido, filtrados por la estación del miembro del personal (o ?station_id=). Muestra solo los artículos aún queued|preparing|ready.

Avanza (queued → preparing → ready → served) o retrocede un estado de KDS. El estado del pedido principal se resincroniza automáticamente.

Edita el menú desde el local (gerentes). Mismos payloads que los endpoints de menú del comercio, limitados al restaurante del miembro del personal.

Resumen de ventas del restaurante del miembro del personal (mismo formato que el endpoint de analíticas del comercio; ?from=&to=).

Revoca el token de este dispositivo.

Webhooks — configuración

Registra endpoints desde el panel en Tokens de API y webhooks. Elige qué eventos recibe cada endpoint. Al guardar obtienes, por endpoint, un Secreto de firma; usa el Probar botón para enviar un ping. Pausa un endpoint para detener la entrega sin perder su secreto.

Tu endpoint debería responder con un 2xx estado rápidamente (en menos de 10 s). Cualquier otro estado — o un tiempo de espera agotado — se trata como un fallo y se reintenta.

Los endpoints también se pueden gestionar programáticamente (para REST-Hooks de Zapier/Make) con un webhooks:write token:

GET    /api/v1/webhook-endpoints            # list your endpoints
POST   /api/v1/webhook-endpoints            # {"url":"https://…","events":["order.created"]} → 201 {id, secret, …}
DELETE /api/v1/webhook-endpoints/{id}       # unsubscribe → 204

El secret se devuelve solo al crear — guárdalo para verificar la firma. url debe ser un endpoint HTTPS público (protegido contra SSRF); events debe estar en la lista de abajo (o *).

Eventos de webhook

¿Falló una entrega mientras tu endpoint estaba caído? Usa Reenviar en cualquier fila del registro de entregas recientes del panel para volver a encolarla con un nuevo webhook-id.

Payload del webhook

Cada entrega es un POST con este envoltorio JSON y estas cabeceras:

POST /your-endpoint HTTP/1.1
Content-Type: application/json
webhook-id: msg_a1b2c3d4e5f6g7h8i9j0k1l2
webhook-timestamp: 1751472240
webhook-signature: v1,K5f...base64...==
X-Webhook-Event: order.created          (legacy)
X-Webhook-Signature: 9a3f...hex...      (legacy, HMAC of body only)

{
  "id": "msg_a1b2c3d4e5f6g7h8i9j0k1l2",
  "event": "order.created",
  "created_at": "2026-07-02T18:04:00+00:00",
  "data": { "order_id": 5501, "total": "42.00" }
}

El id es único por entrega. Como los reintentos reutilizan el mismo id, úsalo para que tu manejador sea idempotente.

Verificar la firma

El webhook-signature cabecera es un HMAC-SHA256, codificado en base64, calculado sobre {id}.{timestamp}.{body} usando el secreto de firma de tu endpoint. Vincular el id y la marca de tiempo a la firma es lo que hace que una petición capturada sea segura frente a reenvíos. Rechaza cualquier petición cuya webhook-timestamp tenga más de ~5 minutos de antigüedad.

PHP

$secret  = 'whsec_from_dashboard';
$id      = $_SERVER['HTTP_WEBHOOK_ID'];
$ts      = $_SERVER['HTTP_WEBHOOK_TIMESTAMP'];
$body    = file_get_contents('php://input');
$sent    = explode(',', $_SERVER['HTTP_WEBHOOK_SIGNATURE'])[1] ?? '';

if (abs(time() - (int) $ts) > 300) { http_response_code(400); exit; }

$expected = base64_encode(hash_hmac('sha256', "$id.$ts.$body", $secret, true));
if (!hash_equals($expected, $sent)) { http_response_code(401); exit; }

// verified — process $body
http_response_code(200);

Node.js

const crypto = require('crypto');

function verify(req, secret) {
  const id  = req.headers['webhook-id'];
  const ts  = req.headers['webhook-timestamp'];
  const sig = (req.headers['webhook-signature'] || '').split(',')[1];
  if (Math.abs(Date.now() / 1000 - Number(ts)) > 300) return false;

  const expected = crypto
    .createHmac('sha256', secret)
    .update(`${id}.${ts}.${req.rawBody}`)
    .digest('base64');

  return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(sig || ''));
}

Reintentos y registro de entregas

La entrega es asíncrona y se reintenta en caso de fallo con retroceso exponencial más jitter: aproximadamente 1m → 5m → 15m → 1h (hasta 5 intentos en total). Cada intento — con éxito o fallido — se registra en el registro de entregas de tu panel con su estado HTTP, número de intento y fragmento de respuesta.

Servidores MCP

Cinco servidores Model Context Protocol conectan a los agentes de IA (ChatGPT, Claude, Cursor) con la plataforma — elige el que se ajuste a tu audiencia. Todos hablan JSON-RPC 2.0 sobre HTTP y negocian versiones de protocolo 2024-11-05 / 2025-03-26 / 2025-06-18.

Inicio rápido: ir a Admin, Catalog, Customer, o Dev. El servidor del sitio web comparte el patrón de conexión de Admin con una X-Storefront-Token cabecera en lugar de un token Bearer.

Servidor MCP (Admin)

Un cliente de IA compatible con MCP (Claude, ChatGPT, Cursor) puede operar tu restaurante en lenguaje natural usando los mismos tokens de API. Apúntalo a:

Autentícate con Authorization: Bearer YOUR_TOKEN. Cada herramienta declara la capacidad granular que necesita (resource:action); una read el token cubre todas :read las herramientas y write lo cubre todo. Todas las llamadas están limitadas a tus restaurantes y con límite de tasa. Las herramientas para las que no tienes la capacidad se ocultan de tools/list.

Conectar (Claude Code)

claude mcp add --transport http platform-admin https://www.menubarcode.com/mcp \
  --header "Authorization: Bearer YOUR_TOKEN"

Listar herramientas

curl -X POST https://www.menubarcode.com/mcp \
  -H "Authorization: Bearer YOUR_TOKEN" -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

Llamar a una herramienta (p. ej. añadir un artículo de menú)

curl -X POST https://www.menubarcode.com/mcp \
  -H "Authorization: Bearer YOUR_TOKEN" -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/call",
       "params":{"name":"add_menu_item",
                 "arguments":{"restaurant_id":12,"name":"Latte","price":4.5}}}'

Herramientas

Catalog MCP (descubrir restaurantes)

Un servidor MCP público de solo lectura que permite a los agentes de IA descubrir restaurantes y platos en toda la plataforma, y luego enlazar directamente a una tienda concreta para pedir. Sin autenticación, con límite de tasa.

Conectar (Claude Code)

claude mcp add --transport http platform-catalog https://www.menubarcode.com/mcp/catalog

Solo aparecen las tiendas activas y listadas públicamente; los propietarios pueden excluirse en los ajustes de su tienda. Nunca se devuelven datos de contacto del propietario. Para realizar un pedido, usa el MCP del sitio web con un token de agente por tienda.

Customer Account MCP

Permite al asistente de IA de un comensal leer, seguir y volver a pedir sus propios pedidos. Autenticado por un token por cliente del inicio de sesión OTP existente; la identidad del cliente proviene únicamente del token — nunca se acepta un teléfono o id de cliente como argumento.

Obtener un token (flujo OTP)

# 1) request a one-time code (sent to the customer's phone)
curl -X POST https://www.menubarcode.com/api/v1/restaurants/12/customer/otp/request \
  -H "Content-Type: application/json" -d '{"phone":"+15551234567"}'

# 2) verify the code → returns a customer bearer token
curl -X POST https://www.menubarcode.com/api/v1/restaurants/12/customer/otp/verify \
  -H "Content-Type: application/json" -d '{"phone":"+15551234567","code":"123456"}'

Conectar (Claude Code)

claude mcp add --transport http my-orders https://www.menubarcode.com/mcp/customer \
  --header "Authorization: Bearer CUSTOMER_TOKEN"

curl -X POST https://www.menubarcode.com/mcp/customer \
  -H "Authorization: Bearer CUSTOMER_TOKEN" -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call",
       "params":{"name":"my_orders","arguments":{"limit":5}}}'

Conecta tu editor de IA

¿Creando un tema o una integración con Claude Code, Cursor o VS Code? Apúntalo al servidor Dev MCP — tu herramienta de IA obtiene documentación de la plataforma en vivo, la lista blanca de Liquid generada y validación de temas en el servidor. No se necesita token.

Claude Code

claude mcp add --transport http platform-dev https://www.menubarcode.com/mcp/dev

Cursor — .cursor/mcp.json

{ "mcpServers": { "platform-dev": { "url": "https://www.menubarcode.com/mcp/dev" } } }

VS Code — .vscode/mcp.json

{ "servers": { "platform-dev": { "type": "http", "url": "https://www.menubarcode.com/mcp/dev" } } }

Herramientas learn_platform (empieza aquí), search_docs / fetch_full_doc, get_liquid_reference, get_section_schema, validate_theme, list_webhook_events. Flujo de trabajo recomendado para agentes: aprender → construir → validar → entregar.

Registro de cambios

Volver a Menubarcode