Ir al contenido

Uso de la API pública

Mont Blanc · Everest

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.

Producción:

https://api-scent.zenitstudio.dev/api/public/v1

Utiliza únicamente rutas bajo /api/public/v1. Las variantes sin esa base o con versiones duplicadas no forman parte del contrato canónico.

Envía la clave en el encabezado x-api-key:

Ventana de terminal
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.

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.

  1. Obtén la clave correspondiente al tenant.
  2. Consulta tenant-info para cargar la configuración y capacidades disponibles.
  3. Consume marcas, productos, facetas y ofertas desde las rutas canónicas.
  4. Envía eventos de búsqueda y compra solo cuando el usuario realice la acción.
  5. Usa checkout y estado de orden respetando el esquema publicado.

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.

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.

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

  • Catálogo (productos, marcas, facetas, categorías, ofertas): respuestas públicas con Cache-Control: public y stale-while-revalidate=60, más Vary: x-api-key. El tenant sale solo de esa cabecera, así que cualquier caché compartido debe separar las respuestas por x-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-status y quiz: Cache-Control: private, no-store. order-status contiene datos del comprador y nunca debe guardarse en una caché.
  • No agregues tus propias capas de caché sobre tenant-info ni order-status.

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.

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.

Consulta la referencia OpenAPI para ver parámetros, cuerpos y respuestas vigentes. El contrato se genera directamente desde las rutas públicas del SaaS.