Consultar característica

Retorna uma característica pelo id, com a lista completa de opções e, se pedido, as traduções do nome e da descrição.

Use esta operação quando já tem o id de uma característica (vindo de Listar características) e precisa do detalhe: as opções (variantes) que ela oferece, as cores das amostras, a que categorias e grupo ela pertence. É a única forma, junto com Opções de uma característica, de ler as opções junto da definição.

GET/api/v1/admin/features/{id}Admin

Consultar uma característica

Exige o privilégio manage_features.

Parâmetros de caminho

iduuidobrigatório

Id da característica.

Parâmetros de consulta

include_descriptionsstring

1

Com o valor 1, a resposta muda de formato: vem {"feature": {...}, "descriptions": {...}}, com o nome e a descrição em cada idioma da loja. Qualquer outro valor é ignorado.

GET/api/v1/admin/characteristics/{id}Admin

Apelido em português: consultar uma característica

Apelido de /api/v1/admin/features/{id}: mesmo parâmetro include_descriptions, mesmo corpo, mesmas regras.

Exemplo de requisição

bash

curl "$BASE_URL/api/v1/admin/features/a827c238-e0ce-4ff3-9655-478b5e3adf1b?include_descriptions=1" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Característica retornada (sem include_descriptions)

json

{
  "id": "a827c238-e0ce-4ff3-9655-478b5e3adf1b",
  "name": "Tamanho",
  "code": "size",
  "feature_type": "select",
  "description": "Tamanho de vestuário (letras)",
  "purpose": "group_catalog_item",
  "prefix": "",
  "suffix": "",
  "categories_path": "",
  "display_on_product": true,
  "display_on_catalog": true,
  "filterable": false,
  "comparable": true,
  "position": 20,
  "status": "A",
  "variants": [
    {
      "id": "1d13c44c-6575-403b-8ceb-e1cf37a5a862",
      "feature_id": "a827c238-e0ce-4ff3-9655-478b5e3adf1b",
      "value": "PP",
      "code": "xs",
      "position": 1,
      "created_at": "2026-04-29T19:57:53.063048Z",
      "variant_id": "1d13c44c-6575-403b-8ceb-e1cf37a5a862",
      "variant": "PP",
      "timestamp": 1777492673
    }
  ],
  "created_at": "2026-04-29T19:57:52.981203Z",
  "updated_at": "2026-04-29T19:57:52.981203Z",
  "feature_id": "a827c238-e0ce-4ff3-9655-478b5e3adf1b",
  "feature": "Tamanho",
  "timestamp": 1777492673,
  "updated_timestamp": 1777492673
}

200Com include_descriptions=1

json

{
  "feature": { "id": "a827c238-e0ce-4ff3-9655-478b5e3adf1b", "name": "Tamanho", "feature_type": "select", "status": "A" },
  "descriptions": {
    "pt-BR": { "lang_code": "pt-BR", "name": "Tamanho", "description": "Tamanho de vestuário (letras)" },
    "en": { "lang_code": "en", "name": "Size", "description": "Clothing size (letters)" }
  }
}

Campos da resposta

iduuid

Id da característica. Os campos feature_id repetem o mesmo valor.

group_iduuid

Id do grupo. Ausente quando a característica não tem grupo.

namestring

Nome, no idioma padrão da loja.

codestring

Código interno. Pode ser vazio.

feature_typestring

selectmulti_selecttextnumberdateboolgroupbrandauthorcolor

Tipo da característica.

descriptionstring

Descrição longa, no idioma padrão.

purposestring

group_catalog_itemgroup_variation_catalog_item

Ligação com variações de produto.

prefixstring

Prefixo de exibição.

suffixstring

Sufixo de exibição.

categories_pathstring

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

display_on_productboolean

Mostra o valor na página do produto.

display_on_catalogboolean

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

filterableboolean

Pode ser filtro da vitrine.

comparableboolean

Entra na tabela de comparação.

positioninteger

Posição de ordenação.

statusstring

AHD

Letra de status.

variantsarray

Opções da característica. Ausente quando não há nenhuma.

variants[].iduuid

Id da opção. variant_id repete o valor.

variants[].feature_iduuid

Característica dona da opção.

variants[].valuestring

Texto da opção. variant repete o valor.

variants[].codestring

Código interno da opção. Pode ser vazio.

variants[].positioninteger

Posição de ordenação.

variants[].image_urlstring

Imagem da opção (amostra, logotipo). Ausente quando não há.

variants[].colorstring

Cor em hexadecimal. Ausente quando não há.

variants[].created_atstring

Criação da opção, RFC 3339 em UTC.

created_atstring

Criação, RFC 3339 em UTC.

updated_atstring

Última alteração, RFC 3339 em UTC.

featurestring

Repete name.

timestampinteger

Criação em Unix timestamp (segundos).

updated_timestampinteger

Última alteração em Unix timestamp (segundos).

descriptionsobject

Só com include_descriptions=1. Chaves são códigos de idioma; cada valor tem lang_code, name e description. Em grupo, só name é traduzido.

Erros

Status	Quando	Corpo
401	Sem credenciais, chave inválida ou token expirado	`{"error":"missing authorization header"}`
403	Sem o privilégio `manage_features`	`{"error":"insufficient privileges","required":"manage_features"}`
404	Nenhuma característica com esse id	`{"error":"feature not found"}`
500	`id` que não é um UUID válido	`{"error":"failed to get feature","detail":"o valor \"abc\" não é um uuid válido. Envie o identificador completo, com os 36 caracteres e os hífens. Corrija o campo e reenvie."}`

Veja também

Consultar característica

Retorna uma característica pelo id, com a lista completa de opções e, se pedido, as traduções do nome e da descrição.

GET/api/v1/admin/features/{id}Admin

Consultar uma característica

Exige o privilégio manage_features.

Parâmetros de caminho

iduuidobrigatório

Id da característica.

Parâmetros de consulta

include_descriptionsstring

1

Com o valor 1, a resposta muda de formato: vem {"feature": {...}, "descriptions": {...}}, com o nome e a descrição em cada idioma da loja. Qualquer outro valor é ignorado.

GET/api/v1/admin/characteristics/{id}Admin

Apelido em português: consultar uma característica

Apelido de /api/v1/admin/features/{id}: mesmo parâmetro include_descriptions, mesmo corpo, mesmas regras.

Exemplo de requisição

bash

curl "$BASE_URL/api/v1/admin/features/a827c238-e0ce-4ff3-9655-478b5e3adf1b?include_descriptions=1" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Característica retornada (sem include_descriptions)

json

{
  "id": "a827c238-e0ce-4ff3-9655-478b5e3adf1b",
  "name": "Tamanho",
  "code": "size",
  "feature_type": "select",
  "description": "Tamanho de vestuário (letras)",
  "purpose": "group_catalog_item",
  "prefix": "",
  "suffix": "",
  "categories_path": "",
  "display_on_product": true,
  "display_on_catalog": true,
  "filterable": false,
  "comparable": true,
  "position": 20,
  "status": "A",
  "variants": [
    {
      "id": "1d13c44c-6575-403b-8ceb-e1cf37a5a862",
      "feature_id": "a827c238-e0ce-4ff3-9655-478b5e3adf1b",
      "value": "PP",
      "code": "xs",
      "position": 1,
      "created_at": "2026-04-29T19:57:53.063048Z",
      "variant_id": "1d13c44c-6575-403b-8ceb-e1cf37a5a862",
      "variant": "PP",
      "timestamp": 1777492673
    }
  ],
  "created_at": "2026-04-29T19:57:52.981203Z",
  "updated_at": "2026-04-29T19:57:52.981203Z",
  "feature_id": "a827c238-e0ce-4ff3-9655-478b5e3adf1b",
  "feature": "Tamanho",
  "timestamp": 1777492673,
  "updated_timestamp": 1777492673
}

200Com include_descriptions=1

json

{
  "feature": { "id": "a827c238-e0ce-4ff3-9655-478b5e3adf1b", "name": "Tamanho", "feature_type": "select", "status": "A" },
  "descriptions": {
    "pt-BR": { "lang_code": "pt-BR", "name": "Tamanho", "description": "Tamanho de vestuário (letras)" },
    "en": { "lang_code": "en", "name": "Size", "description": "Clothing size (letters)" }
  }
}

Campos da resposta

iduuid

Id da característica. Os campos feature_id repetem o mesmo valor.

group_iduuid

Id do grupo. Ausente quando a característica não tem grupo.

namestring

Nome, no idioma padrão da loja.

codestring

Código interno. Pode ser vazio.

feature_typestring

selectmulti_selecttextnumberdateboolgroupbrandauthorcolor

Tipo da característica.

descriptionstring

Descrição longa, no idioma padrão.

purposestring

group_catalog_itemgroup_variation_catalog_item

Ligação com variações de produto.

prefixstring

Prefixo de exibição.

suffixstring

Sufixo de exibição.

categories_pathstring

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

display_on_productboolean

Mostra o valor na página do produto.

display_on_catalogboolean

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

filterableboolean

Pode ser filtro da vitrine.

comparableboolean

Entra na tabela de comparação.

positioninteger

Posição de ordenação.

statusstring

AHD

Letra de status.

variantsarray

Opções da característica. Ausente quando não há nenhuma.

variants[].iduuid

Id da opção. variant_id repete o valor.

variants[].feature_iduuid

Característica dona da opção.

variants[].valuestring

Texto da opção. variant repete o valor.

variants[].codestring

Código interno da opção. Pode ser vazio.

variants[].positioninteger

Posição de ordenação.

variants[].image_urlstring

Imagem da opção (amostra, logotipo). Ausente quando não há.

variants[].colorstring

Cor em hexadecimal. Ausente quando não há.

variants[].created_atstring

Criação da opção, RFC 3339 em UTC.

created_atstring

Criação, RFC 3339 em UTC.

updated_atstring

Última alteração, RFC 3339 em UTC.

featurestring

Repete name.

timestampinteger

Criação em Unix timestamp (segundos).

updated_timestampinteger

Última alteração em Unix timestamp (segundos).

descriptionsobject

Só com include_descriptions=1. Chaves são códigos de idioma; cada valor tem lang_code, name e description. Em grupo, só name é traduzido.

Erros

Status	Quando	Corpo
401	Sem credenciais, chave inválida ou token expirado	`{"error":"missing authorization header"}`
403	Sem o privilégio `manage_features`	`{"error":"insufficient privileges","required":"manage_features"}`
404	Nenhuma característica com esse id	`{"error":"feature not found"}`
500	`id` que não é um UUID válido	`{"error":"failed to get feature","detail":"o valor \"abc\" não é um uuid válido. Envie o identificador completo, com os 36 caracteres e os hífens. Corrija o campo e reenvie."}`