Colecciones

Las colecciones permiten agrupar productos de forma manual o automática (por reglas). Se usan para campañas, colecciones temáticas y destacados.

Listar colecciones

GET /api/v1/catalog/collections

Parámetros:

Nombre	Tipo	Descripción
cursor	string	Cursor de paginación
limit	int	Items por página (default 25, máx 100)
filter[status]	string	active, draft
sort	string	-created_at, title, position

Respuesta 200:

{
  "data": [
    {
      "id": "uuid",
      "title": "Verano 2026",
      "slug": "verano-2026",
      "description": "Productos destacados de verano",
      "status": "active",
      "product_count": 18,
      "created_at": "2026-04-08T12:00:00Z"
    }
  ],
  "meta": { "pagination": { "cursor": "eyJ...", "has_next": true } }
}

---

Crear colección

POST /api/v1/catalog/collections

{
  "title": "Verano 2026",
  "slug": "verano-2026",
  "description": "Productos destacados de verano",
  "status": "active",
  "sort_order": "manual"
}

Campo	Requerido	Tipo	Descripción
title	sí	string	Nombre de la colección
slug	no	string	URL-friendly (auto-generado si vacío)
description	no	string	Descripción
status	no	string	active o draft
sort_order	no	string	manual o -created_at
seo_title	no	string	Título para SEO
seo_description	no	string	Meta descripción
image_media_id	no	uuid	Imagen de portada

Respuesta 201: objeto Collection completo.

---

Obtener colección

GET /api/v1/catalog/collections/:id

Devuelve la colección con sus metadatos e incluye product_count.

---

Actualizar colección

PUT /api/v1/catalog/collections/:id

Mismos campos que crear. Adicionalmente:

Campo	Tipo	Descripción
position	int	Orden de aparición

---

Eliminar colección

DELETE /api/v1/catalog/collections/:id

Respuesta 204 No Content

---

Productos en colección

Listar productos de una colección

GET /api/v1/catalog/collections/:id/products

Parámetros:

Nombre	Tipo	Descripción
cursor	string	Cursor de paginación
limit	int	Items por página (default 25)

Respuesta 200:

{
  "data": [
    {
      "id": "uuid",
      "title": "Polo Clásico",
      "slug": "polo-clasico",
      "price": 4900,
      "position": 1
    }
  ],
  "meta": { "pagination": { "cursor": "eyJ...", "has_next": false } }
}

Agregar producto a colección

POST /api/v1/catalog/collections/:id/products

{
  "product_id": "uuid",
  "position": 1
}

Respuesta 201: objeto de relación producto-colección.

Eliminar producto de colección

DELETE /api/v1/catalog/collections/:id/products/:product_id

Respuesta 204 No Content