Solicitudes

URL base#

Todas las rutas están bajo https://api.flavoso.com/v1. Solo HTTPS. La versión va en la ruta (v1); la fecha de versión, en la cabecera Flavoso-Api-Version.

Cabeceras#

curl -i -X POST https://api.flavoso.com/v1/orders/ORDER_ID/accept \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Idempotency-Key: accept-ORDER_ID" \
  -H "User-Agent: ExamplePOS/4.2 (support@example.com)"

JSON#

Los cuerpos son objetos JSON, y las respuestas también. Los nombres de campo están en inglés y en snake_case. Un cuerpo puede ocupar hasta 64 KB (2 MB en la sincronización de la carta, PUT /menu), contados en bytes; si es mayor, la respuesta es 413 payload_too_large. Un campo o un parámetro de consulta desconocidos devuelven 400 invalid_request con param, así que una errata nunca pasa desapercibida.

Cada objeto indica su tipo en object; una lista es { "object": "list", "data": [ … ] }. Un campo sin valor es null.

Dinero e impuestos#

Los importes son números enteros en la unidad más pequeña de la moneda, es decir, en céntimos: 1290 son 12,90 €. La moneda figura junto al importe (currency, ISO 4217) o en el negocio. Nunca se usan decimales.

Los tipos impositivos van en puntos básicos: 700 es el 7 %, 1900 el 19 %. Los precios en Flavoso son precios brutos; un pedido lleva además sus impuestos desglosados por tipo (tax.lines). Si el negocio no tiene ningún tipo guardado para una parte, esa línea lleva rate_bps: null, y net y tax son null; también el tax_rate_bps de una línea del pedido puede ser null. Contabiliza esa parte como pendiente de aclarar, no como exenta de impuestos.

Fechas y horas#

• Fechas y horas según ISO 8601 en UTC con Z: 2026-10-04T17:44:59.942Z. Envíalas con zona horaria, Z o un desfase como +02:00; sin zona, la respuesta es 400. En los parámetros de consulta, escribe + como %2B (o usa Z). Las respuestas llegan siempre en UTC.
• Días del calendario como YYYY-MM-DD en la hora local del negocio, por ejemplo en los días especiales y los informes.
• Horas como HH:MM en la hora local del negocio, por ejemplo en los horarios de apertura. weekday 0 es el lunes y 6 el domingo.
• La zona horaria del negocio (IANA, por ejemplo Europe/Berlin) figura en GET /me y GET /store.

Identificadores#

Los identificadores son UUID y nunca cambian. Excepciones: los eventos (evt_…) y las solicitudes (req_…). Un pedido tiene además un code corto que ve el cliente, por ejemplo 3271CD; no sirve para asociar datos.

Identificadores propios: external_id#

Con external_id asocias tu propio identificador a un objeto: el número de artículo de tu caja a un plato, el número de ticket a un pedido. Después puedes encontrar el objeto por ese identificador sin tener que guardar ninguna tabla de correspondencias.

• De 1 a 100 caracteres, sin caracteres de control y sin espacios al principio ni al final. Se cuentan caracteres, no bytes.
• Único por app, negocio y tipo: dos platos de tu app en el mismo negocio no pueden llevar el mismo; un plato y un pedido, sí.
• Solo tu app ve sus identificadores en las respuestas de las rutas. Para cualquier otra app el campo es null, y en los eventos siempre es null: el mismo sobre va a todos los destinatarios.
• Está disponible en categorías, platos, grupos de opciones, opciones y pedidos.
• Se asigna con PUT /menu, al crear y al modificar, y en los pedidos con POST /orders/{id}/acknowledge.
• Se filtra con ?external_id= en las listas.
• Si ya está en uso, Flavoso responde con 409 external_id_taken.
• Si el objeto se borra, su identificador desaparece con él.

# Find the dish your POS knows as ART-1001
curl "https://api.flavoso.com/v1/menu/products?external_id=ART-1001" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

# Find the order you booked as receipt R-2026-000123
curl "https://api.flavoso.com/v1/orders?external_id=R-2026-000123" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

livemode#

livemode está en GET /me y en cada evento: false para un negocio de prueba, true para cualquier negocio real. No hay una dirección ni claves aparte para ello.

Versiones#

Dentro de v1 solo hay añadidos compatibles: campos nuevos, rutas nuevas, códigos de error nuevos, eventos nuevos. Lo que rompa la compatibilidad (un campo desaparece o cambia de significado) solo llega en una versión nueva, y la anterior sigue funcionando al menos seis meses más.

Flavoso-Api-Version en cada respuesta y api_version en cada evento indican la fecha de versión, actualmente 2026-10-08. En Cambios se indica qué cambió y cuándo.

Sin CORS#

La API funciona solo de servidor a servidor. Las rutas con datos no envían Access-Control-Allow-Origin, así que ningún navegador deja que una página ajena lea su respuesta. Un token en el navegador sería un token publicado. Sin autenticación solo se pueden consultar openapi.json, postman.json y los metadatos de OAuth.

Métodos#

Una ruta desconocida bajo /v1 responde con 404 not_found en el mismo formato de error.