Productos
y variaciones

Listar productos

GET /api/v1/external/products

Devuelve todos los productos del catálogo del tenant. Requiere scope products:read.

Request

curl https://api.nuvlyx.com/api/v1/external/products \
  -H "Authorization: Bearer nvl_live_TU_TOKEN"

Response 200

[
  {
    "id": "0f1c2b9e-8c3a-4b56-a8b3-9d6e4d4b1f7a",
    "tenantId": "…",
    "name": "Suscripción digital 1 mes",
    "slug": "suscripcion-digital-1-mes",
    "kind": "DIGITAL",
    "status": "ACTIVE",
    "variations": [
      {
        "id": "abc12345-…",
        "sku": "SUB-1M",
        "price": "10000.00",
        "stockQuantity": 42,
        "durationDays": 30,
        "dependsOnStock": true
      }
    ],
    "createdAt": "2026-04-01T15:30:00.000Z"
  }
]

Detalle de un producto

GET /api/v1/external/products/:id

Devuelve un producto específico con todas sus variaciones, niveles de precio y categorías. Requiere scope products:read.

Path parameters

Request

curl https://api.nuvlyx.com/api/v1/external/products/0f1c2b9e-8c3a-4b56-a8b3-9d6e4d4b1f7a \
  -H "Authorization: Bearer nvl_live_TU_TOKEN"

Errores

• 401 — Token faltante o inválido.
• 403 — Token sin el scope products:read.
• 404 — Producto no existe o pertenece a otra tienda.

Cotizar precio para un cliente

GET /api/v1/external/products/:id/price

Devuelve el precio de cada variación del producto, aplicando el tier de precios que le corresponde al cliente. Útil cuando su bot necesita mostrarle al cliente el precio exacto antes de confirmar la compra. Requiere scope products:read.

Query parameters

Si no envía ningún identificador, la respuesta trae el precio base (retail) de cada variación. Si envía ambos, devuelve 400.

Request

curl "https://api.nuvlyx.com/api/v1/external/products/0f1c…/price?customerId=9f8e…" \
  -H "Authorization: Bearer nvl_live_TU_TOKEN"

Response 200

{
  "productId": "0f1c…",
  "productName": "Suscripción digital 1 mes",
  "currency": "COP",
  "customer": {
    "id": "9f8e…",
    "tier": { "id": "tier_…", "name": "Plata", "level": 2 }
  },
  "variations": [
    {
      "variationId": "abc12345-…",
      "sku": "SUB-1M",
      "basePrice": "10000.00",
      "price": "8500.00",
      "appliedTier": { "id": "tier_…", "name": "Plata", "level": 2 },
      "availableStock": 42,
      "dependsOnStock": true
    }
  ]
}

Notas

• Sin tier asignado: si el cliente no tiene un tier configurado, customer.tier y appliedTier vienen en null y price es igual a basePrice.
• Variación sin tarifa especial para ese tier: si la variación no tiene un precio explícito para el tier del cliente, price cae al basePrice y appliedTier queda en null solo para esa variación.
• Phone no vinculado: si envía customerPhone de un cliente que aún no vinculó su WhatsApp, devuelve 404 con un mensaje explícito.
• Ojo: este endpoint sirve para mostrar. Al hacer POST /external/orders el servidor recalcula el precio con la misma lógica — no acepta un precio enviado desde el cliente.