> ## 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 Dados do Produto

> Entenda a hierarquia de entidades de produto e a ordem obrigatória de criação

# Modelo de Dados do Produto

Antes de gerenciar produtos via API, é fundamental entender como as entidades se relacionam e em que ordem devem ser criadas.

## Hierarquia de Entidades

```mermaid theme={null}
flowchart TD
    CAT["<b>Catalog</b><br/><i>somente leitura</i>"]
    PROD["<b>Product</b><br/>nome, descrição, status"]
    OPT["<b>Option</b><br/>ex. Tamanho, Cor"]
    VAL["<b>OptionValue</b><br/>ex. P, M, G"]
    VAR["<b>Variant</b><br/>preço, estoque, status"]
    MED["<b>Media</b><br/>imagens"]
    TAG["<b>Category</b><br/>etiqueta global"]

    CAT -->|contém| PROD
    PROD -->|possui| OPT
    OPT -->|possui| VAL
    PROD -->|possui| VAR
    VAR -->|possui| MED
    TAG -.->|"atribuída via 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
```

| Entidade | Descrição |
| - | - |
| **Catalog** | Contêiner principal de produtos. É criado automaticamente com o merchant. A API apenas permite consultá-lo com `GET /v1/catalogs`. |
| **Product** | Item do catálogo com nome, descrição e status. |
| **Category** | Etiqueta global para organizar produtos (ex. "Roupas", "Eletrônicos"). É atribuída ao produto via `tag_ids`. |
| **Option** | Grupo de variação (ex. "Tamanho", "Cor"). |
| **OptionValue** | Valor dentro de uma opção (ex. "P", "M", "G" para Tamanho). |
| **Variant** | Combinação específica de valores de opção com preço próprio (ex. "Polo Negro - Tamanho M"). |
| **Media** | Imagem ou arquivo associado a uma **variante**, não ao produto diretamente. |

## Ordem Obrigatória de Criação

```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 (com option_values)
    API-->>M: variant_id
    M->>API: POST .../media
    M->>API: POST .../categories
```

1. **Obter catálogo** — `GET /v1/catalogs` → seu `catalog_id`
2. **Criar produto** — `POST /v1/products` com `catalog_id`
3. **Criar opções** — `POST /v1/products/{id}/options` → guarde os IDs dos valores
4. **Criar variantes** — `POST /v1/products/{id}/variants` com `option_values`
5. **Adicionar media** — `POST /v1/products/{product_id}/variants/{variant_id}/media`
6. **Atribuir categorias** — `POST /v1/products/{id}/categories` com `tag_ids`

<Info>
  As categorias (`POST /v1/categories`) são globais e podem ser criadas a qualquer momento — não dependem do produto.
</Info>

## Regras Importantes

<Warning>
  **Os catálogos são somente leitura.** São criados automaticamente ao registrar o merchant. A API apenas permite consultá-los com `GET /v1/catalogs`.
</Warning>

<Warning>
  **As opções DEVEM existir antes de criar variantes.** O campo `option_values` é obrigatório e requer pelo menos 1 ID. Se você enviar `option_values: []` ou não incluir o campo, receberá um erro 422.
</Warning>

<Info>
  **As categorias são globais.** Criar uma categoria não a associa a nenhum produto. Você deve atribuí-la explicitamente com `POST /v1/products/{product_id}/categories` usando `tag_ids` (array de IDs).
</Info>

<Info>
  **As imagens pertencem às variantes**, não aos produtos. Cada variante pode ter suas próprias imagens.
</Info>

## Por que são necessárias opções antes de variantes?

<Warning>
  Internamente, cada produto precisa de pelo menos uma opção com valores para funcionar corretamente no catálogo. Isso se aplica mesmo para **produtos simples** que não têm variações reais (sem tamanho, cor, etc.).

  **Produto com variações** (ex. "Polo Negro"):

  * Opção: "Tamanho" → Valores: "P", "M", "G"
  * 3 variantes, uma por tamanho

  **Produto simples** (ex. "Dona Glaseada"):

  * Opção: "Apresentação" → Valor: "Padrão"
  * 1 variante com esse valor

  O nome da opção é livre. Exemplos: `"Tamanho"`, `"Cor"`, `"Apresentação"`.
</Warning>

## Status

| Entidade | Status possíveis |
| - | - |
| **Product** | `published` |
| **Variant** | `available` (disponível), `not_available` (indisponível) |

## Guias de Ação

<CardGroup cols={2}>
  <Card title="Categorias e Catálogos" icon="folder" href="/pt/products/categories-and-catalogs">
    Consulte catálogos e gerencie categorias.
  </Card>

  <Card title="Gerenciar Produtos" icon="box" href="/pt/products/manage-products">
    CRUD completo de produtos, variantes, opções e media.
  </Card>
</CardGroup>


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