Conceptos

El modelo#

Flavoso es un sistema de pedidos para restaurantes. Cada negocio tiene su propia página de pedidos, carta, cocina y panel. Tu app trabaja en nombre de un negocio una vez que su propietario ha dado su consentimiento.

App#

Una app es tu software tal como lo conoce Flavoso: creada en la consola, con un client ID (flv_app_…), un tipo de cliente, URI de redirección, los permisos que puede solicitar y un webhook. Una app puede estar conectada con cualquier número de negocios; una cuenta tiene como máximo 10 apps.

Cada app tiene un estado: en desarrollo, en revisión, aprobada, rechazada o bloqueada. Hasta la aprobación solo se conecta con tu negocio de prueba y con negocios de los que tú mismo eres propietario.

Negocio#

Un negocio es un restaurante en Flavoso. En la API se llama tenant y tiene id, name, slug (la parte de la dirección de su página de pedidos), timezone, currency y country. GET /me lo devuelve.

Un negocio tiene un plan (Starter, Pro, Premium). La API forma parte de todos los planes; las reservas están disponibles a partir de Pro.

Conexión#

Una conexión es el consentimiento de un propietario: esta app puede trabajar con este negocio, con estos permisos. Su identificador se llama connection_id en la respuesta del endpoint de token y en cada evento, e id en GET /me, porque GET /me devuelve la propia conexión. Ahí está también su created_at.

Por app y negocio hay como máximo una conexión activa. Si el propietario vuelve a conectar la app, a partir de ese momento se aplican los permisos nuevos. Una conexión termina cuando el propietario la desconecta, cuando tu app llama a DELETE /connection o cuando Flavoso la cierra; en ese caso llega app.disconnected.

Tokens#

• Token de acceso (flv_at_…): va en cada solicitud y es válido durante una hora.
• Token de actualización (flv_rt_…): sirve para obtener nuevos tokens de acceso, es válido durante 180 días desde su último uso y se sustituye por uno nuevo en cada uso.

Cada token pertenece a una sola conexión y, por tanto, a un solo negocio. Una app con cien negocios gestiona cien pares de tokens, que conviene guardar asociados al connection_id o al tenant.id.

Permisos#

Nueve permisos controlan lo que puede hacer una conexión, por ejemplo orders:write o menu:read. El permiso de escritura incluye el de lectura. El propietario los ve en lenguaje claro al conectar. Encontrarás todos los detalles en Permisos.

Prueba y real#

No hay claves de prueba separadas ni una segunda dirección. La diferencia está en el negocio: un negocio de prueba nunca puede convertirse en un negocio real, y todo lo que viene de él lleva livemode: false, en GET /me y en cada evento. La misma app, las mismas rutas, los mismos formatos de token.

Objetos e identificadores#

Cada objeto lleva su object (order, product, reservation, event …) y un id. Los identificadores son UUID, salvo en los eventos (evt_…) y las solicitudes (req_…). Un identificador nunca cambia, aunque el negocio cambie el nombre o el precio.

Tus propios identificadores, como el número de artículo de tu caja, van aparte en external_id. Consulta Solicitudes.

Dos direcciones#

• Tu app consulta: REST en https://api.flavoso.com/v1, JSON en ambos sentidos.
• Flavoso avisa: cada cambio como evento, entregado por webhook o recogido con GET /events.

Un cambio es el mismo dondequiera que ocurra: en el panel, en la pantalla de cocina, en la app móvil, en la impresora de tickets o a través de la API. Un evento lo notifica exactamente una vez.