Skip to main content

​
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

​
Ordem Obrigatória de Criação

  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

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