API atual/Referência completa/Características

Criar característica

Cadastra uma nova característica de produto (como Cor, Tamanho ou Marca)

Use esta operação para cadastrar um atributo novo: "Cor", "Voltagem", "Material", "Peso". Depois de criada, a característica ainda não aparece em nenhum produto: o valor é informado em cada produto, e as opções das características de lista (Vermelho, Azul) são criadas com Opções de uma característica.

Antes de criar, confira se a loja já tem a característica. Ao cadastrar a loja, a plataforma pode ter criado um conjunto padrão (veja Características padrão), e o nome de uma característica é único por tipo.

POST/api/v1/admin/featuresAdmin

Exige o privilégio manage_features. Responde 201 com a característica criada (sem opções; crie-as em seguida).

Corpo da requisição

namestringobrigatório

Nome, no idioma padrão da loja. Tags HTML são removidas. Único por tipo, sem diferenciar maiúsculas de minúsculas.

feature_typestringobrigatório

selectmulti_selecttextnumberdateboolgroupbrandauthorcolor

Tipo da característica. Veja os tipos na home da seção.

codestring

Código interno para uso por programas (color, voltage). Opcional.

group_iduuid

Grupo ao qual a característica pertence. Quando informado, o categories_path do grupo substitui o que você enviar.

descriptionstring

Descrição longa. Aceita HTML simples seguro (negrito, itálico, links).

purposestringpadrão:

group_catalog_itemgroup_variation_catalog_item

Ligação com variações de produto. Outro valor volta 500.

prefixstring

Prefixo exibido junto ao valor (R$).

suffixstring

Sufixo exibido junto ao valor (kg, cm).

categories_pathstringpadrão:

Ids de categoria separados por vírgula. Vazio vale para todas as categorias.

display_on_productbooleanpadrão: false

Mostra o valor na página do produto.

display_on_catalogbooleanpadrão: false

Mostra o valor como selo nos cartões de produto.

filterablebooleanpadrão: false

Permite usar como filtro da vitrine (só nos tipos de lista).

comparablebooleanpadrão: false

Inclui na tabela de comparação.

positionintegerpadrão: 0

Posição de ordenação.

descriptionsobject

Traduções. Chave é o código do idioma (en, es, pt-BR); o valor é {"name": "...", "description": "..."}. Idiomas ausentes ficam com o nome e a descrição do idioma padrão.

A característica nasce com status igual a A (ativa). Para ocultá-la, use Alterar característica.

POST/api/v1/admin/characteristicsAdmin

Apelido em português: criar característica

Apelido de /api/v1/admin/features: mesmo corpo, mesmas regras.

Exemplo de requisição

Resposta

201Característica criada

Os campos são os de Consultar característica.

Erros

Status	Quando	Corpo
400	Corpo que não é JSON	`{"error":"invalid request body","detail":"..."}`
400	`name` ou `feature_type` ausentes	`{"error":"name is required"}` ou `{"error":"feature_type is required"}`
400	Nome vazio depois de remover o HTML	`{"error":"failed to create feature","detail":"name_required: feature name must not be empty after sanitization"}`
401	Sem credenciais ou token expirado	`{"error":"missing authorization header"}`
403	Sem `manage_features`	`{"error":"insufficient privileges","required":"manage_features"}`
409	Nome repetido para o mesmo tipo	`{"error":"failed to create feature","detail":"duplicate_feature_name: a feature named \"Voltagem\" already exists"}`
500	`feature_type` ou `purpose` inválidos	`{"error":"failed to create feature","detail":"invalid feature type: zzz"}`

Veja também

Criar característica

Cadastra uma nova característica de produto (como Cor, Tamanho ou Marca)

POST/api/v1/admin/featuresAdmin

Criar característica

Exige o privilégio manage_features. Responde 201 com a característica criada (sem opções; crie-as em seguida).

Corpo da requisição

namestringobrigatório

Nome, no idioma padrão da loja. Tags HTML são removidas. Único por tipo, sem diferenciar maiúsculas de minúsculas.

feature_typestringobrigatório

selectmulti_selecttextnumberdateboolgroupbrandauthorcolor

Tipo da característica. Veja os tipos na home da seção.

codestring

Código interno para uso por programas (color, voltage). Opcional.

group_iduuid

Grupo ao qual a característica pertence. Quando informado, o categories_path do grupo substitui o que você enviar.

descriptionstring

Descrição longa. Aceita HTML simples seguro (negrito, itálico, links).

purposestringpadrão:

group_catalog_itemgroup_variation_catalog_item

Ligação com variações de produto. Outro valor volta 500.

prefixstring

Prefixo exibido junto ao valor (R$).

suffixstring

Sufixo exibido junto ao valor (kg, cm).

categories_pathstringpadrão:

Ids de categoria separados por vírgula. Vazio vale para todas as categorias.

display_on_productbooleanpadrão: false

Mostra o valor na página do produto.

display_on_catalogbooleanpadrão: false

Mostra o valor como selo nos cartões de produto.

filterablebooleanpadrão: false

Permite usar como filtro da vitrine (só nos tipos de lista).

comparablebooleanpadrão: false

Inclui na tabela de comparação.

positionintegerpadrão: 0

Posição de ordenação.

descriptionsobject

Traduções. Chave é o código do idioma (en, es, pt-BR); o valor é {"name": "...", "description": "..."}. Idiomas ausentes ficam com o nome e a descrição do idioma padrão.

A característica nasce com status igual a A (ativa). Para ocultá-la, use Alterar característica.

POST/api/v1/admin/characteristicsAdmin

Apelido em português: criar característica

Apelido de /api/v1/admin/features: mesmo corpo, mesmas regras.

Status	Quando	Corpo
400	Corpo que não é JSON	`{"error":"invalid request body","detail":"..."}`
400	`name` ou `feature_type` ausentes	`{"error":"name is required"}` ou `{"error":"feature_type is required"}`
400	Nome vazio depois de remover o HTML	`{"error":"failed to create feature","detail":"name_required: feature name must not be empty after sanitization"}`
401	Sem credenciais ou token expirado	`{"error":"missing authorization header"}`
403	Sem `manage_features`	`{"error":"insufficient privileges","required":"manage_features"}`
409	Nome repetido para o mesmo tipo	`{"error":"failed to create feature","detail":"duplicate_feature_name: a feature named \"Voltagem\" already exists"}`
500	`feature_type` ou `purpose` inválidos	`{"error":"failed to create feature","detail":"invalid feature type: zzz"}`