Referencia de la API

URL base y formato de respuesta

Todas las rutas se sirven bajo el prefijo /api. En local, la URL base es http://localhost:8000/api. En un servidor es la dirección de tu API seguida de /api, el mismo valor que leen los dos frontends de NEXT_PUBLIC_API_BASE_URL (Variables de entorno).

La API sirve a dos públicos que nunca comparten un token: los clientes, que usan las rutas del sitio web, y el personal, que usa las del panel. Los cuerpos de las peticiones son JSON, salvo las subidas de archivos. Cada respuesta llega en el mismo envoltorio:

{
  "success": true,
  "data": { },
  "message": ""
}

data contiene el resultado. message es una frase breve que rellenan algunas escrituras, en el idioma de la petición, y si no está vacío. El dinero va en dólares decimales en JSON, por ejemplo 14.99, y cada total lo calcula la API: no se confía en nada que un cliente envíe sobre dinero.

La comprobación de estado no necesita token:

curl http://localhost:8000/api/health

{"success":true,"data":{"status":"ok","database":"up"},"message":""}

Cuando no se puede leer la base de datos, sigue respondiendo 200, con "status":"degraded" y "database":"down". La comprobación de estado de la imagen de Docker lee ese campo.

Errores

Un fallo mantiene el envoltorio, con success: false y el estado HTTP:

{
  "success": false,
  "data": null,
  "message": "errors.kitchen_closed",
  "errors": { "email": ["…"] },
  "code": "…"
}

• Los errores que ve un cliente son claves como errors.kitchen_closed, errors.outside_area o errors.rate_limited, que el sitio web traduce por sí mismo. Los demás mensajes son frases en el idioma de la petición.
• errors aparece en un fallo de validación, con los problemas por campo.
• code lleva un motivo legible por máquina cuando existe, por ejemplo changes con una lista changes cuando un precio cambió antes de hacer un pedido.
• Una ruta protegida sin token responde 401; un token sin el permiso responde 403.

Listas y paginación

Las rutas de lista aceptan page y limit (también se acepta page_count en lugar de limit). limit tiene un máximo de 100. Salvo que quien llama ordene, las filas llegan de la actualizada más recientemente a la más antigua, con el id como desempate, así que la paginación es estable.

{ "items": [ ], "total": 64, "page": 1, "limit": 12, "totalPages": 6 }

Las listas de platos y de pedidos ponen las filas bajo items. Las listas de categorías, reseñas, clientes, equipo, roles y ajustes las ponen bajo data, con los mismos campos de paginación. Las listas que se leen en una secuencia, como las secciones de la página de inicio y la cola de las cocinas, mantienen esa secuencia.

Idioma

Envía Accept-Language: ar para recibir mensajes en árabe; cualquier otro valor responde en inglés. Los registros del menú llevan los dos idiomas como { "en": "…", "ar": "…" } diga lo que diga la cabecera, y el cliente elige uno.

Inicio de sesión

1. 01

   Inicia sesión como personal

   TerminalCopiar

   curl -X POST http://localhost:8000/api/auth/login \
     -H "Content-Type: application/json" \
     -d '{"email":"owner@foodstudio.example","password":"FoodDemo2026!"}'

   data.access_token es el token del personal, con token_type Bearer, expires_in (7d por defecto, JWT_EXPIRATION) y el miembro con sus roles. GET /api/auth/me devuelve el miembro con sesión iniciada con sus permisos.
2. 02

   Llama a una ruta protegida

   TerminalCopiar

   curl http://localhost:8000/api/orders -H "Authorization: Bearer YOUR_TOKEN"
3. 03

   Inicia sesión como cliente

   POST /api/auth/customer/login con el mismo cuerpo responde { token, user }; POST /api/auth/customer/register acepta first_name, last_name, email, password (8 caracteres o más) y, opcionalmente, phone, y responde lo mismo. El cliente de demostración es sam@foodstudio.example con FoodDemo2026!.

• Un token de cliente se rechaza en todas las rutas del personal, y un token del personal en todas las rutas de clientes.
• Un correo desconocido y una contraseña incorrecta responden ambos 401 con el mismo mensaje.
• Diez inicios de sesión fallidos desde una misma dirección en 15 minutos, por formulario, responden 429 hasta que el fallo más antiguo tiene 15 minutos (RATE_LIMIT_LOGIN). Los inicios de sesión correctos no cuentan.
• No hay ruta para cerrar sesión: un cliente cierra sesión olvidando su token.

Permisos

Las rutas del personal comprueban un permiso, con el nombre <module>.<action>. Un miembro tiene todos los permisos de todos sus roles.

El menú

Un plato lleva name, description e ingredients en los dos idiomas, price, su category, images, option_groups con sus choices y el price_delta de cada elección, allergens, dietary_tags, preparation_minutes, y los interruptores is_active (publicado), is_available (se puede pedir ahora), is_featured e is_best_seller.

Cocinas y la comprobación del código postal

{ "postcode": "10001", "mode": "delivery", "kitchen_code": "central" }

Responde { result, kitchen, alternatives }, donde result es match, outside_area o closed. La recogida no está limitada por el código postal. Si una cocina está abierta depende del ajuste del reloj de servicio.

Precios, códigos promocionales y el carrito

{
  "lines": [
    { "product_id": 9, "quantity": 1, "options": [{ "group": "size", "choice": "double" }], "instructions": "no onions" },
    { "offer_id": 1, "quantity": 1, "offer_choices": { "main": 9, "side": 5, "drink": 3 } }
  ],
  "kitchen_code": "central",
  "fulfillment": "delivery",
  "address": { "street": "12 Main St", "city": "Demo City", "postcode": "10001" },
  "promo_code": "TASTE10"
}

• Una línea indica un product_id o un offer_id, con una quantity de 1 a 10 e instructions de 200 caracteres como máximo.
• El presupuesto indica el subtotal, los descuentos, la tarifa, el total, los puntos que ganaría el pedido, si la entrega puede hacerse (address_incomplete, outside_area, closed, below_minimum) y una lista changes para cualquier línea cuyo precio cambió o que no se puede pedir.
• Un código promocional descuenta su porcentaje del subtotal del menú, nunca de la tarifa de entrega. redeem_points: true aplica un canje para un cliente con sesión iniciada que tenga puntos suficientes.

Hacer un pedido y seguirlo

• POST /api/orders acepta las lines del presupuesto, kitchen_code, fulfillment y address, más phone, payment_method (stripe, paypal o demo, según lo que liste GET /api/payments/methods), terms_accepted: true y, para un invitado, name y email. Opcionales: promo_code, redeem_points, delivery_instructions, locale, accept_changes, y return_url_ok y return_url_cancel, que deben estar en una dirección de CORS_ORIGIN.
• Responde 201 con { order, payment, tracking }. payment.kind es redirect, con la página del proveedor en payment.url, o none para el pago de demostración, que luego paga POST /api/payments/checkout-session. tracking es un token firmado, válido durante tres horas, para GET /api/orders/track/status.
• La misma Idempotency-Key de la misma persona devuelve el pedido guardado en lugar de crear un segundo.
• Un precio que cambió, o un plato que dejó de estar disponible, responde 422 con code: "changes" hasta que el cliente envía la clave del cambio en accept_changes.
• El seguimiento para invitados responde el mismo 404 para un número desconocido, un correo incorrecto y parámetros que faltan.

El estado de un pedido pasa por pending, confirmed, preparing, ready, y luego out_for_delivery y delivered para la entrega, o directamente a delivered para la recogida. Puede pasar a cancelled con un motivo antes de salir de la cocina, y solo pasa a refunded cuando el proveedor de pago informa de un reembolso.

Pagos

• Configura los pagos

Direcciones, platos guardados, recompensas, reseñas y contacto

Personal: menú, categorías, combos y página de inicio

Personal: pedidos y el resumen

• Un paso que la secuencia de estados no permite responde 409 errors.transition_not_allowed; uno que esta cuenta no puede dar, 403 errors.transition_forbidden; confirmar un pedido sin pagar, 409 errors.payment_required.
• Una cuenta de cocina solo ve los pedidos de su propia cocina, sin precios, y cualquier otro pedido responde 404.

Personal: clientes, equipo y roles

Personal: ajustes, cocinas, códigos promocionales, subidas y notificaciones

• Los ajustes con los que funciona el restaurante son delivery_fee, pickup_fee, delivery_minimum, rewards_points_per_dollar, rewards_redeem_points, rewards_redeem_value y service_clock (real o demo-fixed), junto a site_name, site_tagline, support_email y support_phone.
• Una imagen subida se guarda como JPEG en varios tamaños, y la respuesta relaciona cada versión con su dirección. Los archivos van al bucket cuando las variables R2_* están configuradas y, si no, a /media/uploads/… en la API.
• Cada ruta de notificaciones responde con todo el listado, así que un cliente sustituye lo que tiene por la respuesta.

Límites por dirección

Una petición que supera un límite responde 429 con errors.rate_limited. Los recuentos viven en la memoria de la API, así que un reinicio los borra. Detrás de un proxy inverso, configura TRUST_PROXY para que cada visitante se cuente por su propia dirección.

El asistente de IA y sus conversaciones

Estudio de IA

Servidor MCP

Actualizaciones en directo por WebSocket

Rutas del modo demostración