Gestionar Productos

Esta guía cubre todas las operaciones para consultar, crear, actualizar y eliminar productos y sus sub-entidades.

Reglas Importantes

Antes de comenzar, ten en cuenta estas reglas que aplican a toda la gestión de productos:

• Status del producto: Actualmente el único valor soportado es "published". El status se devuelve igual en las respuestas.
• option_values es inmutable: Una vez creada la variante, no puedes cambiar sus option_values con PATCH. Si necesitas corregirlos, elimina la variante y créala de nuevo.
• Monedas soportadas: MXN, PEN, COP, CLP, ARS, BRL, VES, BOB, USD, PYG, UYU, CRC, EUR.
• La moneda debe coincidir con la del catálogo: Todas las variantes de un producto deben usar la misma moneda configurada en el catálogo. Usar una moneda diferente puede causar inconsistencias internas.
• Respuestas: PATCH devuelve 200 con el recurso actualizado. DELETE devuelve 204 sin body.
• Todo producto requiere al menos una variante: Incluso productos simples (sin tallas ni colores) necesitan mínimo una opción y una variante. Usa un nombre genérico como "Presentación" o "Unidad".
• No existen endpoints batch: Cada entidad se crea individualmente.

Consultar Productos

Listar productos

Devuelve una lista paginada de productos con todas sus sub-entidades.

La respuesta incluye paginación:

{
  "data": [ /* array de productos */ ],
  "pagination": {
    "page": 1,
    "limit": 25,
    "total_pages": 4,
    "total_items": 100,
    "has_more": true
  }
}

Obtener un producto

Devuelve un producto con todas sus opciones, variantes (con media) y categorías.

Ejemplo de respuesta:

{
  "id": 9876,
  "created_at": "2026-01-15T10:00:00Z",
  "name": "Polo Negro",
  "description": "Polo de algodón pima de alta calidad",
  "characteristics": "Material: 100% algodón pima. Peso: 180g/m².",
  "status": "published",
  "categories": [
    { "id": 1, "name": "Ropa" }
  ],
  "options": [
    {
      "id": 10,
      "name": "Talla",
      "values": [
        { "id": 100, "name": "S" },
        { "id": 101, "name": "M" },
        { "id": 102, "name": "L" }
      ]
    }
  ],
  "variants": [
    {
      "id": 500,
      "name": "Polo Negro - Talla M",
      "base_price": 49.90,
      "currency": "PEN",
      "status": "available",
      "media": [
        {
          "id": 1000,
          "title": "Front view",
          "url": "https://cdn.example.com/polo-negro-m-front.jpg"
        }
      ]
    }
  ]
}

Crear un Producto Completo

1. Crear el producto

2. Agregar opciones

La respuesta incluye los IDs de los valores creados. Guarda estos IDs para usarlos al crear variantes.

3. Crear variantes

Cada variante debe incluir option_values con al menos un ID de valor de opción.

4. Agregar media a la variante

5. Asignar categorías

Este endpoint es idempotente: si un tag ya está asignado, se ignora y la respuesta es 200. Solo se retorna 201 cuando se asignan tags nuevos.

Actualizar Entidades

Eliminar Entidades

Producto Simple (sin variaciones)

No todos los productos tienen tallas o colores. Aún así, todo producto requiere al menos una opción y una variante. Usa un nombre genérico para la opción.

Errores Comunes

Los errores de validación (422) devuelven un body con detalles del campo que falló:

{
  "detail": [
    {
      "loc": ["body", "option_values"],
      "msg": "List should have at least 1 item",
      "type": "too_short"
    }
  ]
}