Uso de la API pública
La API pública permite construir storefronts e integraciones que consumen el catálogo. Olympus no incluye API keys propias; Mont Blanc y Everest admiten hasta cinco, gestionadas con el equipo de plataforma.
URL base
Sección titulada «URL base»Producción:
https://api-scent.zenitstudio.dev/api/public/v1Utiliza únicamente rutas bajo /api/public/v1. Las variantes sin esa base o con versiones duplicadas no forman parte del contrato canónico.
Autenticación
Sección titulada «Autenticación»Envía la clave en el encabezado x-api-key:
curl 'https://api-scent.zenitstudio.dev/api/public/v1/products' \ -H 'x-api-key: TU_API_KEY'Nunca incluyas una clave privada en un repositorio público. Para storefronts ejecutados en el navegador, coordina con soporte el mecanismo de acceso apropiado y restringe el origen permitido.
Versión del contrato
Sección titulada «Versión del contrato»Envía x-zenit-contract: 2 en cada llamada a la API pública. tenant-info devuelve catalog.contractVersion (hoy 2): si el valor es distinto de 2, trátalo como incompatibilidad y vacía los carritos que hayas guardado con otra versión. El encabezado no bloquea ni rechaza peticiones; Zenit lo usa para saber si tu storefront está al día.
Flujo recomendado
Sección titulada «Flujo recomendado»- Obtén la clave correspondiente al tenant.
- Consulta
tenant-infopara cargar la configuración y capacidades disponibles. - Consume marcas, productos, facetas y ofertas desde las rutas canónicas.
- Envía eventos de búsqueda y compra solo cuando el usuario realice la acción.
- Usa checkout y estado de orden respetando el esquema publicado.
Campos de presentación y número de pedido
Sección titulada «Campos de presentación y número de pedido»Además de nombre, precio e imágenes, el catálogo entrega campos pensados para la ficha de producto. Todos están siempre presentes en la respuesta:
| Campo | Qué contiene |
|---|---|
product.badge |
Etiqueta corta (hasta 24 caracteres) o null. |
product.highlights |
Lista de hasta 6 puntos destacados ([] si no hay). |
options[].values[].swatchHex |
Color #rrggbb del valor o null. Dibuja la opción como muestras de color solo si todos sus valores tienen color. |
variants[].compareAtPrice |
Precio «antes» de la variante, solo cuando es mayor que su precio; si no, null. Nunca se cobra. |
Para tachar un precio usa compareAtPrice ?? originalPrice (el segundo existe solo con una promoción activa). Muestra badge y highlights como texto plano, nunca como HTML.
El estado de orden (order-status/{token}) devuelve orderNumber, por ejemplo ORDER-0001, para mostrarlo en la página de confirmación. Es solo una referencia visible: la consulta se hace siempre con el token de la orden, nunca con el número.
Errores
Sección titulada «Errores»Todos los errores de la API tienen un cuerpo JSON con error (texto legible) y code (identificador estable). Ramifica siempre por code, nunca por el texto de error: los mensajes pueden cambiar y no están garantizados en un solo idioma. Algunos errores incluyen además requestId; guárdalo al reportar un problema a soporte.
{ "error": "Validation failed", "code": "VALIDATION_ERROR", "fieldPaths": [{ "path": "customer.phone", "message": "…" }]}| HTTP | code |
Cuándo ocurre |
|---|---|---|
| 400 | VALIDATION_ERROR |
Cuerpo o parámetros inválidos. fieldPaths lista cada campo con su ruta completa (por ejemplo customer.phone). |
| 400 | INVALID_JSON |
El cuerpo de un POST no es JSON válido o falta content-type: application/json. |
| 400 | NOT_CONFIGURED |
El tenant no tiene Recurrente activo, o lo tiene pero pausó los cobros (ver pagos pausados). |
| 401 | — | Falta x-api-key o la clave no es válida. |
| 403 | PLAN_LIMIT_EXCEEDED |
El plan del tenant no incluye pagos en línea (por debajo de Mont Blanc). |
| 409 | ITEMS_UNAVAILABLE |
Alguna línea del carrito ya no se puede vender. errors[] indica la variantId o el comboId y su motivo: ITEM_UNAVAILABLE, OUT_OF_STOCK o CAPABILITY_OFF. |
| 422 | LOGISTICS_INCOMPLETE |
El envío por peso no se puede calcular porque a una variante le falta peso. |
| 422 | SHIPPING_UNAVAILABLE |
La tienda restringe el envío a sus reglas de ubicación y no hay una para el department indicado. |
| 422 | PICKUP_NOT_ENABLED |
Pediste shippingMethod: "pickup" y la tienda no tiene recogida habilitada. No se crea la orden. |
| 422 | CHECKOUT_MINIMUM_NOT_MET |
El total (productos más envío) es menor al mínimo de Recurrente, Q5.00 en GTQ. |
| 429 | RATE_LIMITED |
Superaste un límite de uso. Incluye Retry-After: 60. |
| 500 | PAYMENT_ERROR |
Recurrente no pudo crear el cobro. La orden queda fallida y no se cobra nada. |
Para el resto de errores (rutas inexistentes, recursos no encontrados, fallos internos) consulta la referencia OpenAPI.
Límites de uso
Sección titulada «Límites de uso»Los límites se cuentan por minuto. Al superarlos, la API responde 429 con code: "RATE_LIMITED" y el encabezado Retry-After: 60: espera ese tiempo antes de reintentar y no repitas la petición en bucle.
| Recurso | Límite por minuto |
|---|---|
POST /checkout |
10 por IP y 120 por tenant |
GET /order-status/{token} |
30 por IP |
POST /tracking/search |
30 por IP |
POST /tracking/purchase-clicks |
30 por IP y 600 por tenant |
POST /tracking/marketing |
120 por IP y 3000 por tenant |
POST /zeni |
30 por tenant y 10 por IP |
POST /quiz/recommend |
60 por tenant y 10 por IP |
Zeni y el quiz responden de forma distinta: el 429 trae code: "RATE_LIMIT_EXCEEDED" (tenant) o "RATE_LIMIT_EXCEEDED_IP" (IP), con limitPerMinute, y no incluye Retry-After; reintenta pasado un minuto. Zeni además tiene una cuota mensual: al agotarse responde 429 con code: "ADDON_LIMIT_EXCEEDED".
Cache y cabeceras
Sección titulada «Cache y cabeceras»- Catálogo (productos, marcas, facetas, categorías, ofertas): respuestas públicas con
Cache-Control: publicystale-while-revalidate=60, másVary: x-api-key. El tenant sale solo de esa cabecera, así que cualquier caché compartido debe separar las respuestas porx-api-key. tenant-info:Cache-Control: private, no-cache, no-store, must-revalidate. Refleja el plan y lo que el panel activa o desactiva, por lo que no debe cachearse en el borde.order-statusyquiz:Cache-Control: private, no-store.order-statuscontiene datos del comprador y nunca debe guardarse en una caché.- No agregues tus propias capas de caché sobre
tenant-infoniorder-status.
Pagos pausados
Sección titulada «Pagos pausados»tenant-info expone dos campos para decidir si ofrecer el pago con tarjeta:
| Campo | Significado |
|---|---|
hasPaymentEnabled |
true solo si Recurrente está activo, no está pausado y el plan permite pagos en línea. Es el único campo que debes usar para decidir el flujo de pago. |
paymentsPaused |
Informativo: indica que el tenant pausó los cobros nuevos sin desconectar Recurrente. |
Cuando hasPaymentEnabled es false, paymentMethods ya no incluye card: muestra tu flujo alternativo (por ejemplo, pedir por WhatsApp). Si aun así llamas a POST /checkout, la respuesta es 400 con code: "NOT_CONFIGURED"; trátala como la señal para pasar a ese flujo alternativo, no como un error de tu integración. Los pagos ya iniciados antes de la pausa se completan con normalidad. Quién pausa y reanuda los cobros se explica en Pagos.
Estado de orden y datos del comprador
Sección titulada «Estado de orden y datos del comprador»GET /order-status/{token} solo acepta una clave de tenant (con la clave de sistema responde 403) y se consulta con el orderToken de la URL de éxito. Pasados 30 días desde la creación de la orden, customerName, nit, shippingAddress, shippingMethod, authCode, cardLast4 y cardNetwork viajan como null; id, orderNumber, status, importes e items se siguen devolviendo. Muestra esos campos solo si no son null.
Contrato interactivo
Sección titulada «Contrato interactivo»Consulta la referencia OpenAPI para ver parámetros, cuerpos y respuestas vigentes. El contrato se genera directamente desde las rutas públicas del SaaS.
