API e desenvolvedores

Modelo de Dados do Produto

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

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

Hierarquia de Entidades

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

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

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

Regras Importantes

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.

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.

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).

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

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

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".

Status

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

Guias de Ação

Categorias e Catálogos

Consulte catálogos e gerencie categorias.

Gerenciar Produtos

CRUD completo de produtos, variantes, opções e media.

Precisa de ajuda?