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

bash

curl -X POST "$BASE_URL/api/v1/admin/features" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Voltagem",
    "feature_type": "select",
    "display_on_product": true,
    "filterable": true,
    "comparable": true,
    "position": 40,
    "descriptions": { "en": { "name": "Voltage", "description": "Operating voltage" } }
  }'

Resposta

201Característica criada

json

{
  "id": "36d53e33-2e76-49fa-ac05-ccceab9ea691",
  "name": "Voltagem",
  "code": "",
  "feature_type": "select",
  "description": "",
  "purpose": "",
  "prefix": "",
  "suffix": "",
  "categories_path": "",
  "display_on_product": true,
  "display_on_catalog": false,
  "filterable": true,
  "comparable": true,
  "position": 40,
  "status": "A",
  "created_at": "2026-10-11T20:50:37.374209Z",
  "updated_at": "2026-10-11T20:50:37.374209Z",
  "feature_id": "36d53e33-2e76-49fa-ac05-ccceab9ea691",
  "feature": "Voltagem",
  "timestamp": 1791751837,
  "updated_timestamp": 1791751837
}

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.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/admin/features" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Voltagem",
    "feature_type": "select",
    "display_on_product": true,
    "filterable": true,
    "comparable": true,
    "position": 40,
    "descriptions": { "en": { "name": "Voltage", "description": "Operating voltage" } }
  }'

Resposta

201Característica criada

json

{
  "id": "36d53e33-2e76-49fa-ac05-ccceab9ea691",
  "name": "Voltagem",
  "code": "",
  "feature_type": "select",
  "description": "",
  "purpose": "",
  "prefix": "",
  "suffix": "",
  "categories_path": "",
  "display_on_product": true,
  "display_on_catalog": false,
  "filterable": true,
  "comparable": true,
  "position": 40,
  "status": "A",
  "created_at": "2026-10-11T20:50:37.374209Z",
  "updated_at": "2026-10-11T20:50:37.374209Z",
  "feature_id": "36d53e33-2e76-49fa-ac05-ccceab9ea691",
  "feature": "Voltagem",
  "timestamp": 1791751837,
  "updated_timestamp": 1791751837
}

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"}`