Cambios

Cómo cambia la API#

Dentro de v1 solo hay añadidos compatibles: campos nuevos, rutas nuevas, códigos de error nuevos, eventos nuevos. Lo que rompa la compatibilidad solo llega en una versión nueva, y la anterior sigue funcionando al menos seis meses más. Flavoso-Api-Version y api_version indican la fecha de versión.

8 de octubre de 2026: últimos retoques antes de las primeras cajas#

Antes de que las primeras cajas pasen a producción, hemos ajustado el contrato en algunos puntos. Algunos cambios son más estrictos que antes; aun así, siguen dentro de v1 porque todavía no había ninguna integración en producción. Si desarrollaste con una versión anterior, revisa estos puntos.

• Fecha de versión: Flavoso-Api-Version y api_version de los eventos nuevos indican ahora 2026-10-08. Los eventos ya entregados o consultados conservan 2026-10-04.
• Tamaño del cuerpo: un cuerpo más grande de lo que admite la operación (64 KB, 2 MB en PUT /menu, contados en bytes) recibe 413 payload_too_large en lugar de 400 invalid_request.
• Lo desconocido es un error: un parámetro de consulta o un campo del cuerpo desconocido da 400 invalid_request con param, en cualquier operación.
• Fechas con zona horaria: updated_since, created_since, starts_from y las demás fechas de una solicitud, incluido until de POST /store/pause, necesitan Z o un desfase; si no, 400. Un + sin codificar en la consulta se acepta delante del desfase.
• Crear responde 201: POST /menu/categories, /menu/products, /menu/option-groups, /menu/option-groups/{id}/options y POST /store/closures para un día nuevo (200 si sustituye a uno).
• Aceptar: POST /orders/{id}/accept pasa un pedido pending al siguiente estado que usa el negocio (no siempre confirmed); un pedido que ya ha pasado de pending vuelve sin cambios con 200, uno terminado o cancelado responde con 409 invalid_transition.
• Opciones de los pedidos: items[].options[] llevan id, group_id y group_name (null en pedidos anteriores).
• Carta: nuevo GET /menu/options; la respuesta de PUT /menu pone warnings antes de ids; un negocio de prueba guarda como máximo 50 imágenes de image_url (por encima de ese límite, PUT /menu avisa con images_capped y un plato suelto recibe 400), y restablecerlo las borra; menu.synced indica el connection_id que sincronizó.
• Escrituras simultáneas: una escritura en la carta o en el negocio (/store) que choca tres veces seguidas con otro cambio responde con 409 conflict y Retry-After en lugar de 500. Después, vuelve a enviarla sin cambios.
• Eventos: GET /events con un after que ya no se conserva sigue por el evento conservado más antiguo e indica gap: true en lugar de responder con 400; after=latest empieza en el momento actual; next_after siempre está presente. data.object.updated_at en los eventos de pedidos y reservas es el momento del cambio comunicado. store.paused y store.resumed llevan el negocio en object; store.updated también comunica order_statuses; reservation.updated también comunica una note cambiada.
• Rechazar en vez de recortar: una note de pausa de más de 140 caracteres y un reason de más de 200 dan 400 con param en lugar de recortarse.
• Permisos: GET /tables y GET /areas funcionan también con reservations:read.
• Correcciones: order.paid ya no promete pagos registrados en el local (Flavoso no registra ninguno); un token caducado o revocado ya no cuenta para el límite por dirección IP y siempre recibe 401; un PATCH /reservations/{id} que responde con 409 no ha cambiado nada; una Idempotency-Key cuya primera solicitud nunca terminó queda libre de nuevo a los 2 minutos; external_id sigue en todas partes la misma regla (sin espacios al principio ni al final, sin caracteres de control).

6 de octubre de 2026: la plataforma para desarrolladores#

La gran ampliación: las cajas y otros sistemas pueden ahora mantener la carta, hacerse cargo de los pedidos, gestionar horarios y reservas y conciliar las ventas.

• Carta: PUT /menu sincroniza toda la carta (merge, replace, dry_run); POST /menu/availability comunica hasta 500 entradas a la vez; las categorías, los platos, los grupos de opciones y las opciones se pueden crear, cambiar y borrar uno a uno; image_url; cada objeto lleva external_id y updated_at.
• Pedidos: con POST /orders/{id}/acknowledge te haces cargo de un pedido con un identificador propio; filtros nuevos paid, acknowledged, created_since, created_until, external_id; campos nuevos source, external_id, acknowledged_at y tax con líneas de impuestos.
• Negocio: GET /store indica contacto, dirección, ubicación, pedido mínimo, tiempos de preparación, horarios de reparto y próximos días especiales; novedades: PATCH /store, GET y PUT /store/hours y los días especiales en /store/closures.
• Mesas y zonas: GET /tables, GET /areas.
• Reservas: POST /reservations, PATCH /reservations/{id}, GET /reservations/availability; filtros nuevos starts_from y starts_until.
• Informes: GET /reports/sales y GET /reports/products, con el nuevo permiso reports:read.
• Recoger eventos: GET /events y GET /events/{id}. Los eventos se producen ahora para cada conexión activa, incluso sin webhook.
• Tipos de eventos nuevos: order.paid, store.updated, app.scopes_changed, menu.category.*, menu.product.created y .deleted, menu.option_group.*, menu.option.created y .deleted, menu.synced (un evento por sincronización). menu.product.updated y menu.option.updated llegan con cada cambio de campo, con changed y previous.
• Prueba y real: livemode en GET /me y en cada evento. GET /me indica además tenant.country, plan y rate_limit.
• Errores: param indica el campo erróneo; códigos nuevos external_id_taken, slot_unavailable, limit_exceeded.
• OAuth: un token de actualización ya intercambiado se sigue aceptando durante 60 segundos.
• Webhooks: cada entrega con cada intento en la consola, «Reenviar», eventos de prueba de cualquier tipo; Flavoso-Delivery-Attempt cuenta también los envíos manuales.
• Herramientas: registro de solicitudes, explorador de API, tokens de prueba, directorio de apps, postman.json, operationId en cada operación de la especificación, y esta documentación.

5 de octubre de 2026: la nueva dirección#

La API tiene ahora su propia dirección: https://api.flavoso.com. Los tokens y las respuestas no cambian, y las direcciones antiguas siguen funcionando. Solo tienes que hacer algo si tu app compara iss con un valor fijo.

• Rutas: todas las rutas están bajo https://api.flavoso.com/v1, también openapi.json y postman.json.
• OAuth: el token en https://api.flavoso.com/oauth/token, la revocación en https://api.flavoso.com/oauth/revoke y los metadatos en https://api.flavoso.com/.well-known/oauth-authorization-server. La pantalla de consentimiento sigue en https://app.flavoso.com/oauth/authorize, porque allí inicia sesión el propietario.
• Emisor: issuer en los metadatos e iss en la redirección de vuelta son ahora https://api.flavoso.com en lugar de https://app.flavoso.com. Si tu app compara iss con un valor fijo, actualízalo; mejor aún, léelo de los metadatos.
• Direcciones antiguas: https://app.flavoso.com/api/public/v1/… y https://app.flavoso.com/api/oauth/… siguen respondiendo; la dirección antigua de los metadatos redirige a la nueva.

4 de octubre de 2026: la primera versión#

La primera versión de v1, con inicio de sesión mediante OAuth 2.0 y PKCE: leer, aceptar, rechazar, cancelar y hacer avanzar pedidos; leer la carta, comunicar platos agotados y precios; pausar el negocio; leer reservas y fijar su estado; webhooks firmados.