API y desarrolladores

Modelo de Datos del Producto

Entiende la jerarquía de entidades de producto y el orden obligatorio de creación

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

flowchart TD
    CAT["<b>Catalog</b><br/><i>read-only</i>"]
    PROD["<b>Product</b><br/>nombre, descripción, estado"]
    OPT["<b>Option</b><br/>ej. Talla, Color"]
    VAL["<b>OptionValue</b><br/>ej. S, M, L"]
    VAR["<b>Variant</b><br/>precio, stock, estado"]
    MED["<b>Media</b><br/>imágenes"]
    TAG["<b>Category</b><br/>etiqueta global"]

    CAT -->|contiene| PROD
    PROD -->|tiene| OPT
    OPT -->|tiene| VAL
    PROD -->|tiene| VAR
    VAR -->|tiene| MED
    TAG -.->|"asignada vía tag_ids"| PROD

    style CAT fill:#f3e8ff,stroke:#7c3aed,color:#1e1e1e
    style PROD fill:#ede9fe,stroke:#7c3aed,color:#1e1e1e
    style OPT fill:#e0f2fe,stroke:#0284c7,color:#1e1e1e
    style VAL fill:#e0f2fe,stroke:#0284c7,color:#1e1e1e
    style VAR fill:#dcfce7,stroke:#16a34a,color:#1e1e1e
    style MED fill:#dcfce7,stroke:#16a34a,color:#1e1e1e
    style TAG fill:#fef3c7,stroke:#d97706,color:#1e1e1e
Entidad Descripción
Catalog Contenedor principal de productos. Se crea automáticamente con el merchant. La API solo permite consultarlo con GET /v1/catalogs.
Product Artículo del catálogo con nombre, descripción y estado.
Category Etiqueta global para organizar productos (ej. "Ropa", "Electrónica"). Se asigna al producto vía tag_ids.
Option Grupo de variación (ej. "Talla", "Color").
OptionValue Valor dentro de una opción (ej. "S", "M", "L" para Talla).
Variant Combinación específica de valores de opción con precio propio (ej. "Polo Negro - Talla M").
Media Imagen o archivo asociado a una variante, no al producto directamente.

Orden Obligatorio de Creación

sequenceDiagram
    participant M as Merchant
    participant API as Business API
    M->>API: GET /v1/catalogs
    API-->>M: catalog_id
    M->>API: POST /v1/products
    API-->>M: product_id
    M->>API: POST .../options
    API-->>M: option_value_ids
    M->>API: POST .../variants (con option_values)
    API-->>M: variant_id
    M->>API: POST .../media
    M->>API: POST .../categories
  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

Entidad Estados posibles
Product published
Variant available (disponible), not_available (no disponible)

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.

¿Necesitas ayuda?