Restaurantes y cafeterías

Sincronización de la carta

Normalmente el TPV es la fuente de verdad de los precios y de lo que está agotado. Asigna a cada plato tu SKU en external_id y refiérete a los platos por ese SKU; nunca necesitas guardar nuestros ids.

1. 1
   Lee lo que hay

   GET /v1/menu devuelve categorías, platos y modificadores en todos los idiomas. Añade ?lang=en para obtener textos simples en un solo idioma.

2. 2
   Crea lo que falta

   POST /v1/menu/items con category (un id de categoría o tu código de categoría; un código desconocido crea la categoría), external_id, name en uno o varios idiomas y price. Si vuelves a enviar el mismo external_id, recibes el plato existente.

3. 3
   Envía los cambios

   Con cada cambio, o cada pocos minutos, envía POST /v1/menu/items/bulk con precios y disponibilidad. Hasta 500 platos por llamada; los SKU desconocidos vuelven en not_found.

curl https://loyaltyfy.io/api/v1/menu/items/bulk \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
    "items": [
      { "item": "1001", "price": 4800 },
      { "item": "2040", "available": false },
      { "item": "3017", "price": 9900, "old_price": 12000 }
    ]
  }'

{
  "object": "menu_bulk_result",
  "updated": ["1001", "2040"],
  "unchanged": [],
  "not_found": ["3017"],
  "failed": []
}

Productos agotados: available: false deja el plato visible con la etiqueta "agotado" y quita el botón de pedir; visible: false lo oculta. Los modificadores tienen su propio interruptor, así que puedes desactivar la leche de avena sin desactivar el café:

curl -X PATCH https://loyaltyfy.io/api/v1/menu/option_values/MOD-OAT \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{ "available": false }'

Pedidos desde la mesa

Con los pedidos activados (Menú → Pedidos en el panel), los clientes que escanean el QR de la mesa pueden enviar su carrito al local. Cada mesa tiene su propio enlace con el número de mesa:

https://loyaltyfy.io/m/your-venue?table=12

Calculamos el precio de cada pedido en nuestro lado a partir de la carta actual, así que el TPV puede fiarse de los importes. Los pedidos con un plato o un modificador agotado se rechazan antes de llegar a ti.

1. 1
   Recibe los pedidos nuevos

   Suscríbete al webhook order.created o consulta GET /v1/orders?status=new cada 10 o 15 segundos.

2. 2
   Acepta

   Crea el pedido en el TPV y luego llama a POST /v1/orders/{id}/accept con tu propio id de pedido como external_id. Usa el external_id de cada línea para casar tus SKU.

3. 3
   Hazlo avanzar

   PATCH /v1/orders/{id} con preparing, ready, served, completed. O POST /v1/orders/{id}/reject con un motivo si la cocina no puede prepararlo.

curl "https://loyaltyfy.io/api/v1/orders?status=new" \
  -H "Authorization: Bearer sk_test_..."

{
  "object": "order",
  "id": "0c69a81c-0fbc-4333-b26c-789566b9bea4",
  "number": 10,
  "status": "new",
  "table": "7",
  "note": "No onions, please",
  "currency": "MDL",
  "subtotal": 14000,
  "item_count": 2,
  "items": [
    {
      "item_id": "a48343bd-9f6e-424a-b003-fe790617f4d6",
      "external_id": "2040",
      "name": "Zeamă",
      "quantity": 2,
      "unit_price": 7000,
      "total": 14000,
      "options": []
    }
  ],
  "external_id": null,
  "reject_reason": null,
  "guest_language": "en",
  "source": "qr_menu",
  "livemode": true,
  "created_at": "2026-10-06T18:14:48.233+00:00",
  "accepted_at": null,
  "completed_at": null,
  "updated_at": "2026-10-06T18:14:48.233+00:00"
}

curl -X POST https://loyaltyfy.io/api/v1/orders/0c69a81c-0fbc-4333-b26c-789566b9bea4/accept \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{ "external_id": "POS-ORDER-55821" }'

Los estados solo avanzan: new → accepted → preparing → ready → served → completed; new también puede pasar a rejected, y cualquier pedido abierto puede pasar a cancelled. Puedes saltarte pasos (de aceptado directamente a completado no hay problema). Un paso hacia atrás recibe 409 invalid_status_transition. Los locales sin integración con TPV gestionan los mismos estados en la pantalla Pedidos, así que no pasa nada si tu TPV solo acepta y completa.

Fidelización en la caja de la cafetería

Igual que cualquier integración con TPV: busca al cliente cuando escanea la tarjeta y envía el ticket cuando está pagado. En cafeterías con tarjeta de sellos («el 6.º café gratis»), el sello se gana con el ticket. Envía line_items con tus referencias para que el local vea qué productos compran sus clientes.