Anúncios · Tipos de atributo

Este guia detalha, um a um, os nove tipos de atributo da plataforma: quais campos cada um pede, como o valor aparece na vitrine e qual payload enviar no anúncio. Para entender onde os atributos entram no fluxo de publicação (características vs. variações, combinações, SKU), comece por Atributos e variações.

Como ler a definição de um atributo

Tudo parte de GET/api/categories/{id}/attributes. Cada atributo retornado é autodescritivo:

{
  "id": 5,
  "name": "Capacidade",
  "type": "default_unit",          // estrutura do valor: qual conjunto de campos enviar
  "value_type": "float",           // tipo primitivo do campo value (text, float ou number)
  "is_feature": true,
  "is_variant": false,
  "is_calculable": false,
  "ui": {
    "public_name": "Capacidade",
    "description": "Capacidade do produto",
    "select_type": "text"          // widget: select/radio/checkbox = opção pré-cadastrada; text = valor livre
  },
  "value_definition": {
    "fields": {                    // schema de cada campo: type, required, label, enum...
      "value": { "type": "number", "required": true, "label": "Valor" },
      "unit":  { "type": "string", "required": true, "label": "Unidade", "enum": ["ml", "L"] }
    },
    "options": [ /* opções pré-cadastradas, quando houver */ ],
    "default_unit": "ml",          // unidade aplicada quando você omite unit
    "available_units": ["ml", "L"] // unidades aceitas neste atributo
  }
}

Três campos definem como preencher o atributo:

• type: a estrutura do valor. É o assunto deste guia e cada um tem sua seção abaixo.
• value_type: o tipo primitivo do campo value nos tipos genéricos (text, float ou number). Os tipos especializados ignoram esse campo, pois o schema deles já tipa cada campo internamente.
• ui.select_type: o widget de entrada. select, radio e checkbox indicam que o valor vem de uma das options pré-cadastradas (envie value_id); text indica valor digitado livremente.

Nos payloads, a API aceita os aliases attribute_id/id, attribute_value/value e value_unit/unit. Os exemplos abaixo usam a forma curta.

Os nove tipos

Atributos genéricos

Os três tipos default* cobrem a maioria dos atributos: material, potência, conteúdo da embalagem. Neles o value_type importa (text, float, number) e o ui.select_type decide entre opção pré-cadastrada e digitação livre.

default · texto simples

Um único campo value textual. É o tipo usado quando nenhum especializado se aplica: Material, Modelo, Linha, Acabamento. Combinado com select_type: "select" ou "radio", vira um dropdown de opções pré-cadastradas.

// valor livre (select_type: text)
{ "id": 7, "value": "Algodão" }

// opção pré-cadastrada (select_type: select/radio/checkbox)
{ "id": 7, "value_id": 21 }

• value é obrigatório e deve ser texto.
• Com opções pré-cadastradas, envie o value_id de uma das options. Um value textual que case exatamente com uma opção também é aceito; qualquer outro valor retorna erro de opção inválida.

default_unit · número com unidade

Pareia um valor numérico a uma unidade: Peso (kg/g), Potência (W/HP), Capacidade (L/ml). As unidades aceitas vêm de value_definition.available_units, configuradas por atributo.

{ "id": 5, "value": 350, "unit": "ml" }

• value deve ser numérico; unit deve estar em available_units.
• Omitiu unit? A API aplica o default_unit do atributo, quando configurado.
• Unidade fora da lista retorna erro Invalid unit for attribute.
• Atenção especial quando o atributo é is_calculable (ex.: Quantidade): em ofertas de catálogo a unidade precisa casar com a base_unit do seu SKU, senão a API retorna 422 (UNIT_MISMATCH).

default_list · lista de itens

Um array items de textos livres. Pensado para atributos como "Acompanha", "Materiais" e "Idiomas suportados". A vitrine exibe os itens concatenados por vírgula.

{ "id": 9, "items": ["Cabo USB", "Manual", "Fonte 12 V"] }

• items é obrigatório, com pelo menos um item.
• Cada item é texto de até 255 caracteres.
• A ordem enviada é preservada na exibição.

Dimensões

Dois tipos irmãos para medidas do produto exibidas na ficha técnica. As unidades aceitas são fixas: mm, cm ou m.

As dimensões de atributo são informativas (ficha técnica). A dimensão física usada no cálculo de frete vem do cadastro do SKU, não daqui.

dimension_2d · largura por altura

Para superfícies: tapetes, quadros, telas, espelhos.

{ "id": 11, "width": 120, "height": 80, "unit": "cm" }

• width e height são numéricos e obrigatórios; unit deve ser mm, cm ou m.
• Os campos podem ir soltos no objeto do atributo (como acima) ou aninhados em fields/component; o resultado é o mesmo.
• Se o atributo tiver default_unit, a unidade omitida é preenchida por ele.

dimension_3d · largura, altura e profundidade

O mesmo modelo com o eixo extra depth. Para móveis, eletrodomésticos e qualquer produto com volume relevante na ficha técnica.

{ "id": 12, "width": 20, "height": 30, "depth": 10, "unit": "cm" }

• Mesmas regras do dimension_2d, com depth também numérico e obrigatório.

Tipos visuais

Três tipos em que a apresentação faz parte do valor: cor, imagem e marca. São os candidatos naturais a atributo de variação e a atributo principal na hora de agrupar fotos por variação.

color · cor

Cor com nome comercial (value), agrupador main_color (alimenta os filtros da vitrine: "Azul" agrupa "Azul Royal", "Azul Petróleo"...), código hex e brightness (light/dark, usado pelo front para escolher texto contrastante sobre a amostra).

// opção pré-cadastrada
{ "id": 14, "value_id": 87 }

// cor livre (customizada)
{ "id": 14, "value": "Azul Petróleo", "hex": "#0F4C5C" }

• Na cor livre, value + hex bastam. O hex aceita #RGB ou #RRGGBB.
• main_color e brightness são opcionais; brightness é calculada a partir do hex quando omitida.
• Vale tanto em attributes[] quanto em variations[].attributes[].
• Em combine-attributes, envie a cor livre como objeto com "custom": true.

image · estampa ou textura

Aqui a imagem é o valor: estampas, texturas e padrões visuais que diferenciam variações. Cada valor pareia uma descrição textual (value) a uma imagem obrigatória, resolvida pelo domínio de Mídia.

// os valores vêm das opções pré-cadastradas do atributo
{ "id": 18, "value_id": 42 }

• value (descrição) e image (ID de imagem) são obrigatórios em cada opção; diferente da marca, aqui a imagem nunca é opcional.
• Os valores são opções pré-cadastradas: escolha pelo value_id retornado em value_definition.options.

brand · marca

Nome da marca com logo opcional. Quando a opção tem logo, a vitrine exibe a imagem junto ao nome; sem logo, só o texto.

// pelo ID da opção
{ "id": 2, "value_id": 3 }

// ou pelo nome exato de uma opção existente
{ "id": 2, "value": "HyperX" }

• Em cada opção, value (nome) é obrigatório; image (ID da imagem do logo) e alt (texto alternativo) são opcionais.
• Marcas alimentam a página da marca e o catálogo automático da vitrine, então use sempre a opção cadastrada em vez de variar a grafia.

packaging · embalagem

Quantidade pareada ao tipo físico de embalagem. A lista de tipos é fixa da plataforma:

{ "id": 3, "value": 12, "unit": "box" }

• value é numérico e obrigatório; unit deve ser um dos códigos da tabela acima.

Resumo rápido de payloads

Cola de referência com um exemplo válido por tipo:

[
  { "id": 7,  "value": "Algodão" },                                  // default (texto livre)
  { "id": 7,  "value_id": 21 },                                      // default (opção pré-cadastrada)
  { "id": 5,  "value": 350, "unit": "ml" },                          // default_unit
  { "id": 9,  "items": ["Cabo USB", "Manual"] },                     // default_list
  { "id": 11, "width": 120, "height": 80, "unit": "cm" },            // dimension_2d
  { "id": 12, "width": 20, "height": 30, "depth": 10, "unit": "cm" },// dimension_3d
  { "id": 14, "value": "Azul Petróleo", "hex": "#0F4C5C" },          // color (cor livre)
  { "id": 18, "value_id": 42 },                                      // image
  { "id": 2,  "value_id": 3 },                                       // brand
  { "id": 3,  "value": 12, "unit": "box" }                           // packaging
]

O passo seguinte é montar esses valores em attributes[] e variations[].attributes[] do anúncio: veja Atributos e variações e a etapa de criação.