Anúncios · Atributos e variações

Os atributos são o vocabulário do anúncio: dizem o que o produto é (marca, material, potência) e no que cada variação difere (cor, tamanho, voltagem). Quem dita as regras é a categoria. Cada uma define seus próprios atributos, obrigatórios ou não.

O vínculo categoria–atributo

GET/api/categories/{id}/attributes

Cada atributo retornado carrega flags do vínculo com aquela categoria:

Flag	Significado
`is_required`	Obrigatório: sem ele o anúncio não passa no checklist de publicação.
`is_feature`	Característica descritiva do produto (marca, material, peso).
`is_variant`	Atributo de variação (cor, tamanho, voltagem).
`is_combinable`	Pode entrar na geração de combinações de variações.
`is_filter`	Vira filtro de busca na vitrine.

Parâmetro	Para quê
`matrix=true`	Agrupa por seção (Identificação, Técnico, ...). Sem ele, lista plana.
`only_features=1`	Apenas características.
`only_variations=1`	Apenas atributos de variação.

only_features e only_variations juntos retornam 422.

Anatomia de um atributo

A definição é autodescritiva. O backend te diz como montar o formulário e o payload:

{
  "id": 14,
  "name": "Cor",
  "type": "color",                  // estrutura do valor (tabela abaixo)
  "value_type": null,               // tipo primitivo (text/float/number), relevante nos types default*
  "is_feature": false,
  "is_variant": true,
  "ui": {
    "public_name": "Cor",
    "description": "Cor predominante do produto",
    "select_type": "select"         // select/radio/checkbox = opção pré-cadastrada; text = digitação livre
  },
  "value_definition": {
    "fields": { /* schema dinâmico do formulário (ex.: value, main_color, hex) */ },
    "options": [                    // opções pré-cadastradas, quando houver
      {
        "id": 87,
        "value": "Azul",
        "component": { "value": "Azul", "main_color": "blue", "hex": "#1565C0", "brightness": "dark" }
      }
    ]
  }
}

type define a estrutura do valor. São nove tipos, cada um detalhado com exemplo visual e payload no guia Tipos de atributo:

`type`	O que guarda	Payload típico
`default`	Texto simples	`{ "id": 1, "value": "Algodão" }`
`default_unit`	Número + unidade	`{ "id": 5, "value": 350, "unit": "ml" }`
`default_list`	Lista de itens	`{ "id": 9, "items": ["Cabo USB", "Manual"] }`
`dimension_2d`	Largura × altura	`{ "id": 11, "width": 20, "height": 30, "unit": "cm" }`
`dimension_3d`	Largura × altura × profundidade	`{ "id": 12, "width": 20, "height": 30, "depth": 10, "unit": "cm" }`
`color`	Cor (pré-cadastrada ou livre)	`{ "id": 14, "value": "Azul Petróleo", "hex": "#0F4C5C" }`
`image`	Estampa/textura com imagem	`{ "id": 18, "value_id": 42 }`
`brand`	Marca com logo opcional	`{ "id": 2, "value_id": 3 }`
`packaging`	Quantidade + tipo de embalagem	`{ "id": 3, "value": 12, "unit": "box" }`

value_type (text, float, number) é o tipo primitivo do valor. Relevante nos types default*; os tipos especializados o ignoram.

Opção pré-cadastrada vs. valor livre: quando ui.select_type é select/radio/checkbox, envie o value_id de uma das options (ou um value que case exatamente com uma opção). Quando é text, digite livre. A exceção é a cor: atributos type=color aceitam também uma cor livre (value + hex), detalhada na seção de cor do guia de tipos.

Onde os atributos entram no anúncio

No create/simulate, há dois lugares:

attributes[]: características do anúncio como um todo (marca, material...).
variations[].attributes[]: o que diferencia cada variação (a cor azul desta, a voltagem 110 V daquela).

A API aceita os aliases attribute_id/id, attribute_value/value, value_unit/unit e value_id/option_id: use o par que preferir, mas seja consistente.

Cuidado com valor numérico em atributo de opções. Num atributo com select_type diferente de text, um value numérico é interpretado como ID de opção, não como o número em si. Se o valor que você quer enviar é um número, mande o value_id explicitamente para não cair na opção errada.

Variações: da combinação ao SKU

1. Gerar combinações

POST/api/categories/{id}/combine-attributes

Envie os valores escolhidos de cada atributo is_combinable: texto, option_id ou objeto (cor customizada, dimensões):

{
  "attributes": {
    "1": ["110 V", "220 V"],
    "14": [{ "value": "Azul Petróleo", "hex": "#0F4C5C", "custom": true }, "Verde"]
  },
  "primary_attribute_id": 1
}

A resposta traz combinations[] (o produto cartesiano, cada uma com attributes, attributes_details e description) e primary_attribute. Escolha o atributo principal que muda a aparência do produto (cor, em geral): é ele que organiza as fotos em Imagens.

Valores customizados só passam em atributos com select_type: "text" ou type: "color"; nos demais, use opções pré-cadastradas. Atributo fora da lista de combináveis da categoria → 400.

2. Vincular um SKU em cada variação

Cada combinação vira um item de variations[] no create, com seu seller_sku:

{
  "seller_sku": "FK-JBL-2000-AZUL",
  "attributes": [{ "attribute_id": 14, "value": "Azul Petróleo", "hex": "#0F4C5C" }],
  "images": [{ "id": "{{image_id}}" }]
}

Use SKUs diferentes quando cada variação tem estoque/preço próprio, ou o mesmo SKU quando as variações são apenas visuais. O SKU precisa existir na loja com preço e estoque configurados.

Status da variação

active, pending (default na criação) ou hidden. Não confunda com o status da oferta de catálogo (active, inactive, paused, pending), usado no attach-sku.

Atributos calculáveis

Alguns atributos (ex.: Quantidade) são is_calculable: true. Em ofertas de catálogo, a unidade desse atributo precisa casar com a base_unit do seu SKU, senão a API recusa com 422. Detalhes em Tipos de atributo.