> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ya.works/llms.txt
> Use this file to discover all available pages before exploring further.

# Modelo de Datos del Producto

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

# 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

```mermaid theme={null}
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

```mermaid theme={null}
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`

<Info>
  Las categorías (`POST /v1/categories`) son globales y se pueden crear en cualquier momento — no dependen del producto.
</Info>

## Reglas Clave

<Warning>
  **Los catálogos son de solo lectura.** Se crean automáticamente al registrar el merchant. La API solo permite consultarlos con `GET /v1/catalogs`.
</Warning>

<Warning>
  **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.
</Warning>

<Info>
  **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).
</Info>

<Info>
  **Las imágenes pertenecen a variantes**, no a productos. Cada variante puede tener sus propias imágenes.
</Info>

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

<Warning>
  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"`.
</Warning>

## Estados

| Entidad | Estados posibles |
| - | - |
| **Product** | `published` |
| **Variant** | `available` (disponible), `not_available` (no disponible) |

## Guías de Acción

<CardGroup cols={2}>
  <Card title="Categorías y Catálogos" icon="folder" href="/products/categories-and-catalogs">
    Consulta catálogos y gestiona categorías.
  </Card>

  <Card title="Gestionar Productos" icon="box" href="/products/manage-products">
    CRUD completo de productos, variantes, opciones y media.
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.