Skip to main content

​
Modelo de Datos del Producto

Antes de gestionar productos vía API, es fundamental entender cómo se relacionan las entidades y en qué orden deben crearse.

​
Jerarquía de Entidades

​
Orden Obligatorio de Creación

  1. Obtener catálogo — GET /v1/catalogs → tu catalog_id
  2. Crear producto — POST /v1/products con catalog_id
  3. Crear opciones — POST /v1/products/{id}/options → guarda los IDs de valores
  4. Crear variantes — POST /v1/products/{id}/variants con option_values
  5. Agregar media — POST /v1/products/{product_id}/variants/{variant_id}/media
  6. Asignar categorías — POST /v1/products/{id}/categories con tag_ids
Las categorías (POST /v1/categories) son globales y se pueden crear en cualquier momento — no dependen del producto.

​
Reglas Clave

Los catálogos son de solo lectura. Se crean automáticamente al registrar el merchant. La API solo permite consultarlos con GET /v1/catalogs.
Las opciones DEBEN existir antes de crear variantes. El campo option_values es obligatorio y requiere al menos 1 ID. Si envías option_values: [] o no incluyes el campo, recibirás un error 422.
Las categorías son globales. Crear una categoría no la asocia a ningún producto. Debes asignarla explícitamente con POST /v1/products/{product_id}/categories usando tag_ids (array de IDs).
Las imágenes pertenecen a variantes, no a productos. Cada variante puede tener sus propias imágenes.

​
¿Por qué se requieren opciones antes de variantes?

Internamente, cada producto necesita al menos una opción con valores para funcionar correctamente en el catálogo. Esto aplica incluso para productos simples que no tienen variaciones reales (sin talla, color, etc.).Producto con variaciones (ej. “Polo Negro”):
  • Opción: “Talla” → Valores: “S”, “M”, “L”
  • 3 variantes, una por talla
Producto simple (ej. “Dona Glaseada”):
  • Opción: “Presentación” → Valor: “Estándar”
  • 1 variante con ese valor
El nombre de la opción es libre. Ejemplos: "Talla", "Color", "Presentación".

​
Estados

​
Guías de Acción

Categorías y Catálogos

Consulta catálogos y gestiona categorías.

Gestionar Productos

CRUD completo de productos, variantes, opciones y media.