API pública de tienda online
API REST server-to-server en producción para integrar en tu propio sitio el catálogo y los flujos de compra de Lueira. Las operaciones requieren que el acceso esté habilitado para el tenant.
Endpoints
Base URL: https://api.lueira.com/api/store/v1. La especificación OpenAPI enumera las 113 operaciones, con parámetros, scopes, modelos y respuestas: catálogo de alquileres, packs, clases, cursos, pases y tienda; disponibilidad y precios; formularios y subidas; carritos, descuentos, checkout y pagos; login y cuenta de cliente; pedidos, bonos y reservas de sesiones.
Acceso y permisos
El administrador contratará el complemento de tienda online por separado y creará una clave de tipo online_store con los scopes necesarios. Una clave admin no sirve para la API de tienda, ni una clave de tienda para la API de administración o MCP.
- Catálogo y disponibilidad:
store:catalog:read,store:availability:read. - Carrito y checkout:
store:cart:read,store:cart:write,store:checkout:write. - Pedidos:
store:orders:read. - Clientes:
store:customer:read,store:customer:write. - Bonos:
store:vouchers:read,store:vouchers:write.
Autorización de compradores
La clave identifica al tenant. Store-ID selecciona una tienda habilitada de ese tenant. Las rutas del comprador requieren además Customer-Authorization: Bearer <token>. Las operaciones de carrito usan un Cart-Access-Token propio del carrito. Mantén estos secretos en un servidor.
Headers de petición y respuesta
La referencia interactiva declara los headers en cada operación. Usa estos headers comunes y condicionales:
| Dirección | Header | Cuándo y para qué |
|---|---|---|
| Petición | Authorization: Bearer <api_key> | Obligatorio en las operaciones; usa una clave online_store. No la expongas en JavaScript del navegador. |
| Petición | Store-ID | Opcional. Selecciona una tienda habilitada; si se omite se usa la tienda principal del tenant. |
| Petición | X-Lueira-Center-Slug | Opcional. Selecciona un centro visible por su slug en tiendas con varios centros. |
| Petición | Customer-Authorization: Bearer <token> | Obligatorio en las operaciones que requieren sesión de cliente. |
| Petición | Cart-Access-Token y Cart-ID | Se envían en las operaciones de carrito indicadas por OpenAPI. El token del carrito es un secreto. |
| Petición | Idempotency-Key | Obligatorio en mutaciones; usa una clave única de hasta 255 caracteres y conserva la misma al reintentar. |
| Petición | Content-Type: application/json | Envíalo cuando la petición incluya un cuerpo JSON. |
| Respuesta | X-Request-ID | Identificador de cada respuesta; inclúyelo al contactar con soporte. En errores coincide con error.request_id. |
| Respuesta | X-Lueira-Api-Version | Versión de la API, por ejemplo store-v1. |
| Respuesta | X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset | Límite, peticiones restantes y momento de reset del límite por minuto. |
| Respuesta | Retry-After | Segundos que debes esperar cuando se responde 429. |
| Respuesta | X-Store-Usage, X-Store-Included, X-Store-Grace, X-Store-Overage-Packs, X-Store-Usage-Reset | Uso y cuota mensual en respuestas correctas; el reset es UTC. |
| Respuesta | X-Next-Offset, X-Total-Count | Metadatos de paginación cuando la operación los devuelve. |
| Respuesta | Cart-ID, Cart-Access-Token, Idempotency-Replayed | Headers de carrito cuando aplica. Idempotency-Replayed: true indica que se devolvió una respuesta guardada. |
allowed_origins solo configura CORS y no autentica usuarios. El navegador puede leer los headers expuestos por CORS cuando el origen está permitido.Orígenes permitidos
Puedes configurar allowed_origins en cada clave de tienda. Solo determinan a qué orígenes responde CORS el navegador: no sustituyen la autenticación ni son una lista de IP permitidas.
Reintentos seguros
Cada mutación requiere un Idempotency-Key único. Repetir la misma petición con la misma clave devuelve la respuesta original; reutilizarla con datos distintos produce 409. Si una operación queda pendiente de conciliación, también responde 409: conserva la clave y consulta el estado antes de volver a intentar una compra.
Cuotas y facturación
El complemento se factura mediante una suscripción mensual de Stripe, aunque el plan principal sea anual. El primer mes se prorratea hasta el siguiente mes UTC. Tras las peticiones incluidas hay un margen gratuito del 5 %; después, cada bloque iniciado de 25.000 peticiones correctas cuesta 25 €. No se corta el servicio al alcanzar la cuota mensual. El límite por minuto sigue aplicándose y puede devolver 429.
| Plan | Complemento mensual | Req/min | Incluidas/mes |
|---|---|---|---|
| Básico | 49 € | 150 | 75.000 |
| Pro | 99 € | 300 | 375.000 |
| Premium | 179 € | 750 | 1.500.000 |
online_store con los scopes mínimos y el acceso habilitado para tu tenant.