API de FlavosoGuíasFlujo de pedidos

Flujo de pedidos

El ciclo de vida de un pedido, sus campos, líneas de impuestos, métodos de pago y orígenes.

El ciclo de vida

pending

nuevo, a la espera del negocio

confirmed

aceptado

preparing

en preparación

ready

listo; en pedidos a domicilio, preparado para el repartidor

completed

recogido, servido o entregado

cancelled cancelado, desde cualquier estado abierto; desde pending significa rechazar

Hacia delante se pueden saltar estados (confirmed → ready); hacia atrás no se puede.

Un negocio puede desactivar confirmed, preparing y ready; aceptar pasa entonces al siguiente estado que usa. Los estados que usa figuran en GET /store, en order_statuses.

Los estados

status	Significado	Cómo se llega
`pending`	Nuevo, a la espera del negocio.	Se crea el pedido.
`confirmed`	Aceptado.	`POST /orders/{id}/accept` (si el negocio usa `confirmed`; si no, aceptar pasa a su siguiente estado)
`preparing`	En preparación.	`POST /orders/{id}/status` con `preparing`
`ready`	Listo; en pedidos a domicilio, preparado para el repartidor.	`POST /orders/{id}/status` con `ready`
`completed`	Recogido, servido o entregado.	`POST /orders/{id}/status` con `completed`
`cancelled`	Cancelado o rechazado.	`POST /orders/{id}/reject` (solo desde `pending`) o `POST /orders/{id}/cancel`

Hacer avanzar

Hacia delante se pueden saltar estados, por ejemplo confirmed → ready. Hacia atrás no se puede: 409 invalid_transition.
Un negocio puede desactivar estados. Los que usa figuran en GET /store, en order_statuses; un estado desactivado responde con 409 stage_not_used.
Si el pedido ya está en el estado de destino, vuelve sin cambios con 200. accept pasa un pedido pending al siguiente estado que usa el negocio (si ha desactivado confirmed, preparing y ready, completed); un pedido que ya ha pasado de pending vuelve sin cambios, uno terminado o cancelado responde con 409 invalid_transition.
Rechazar y cancelar admiten un motivo (reason, hasta 200 caracteres; si es más largo, da 400) para el registro de actividad del negocio; el cliente no lo ve.
Cada cambio funciona como un clic en el panel: el cliente recibe su mensaje, el equipo su aviso, y el registro de actividad del negocio nombra a tu app.

# Accept (pending → confirmed)
curl -X POST https://api.flavoso.com/v1/orders/ORDER_ID/accept \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Idempotency-Key: accept-ORDER_ID"

# Advance: confirmed → preparing → ready → completed (skipping ahead is allowed)
curl -X POST https://api.flavoso.com/v1/orders/ORDER_ID/status \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"status": "preparing"}'

# Reject an order that was not accepted yet; the reason goes to the audit log
curl -X POST https://api.flavoso.com/v1/orders/ORDER_ID/reject \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"reason": "Out of dough"}'

# Cancel from any open status
curl -X POST https://api.flavoso.com/v1/orders/ORDER_ID/cancel \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"reason": "Guest called to cancel"}'

Con pago en el local, el pedido existe de inmediato. Con pago online, solo cuando se confirma el pago: antes no aparece en ninguna lista ni desencadena ningún evento. order.created llega exactamente una vez por pedido.

Los campos

Campo	Significado
`code`	Código corto que ve el cliente, por ejemplo `3271CD`.
`type`	`pickup`, `delivery` o `dine_in`.
`source`	De dónde viene; consulta más abajo.
`requested_for`	Hora deseada de un encargo; `null` significa lo antes posible.
`amounts`	`subtotal`, `delivery_fee`, `service_fee`, `discount`, `tip`, `total`, todo en céntimos.
`tax`	Los impuestos por tipo; consulta más abajo.
`payment`	`method`, `status`, `paid_at`.
`customer`	Nombre y, en pedidos para recoger y a domicilio, el número de teléfono.
`delivery`	En pedidos a domicilio, la dirección.
`table`	En mesa: identificador y nombre de la mesa.
`note`	Nota del cliente para la cocina. Las alergias suelen ir aquí.
`items`	Líneas con cantidad, precio unitario y de línea, opciones (con `id`, `group_id` y `group_name`) y el tipo impositivo congelado al hacer el pedido (`tax_rate_bps`, `null` sin tipo guardado).
`external_id`, `acknowledged_at`	Tu identificador y el momento en que tu app se hizo cargo del pedido; consulta Integración con caja. En los eventos, siempre `null`.

{
  "object": "order",
  "id": "cce01f52-5188-410f-9659-6ce26ba9b784",
  "code": "3271CD",
  "type": "delivery",
  "status": "pending",
  "source": "storefront",
  "created_at": "2026-10-04T17:44:59.942Z",
  "updated_at": "2026-10-04T17:45:10.118Z",
  "requested_for": null,
  "currency": "EUR",
  "amounts": {
    "subtotal": 2490,
    "delivery_fee": 250,
    "service_fee": 0,
    "discount": 0,
    "tip": 200,
    "total": 2940
  },
  "tax": {
    "included": true,
    "lines": [
      {
        "rate_bps": 700,
        "gross": 2421,
        "net": 2263,
        "tax": 158
      },
      {
        "rate_bps": 1900,
        "gross": 319,
        "net": 268,
        "tax": 51
      }
    ]
  },
  "payment": {
    "method": "online",
    "status": "paid",
    "paid_at": "2026-10-04T17:45:10.000Z"
  },
  "customer": {
    "name": "Alex",
    "phone": "+49 151 00000000"
  },
  "delivery": {
    "address": "Musterstraße 1",
    "postal_code": "10115",
    "city": "Berlin"
  },
  "table": null,
  "note": "Please ring twice",
  "external_id": null,
  "acknowledged_at": null,
  "items": [
    {
      "id": "e9c0ce66-7f7f-42cf-a4bf-7d66f87768c1",
      "product_id": "303b87c9-58a3-4644-9a8b-2841cc1f89d6",
      "name": "Pizza Margherita",
      "quantity": 2,
      "unit_price": 1100,
      "line_total": 2200,
      "tax_rate_bps": 700,
      "options": [
        {
          "id": "1f2e3d4c-5b6a-4798-8a7b-6c5d4e3f2a1b",
          "name": "Extra cheese",
          "price_delta": 150,
          "group_id": "8e7d6c5b-4a39-4281-b0f9-e8d7c6b5a4f3",
          "group_name": "Extras"
        }
      ]
    },
    {
      "id": "0d1e2f3a-4b5c-4d6e-8f70-81a2b3c4d5e6",
      "product_id": "6a7b8c9d-0e1f-4a2b-9c3d-4e5f6a7b8c9d",
      "name": "Cola 0,33 l",
      "quantity": 1,
      "unit_price": 290,
      "line_total": 290,
      "tax_rate_bps": 1900,
      "options": []
    }
  ]
}

Líneas de impuestos

tax desglosa el importe bruto del pedido por tipo impositivo: { "included": true, "lines": [{ "rate_bps", "gross", "net", "tax" }] }. Las líneas abarcan los productos del pedido, los gastos de envío y la tarifa de servicio, con el mismo cálculo que el ticket y la exportación DATEV. El impuesto está incluido en el precio (included: true).

En el ejemplo de arriba: la pizza al 7 %, la cola al 19 % y los gastos de envío repartidos proporcionalmente entre ambas. La propina no cuenta como venta y no aparece en ninguna línea.

Si el negocio no tiene ningún tipo guardado para una parte, esa parte aparece en una línea con rate_bps: null, y net y tax son ahí null, no 0. Contabilízala como pendiente de aclarar, no como exenta de impuestos.

Métodos de pago

payment.method	payment.status	Significado
`online`	`paid`	Pagado online. El pedido solo existe a partir de aquí.
`on_site`	`open`	Pago en el local, todavía pendiente: en efectivo o con tarjeta en la recogida, en la entrega o en la mesa.
`online`	`open`	Nunca visible: un pedido online solo existe para la API cuando está pagado. Flavoso no registra los pagos en el local, así que `on_site` sigue en `open`.

Con pago online, el dinero va directamente al negocio; Flavoso nunca es el receptor del pago. La propina está en amounts.tip y está incluida en total.

Orígenes

source	De dónde
`storefront`	La página de pedidos del negocio, también integrada en su web.
`table`	El código QR de la mesa.
`app`	La app de Flavoso para clientes.

Datos del cliente

Un pedido solo contiene lo necesario para entregarlo: el nombre; en pedidos para recoger y a domicilio, el número de teléfono, y en pedidos a domicilio, la dirección. Nunca la dirección de e-mail ni la cuenta del cliente. En los pedidos en mesa tampoco aparece el número de teléfono. Consulta Protección de datos.

¿Algo no ha quedado claro? Escribe a support@flavoso.com e indica el identificador de X-Request-Id. Así podremos encontrar tu solicitud en el registro.