API de FlavosoPrimeros pasosInicio rápido

Inicio rápido

Tu primera respuesta en dos minutos con un token de prueba y, después, el camino completo con OAuth 2.0.

Dos formas

Hay dos formas de obtener un token y necesitas las dos:

Token de prueba: un clic en la consola y consultas tu propio negocio de prueba. Ideal para conocer la API en dos minutos.
OAuth 2.0: así es como cada negocio conectará tu app más adelante. El propietario inicia sesión y da su consentimiento, y tu app recibe tokens solo para ese negocio.

Solo necesitas una cuenta gratuita de Flavoso: no hace falta un negocio propio ni una suscripción. Los ejemplos funcionan con curl, Node.js 18 o posterior, Python 3 con requests y PHP 8 o posterior.

Con el asistente de configuración

Lo más rápido es hacerlo en la propia consola. Si aún no tienes ninguna app, la consola abre el asistente de configuración, que te lleva en cinco pasos hasta tu primera respuesta. Mientras no hayas terminado, lo encontrarás a la izquierda, en Configuración.

1
Crear la app
Nombre, dónde se ejecuta (en tu servidor o en un dispositivo del local) y qué puede hacer. El asistente muestra el client secret una sola vez.
Consola › Configuración
2
Crear el negocio de prueba
Un restaurante para probar, con carta de ejemplo y mesas.
3
Crear un token de prueba
Acceso al negocio de prueba sin el flujo de OAuth.
4
Primera solicitud
GET /me con el token, desde tu código o directamente en el navegador. El asistente detecta la solicitud en cuanto llega a Flavoso y muestra el estado y la respuesta.
5
Recibir eventos
Por webhook a tu servidor, o recogidos con GET /events. Un pedido de prueba muestra que llegan.

Las secciones siguientes recorren los mismos pasos a mano, con código para cada uno.

Crear una app y un negocio de prueba

1
Crear una cuenta
Pulsa «Cuenta de desarrollador gratuita» en la página de inicio de esta documentación. Si ya tienes una cuenta de Flavoso, solo tienes que iniciar sesión.
app.flavoso.com
2
Crear una app
En la consola, en Apps, elige «Nueva app»: nombre, tipo de cliente (confidencial para apps con servidor propio), una URI de redirección y los permisos que necesita tu app. Acepta las condiciones para desarrolladores. El client secret se muestra exactamente una vez: cópialo enseguida.
Consola › Apps › Nueva app
3
Crear un negocio de prueba
Un clic crea tu negocio de prueba: un restaurante gratuito para probar, con carta de ejemplo y mesas. Todas tus apps lo comparten.
Consola › Negocio de prueba

Para el inicio rápido bastan los permisos orders:write, menu:write y store:write. Encontrarás la lista completa en Permisos.

Primera forma: token de prueba

En las Credenciales de tu app, «Crear token de prueba» genera un token de acceso y un token de actualización para tu negocio de prueba, ambos con los permisos de tu app. El token de acceso es válido durante una hora y el de actualización, 180 días desde su último uso; como cualquier token de actualización, se sustituye por uno nuevo en cada uso. La consola muestra los dos una sola vez. Así se crea también la conexión entre la app y el negocio de prueba, igual que con el consentimiento de un propietario.

Define la variable de entorno ACCESS_TOKEN con el token y consulta GET /me, que devuelve la propia conexión:

# The test token from the developer console (valid for up to one hour)
export ACCESS_TOKEN="flv_at_..."

curl https://api.flavoso.com/v1/me \
  -H "Authorization: Bearer $ACCESS_TOKEN"

La respuesta indica el negocio, los permisos concedidos y livemode. En el negocio de prueba, livemode es siempre false:

Respuesta

{
  "object": "connection",
  "id": "4b3f7c1e-9a2d-4e8b-b5f6-0c1d2e3f4a5b",
  "livemode": false,
  "app": {
    "client_id": "flv_app_...",
    "name": "Example POS"
  },
  "tenant": {
    "id": "7d0e5b8a-3c41-4f2e-9a6b-1e2d3c4b5a69",
    "name": "Test restaurant",
    "slug": "test-k7q2m9",
    "timezone": "Europe/Berlin",
    "currency": "EUR",
    "country": "DE"
  },
  "scopes": [
    "orders:write",
    "menu:write",
    "store:write",
    "reports:read"
  ],
  "plan": "pro",
  "rate_limit": {
    "limit": 120,
    "window_seconds": 60
  },
  "created_at": "2026-10-04T17:40:00.000Z"
}

Aceptar el primer pedido

1
Crear un pedido de prueba
«Crear pedidos de prueba» crea un pedido real en el negocio de prueba, como si lo hubiera hecho un cliente. Aparece en la API y desencadena webhooks.
Consola › Negocio de prueba › Pedidos
2
Obtener los pedidos abiertos
GET /orders?status=pending devuelve los pedidos que esperan la respuesta del negocio.
3
Aceptar
POST /orders/{id}/accept lo acepta, como un clic en el panel. Con una Idempotency-Key, puedes repetir la solicitud sin riesgo.

# The orders waiting for the restaurant ("Create test orders" in the console creates one)
curl "https://api.flavoso.com/v1/orders?status=pending" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

# Accept one. The same key gives the same result, so a retry is safe.
curl -X POST https://api.flavoso.com/v1/orders/ORDER_ID/accept \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Idempotency-Key: accept-ORDER_ID"

En la consola, en Negocio de prueba › Pedidos, el pedido aparece después como aceptado, y el registro de tu app muestra la solicitud con su respuesta.

Segunda forma: conectar con OAuth

Un negocio real no te da un token. Su propietario conecta tu app, así que integras en ella el flujo de OAuth 2.0 con PKCE. Lo pruebas con tu negocio de prueba antes de que nadie más lo vea.

1
Generar state y PKCE
Genera un code_verifier y un state aleatorios y calcula el code_challenge a partir del verificador (SHA-256, Base64URL).
2
Enviar a la pantalla de consentimiento
Redirige el navegador a https://app.flavoso.com/oauth/authorize. Allí inicia sesión con tu cuenta, elige el negocio de prueba y pulsa «Conectar».
3
Intercambiar el código por tokens
Flavoso redirige de vuelta a tu URI de redirección con code, state e iss. Compara state y después intercambia el código en https://api.flavoso.com/oauth/token en un plazo de 10 minutos.
4
Hacer solicitudes
Con el access_token de la respuesta, llama a la API igual que con el token de prueba.

# 1. PKCE: a random code_verifier, its S256 code_challenge and a random state
CODE_VERIFIER=$(openssl rand -hex 32)
CODE_CHALLENGE=$(printf '%s' "$CODE_VERIFIER" | openssl dgst -sha256 -binary | openssl base64 -A | tr '+/' '-_' | tr -d '=')
STATE=$(openssl rand -hex 16)

# 2. Open this address in a browser, sign in, pick your test restaurant, press "Connect".
#    http://127.0.0.1:8080/callback must be one of your app's redirect URIs. For a
#    confidential app such a loopback address only connects your test restaurant.
echo "https://app.flavoso.com/oauth/authorize?response_type=code&client_id=$CLIENT_ID&redirect_uri=http%3A%2F%2F127.0.0.1%3A8080%2Fcallback&scope=orders%3Awrite&state=$STATE&code_challenge=$CODE_CHALLENGE&code_challenge_method=S256"

# 3. The browser lands on http://127.0.0.1:8080/callback?code=...&state=...&iss=...
#    Nothing has to listen there. Compare state with $STATE, then copy the code (valid 10 minutes, once).
curl https://api.flavoso.com/oauth/token \
  -u "$CLIENT_ID:$CLIENT_SECRET" \
  -d grant_type=authorization_code \
  -d code=AUTHORIZATION_CODE \
  --data-urlencode redirect_uri=http://127.0.0.1:8080/callback \
  -d code_verifier=$CODE_VERIFIER

# 4. First request with the access_token from the response
curl https://api.flavoso.com/v1/me \
  -H "Authorization: Bearer $ACCESS_TOKEN"

La respuesta del endpoint de token:

Respuesta

{
  "access_token": "flv_at_...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "flv_rt_...",
  "scope": "orders:write menu:write store:write reports:read",
  "connection_id": "4b3f7c1e-9a2d-4e8b-b5f6-0c1d2e3f4a5b",
  "tenant": {
    "id": "7d0e5b8a-3c41-4f2e-9a6b-1e2d3c4b5a69",
    "name": "Pizzeria Example",
    "slug": "pizzeria-example"
  }
}

Encontrarás todo sobre tipos de cliente, URI de redirección, errores y consentimiento en Autenticación.

Renovar el token

Un token de acceso es válido durante una hora. Después, obtienes un par nuevo con el token de actualización. Cada renovación devuelve un token de actualización nuevo y solo ese sigue siendo válido: guárdalo antes de usar el nuevo token de acceso.

# Access tokens last one hour. The response carries a NEW refresh token: store it.
curl https://api.flavoso.com/oauth/token \
  -u "$CLIENT_ID:$CLIENT_SECRET" \
  -d grant_type=refresh_token \
  -d refresh_token=$REFRESH_TOKEN

En Autenticación se explica cómo encajan la rotación, el periodo de gracia y la revocación.

Cómo seguir

Configura webhooks para que los pedidos nuevos lleguen solos. Una caja sin dirección pública recoge los eventos.
Para una caja: la guía de integración con caja, de principio a fin.
Gestiona bien los errores: Errores, Idempotencia, Límites de solicitudes.
Cuando todo funcione: Revisión y directorio.

¿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.