Catálogo

Cómo listar productos, navegar categorías, filtrar por marca y gestionar inventario

El módulo de catálogo expone productos, variantes, categorías, marcas, tags y modificadores. Esta guía cubre las operaciones más comunes desde la perspectiva de una integración.

Todos los ejemplos usan el API token pk_*. Consulta la guía de autenticación si aún no tienes un token.

Productos

Listar productos

curl "https://tu-instancia.com/api/v1/products" \
  -H "Authorization: Bearer pk_..."

Parámetros de filtro disponibles:

Parámetro	Tipo	Descripción
`search`	string	Busca en nombre, SKU y GTIN
`status`	string	`draft`, `active`, `archived`
`brandId`	string	Filtra por marca
`categoryId`	string	Filtra por categoría (incluye subcategorías)
`featured`	boolean	Solo productos destacados
`sortBy`	string	`name`, `createdAt`, `updatedAt`, `price`
`sortOrder`	string	`asc`, `desc`
`page`	number	Número de página (default: 1)
`pageSize`	number	Resultados por página (default: 20, max: 100)

Ejemplo con filtros:

curl "https://tu-instancia.com/api/v1/products?status=active&brandId=clx123&sortBy=name&pageSize=50" \
  -H "Authorization: Bearer pk_..."

Obtener un producto por ID

curl "https://tu-instancia.com/api/v1/products/{productId}" \
  -H "Authorization: Bearer pk_..."

La respuesta incluye variantes, opciones, imágenes, categorías, tags y campos personalizados:

{
  "data": {
    "id": "clx...",
    "name": "Playera Básica",
    "slug": "playera-basica",
    "sku": "PLY-001",
    "status": "active",
    "description": "Playera de algodón 100%...",
    "price": 350.00,
    "costPrice": 180.00,
    "currency": "MXN",
    "brand": { "id": "...", "name": "Marca Propia", "slug": "marca-propia" },
    "primaryCategory": { "id": "...", "name": "Ropa", "slug": "ropa" },
    "secondaryCategories": [],
    "tags": [{ "id": "...", "name": "Nuevo" }],
    "variants": [
      {
        "id": "clx...",
        "sku": "PLY-001-S-BLK",
        "price": 350.00,
        "status": "active",
        "options": [
          { "optionName": "Talla", "valueName": "S" },
          { "optionName": "Color", "valueName": "Negro" }
        ]
      }
    ],
    "images": [
      { "id": "...", "url": "https://...", "altText": "Playera Básica", "position": 1 }
    ],
    "customFields": [
      { "key": "material", "value": "100% algodón" }
    ]
  }
}

Obtener producto por SKU

curl "https://tu-instancia.com/api/v1/products/sku/{sku}" \
  -H "Authorization: Bearer pk_..."

Verificar disponibilidad de slug

Útil antes de crear un producto para evitar conflictos:

curl "https://tu-instancia.com/api/v1/products/check-slug?slug=playera-basica" \
  -H "Authorization: Bearer pk_..."

{ "data": { "available": false } }

Categorías

Las categorías son jerárquicas (árbol multinivel). Cada categoría puede tener subcategorías anidadas.

Obtener el árbol de categorías

curl "https://tu-instancia.com/api/v1/categories/tree" \
  -H "Authorization: Bearer pk_..."

{
  "data": [
    {
      "id": "clx...",
      "name": "Textiles",
      "slug": "textiles",
      "level": 0,
      "children": [
        {
          "id": "clx...",
          "name": "Ropa",
          "slug": "ropa",
          "level": 1,
          "children": [
            {
              "id": "clx...",
              "name": "Playeras",
              "slug": "playeras",
              "level": 2,
              "children": []
            }
          ]
        }
      ]
    }
  ]
}

Listar categorías (plano)

curl "https://tu-instancia.com/api/v1/categories" \
  -H "Authorization: Bearer pk_..."

Obtener una categoría por ID

curl "https://tu-instancia.com/api/v1/categories/{categoryId}" \
  -H "Authorization: Bearer pk_..."

La respuesta incluye el path completo (materializado) y la categoría padre, útil para breadcrumbs.

Marcas

Listar marcas

curl "https://tu-instancia.com/api/v1/brands" \
  -H "Authorization: Bearer pk_..."

Parámetros opcionales: search, status, sortBy, sortOrder, page, pageSize.

Obtener una marca por ID

curl "https://tu-instancia.com/api/v1/brands/{brandId}" \
  -H "Authorization: Bearer pk_..."

Inventario

El inventario registra la cantidad disponible por producto/variante.

Leer inventario de un producto

curl "https://tu-instancia.com/api/v1/products/{productId}/inventory" \
  -H "Authorization: Bearer pk_..."

{
  "data": {
    "productId": "clx...",
    "quantity": 150,
    "variants": [
      {
        "variantId": "clx...",
        "sku": "PLY-001-S-BLK",
        "quantity": 50
      }
    ]
  }
}

Ajuste absoluto de inventario

Establece la cantidad exacta (útil para sincronización con ERP):

curl -X POST "https://tu-instancia.com/api/v1/products/{productId}/inventory/absolute" \
  -H "Authorization: Bearer pk_..." \
  -H "Content-Type: application/json" \
  -d '{"quantity": 200, "variantId": "clx..."}'

Ajuste relativo de inventario

Suma o resta unidades (útil para registrar ventas o recepciones):

# Sumar 50 unidades
curl -X POST "https://tu-instancia.com/api/v1/products/{productId}/inventory/relative" \
  -H "Authorization: Bearer pk_..." \
  -H "Content-Type: application/json" \
  -d '{"delta": 50, "variantId": "clx..."}'

# Restar 10 unidades (venta)
curl -X POST "https://tu-instancia.com/api/v1/products/{productId}/inventory/relative" \
  -H "Authorization: Bearer pk_..." \
  -H "Content-Type: application/json" \
  -d '{"delta": -10, "variantId": "clx..."}'

Modificadores

Los modificadores son opciones adicionales por producto (ej. grabado, empaque especial, color de bordado). Se resuelven por contexto (empresa o storefront).

Obtener modificadores resueltos para un producto

curl "https://tu-instancia.com/api/v1/products/{productId}/modifiers/resolved" \
  -H "Authorization: Bearer pk_..."

Devuelve la lista de modificadores aplicables al producto con sus opciones disponibles.

Visibilidad de catálogo

En entornos multi-empresa, la visibilidad de productos y marcas es configurable por subsidiaria.

Verificar visibilidad de un producto

curl "https://tu-instancia.com/api/v1/products/{productId}/visibility" \
  -H "Authorization: Bearer pk_..."

Listar visibilidad por empresa

curl "https://tu-instancia.com/api/v1/catalog-visibility?companyId={companyId}" \
  -H "Authorization: Bearer pk_..."

Exportación

El catálogo se puede exportar en formato CSV a través de un proceso asíncrono:

# Iniciar exportación
curl -X POST "https://tu-instancia.com/api/v1/products/export" \
  -H "Authorization: Bearer pk_..." \
  -H "Content-Type: application/json" \
  -d '{"format": "csv", "filters": {"status": "active"}}'

La exportación se procesa en segundo plano. Cuando esté lista, podrás descargar el archivo desde /api/v1/exports/{exportId}/download.

Catálogo

On this page