Listar características

Retorna as características cadastradas na loja, com filtros por tipo, status, grupo e categoria, e paginação.

Use esta operação para ler o cadastro de características da loja: montar uma tela de administração, sincronizar o catálogo com um ERP ou descobrir o id de uma característica antes de gravar valores em produtos. A lista traz a definição de cada característica (nome, tipo, onde aparece, a que grupo pertence). Ela não traz as opções (as variantes) nem os valores dos produtos. Para as opções, use Consultar característica ou Opções de uma característica.

A lista mistura características comuns e grupos (feature_type igual a group). Para ver só os grupos, use Listar grupos.

GET/api/v1/admin/featuresAdmin

Ordenada por position e depois por nome. Exige o privilégio manage_features.

Parâmetros de consulta

pageintegerpadrão: 1

Página, a partir de 1.

per_pageintegerpadrão: 20

Itens por página, de 1 a 100. Valor acima de 100 vira 100; zero ou negativo vira 20.

feature_typestring

selectmulti_selecttextnumberdateboolgroupbrandauthorcolor

Filtra por tipo.

statusstring

AHDactivehiddendisabled

Filtra por status. Aceita a letra ou a palavra.

group_iduuid

Somente as características filhas deste grupo.

category_idstring

Somente as que valem para esta categoria: as de categories_path vazio (todas as categorias) e as que contêm o id da categoria. A busca é por trecho de texto, sem considerar subcategorias.

searchstring

Busca por trecho no nome ou na descrição, sem diferenciar maiúsculas de minúsculas.

GET/api/v1/admin/characteristicsAdmin

Apelido em português: listar características

Apelido de /api/v1/admin/features: mesmos parâmetros, mesmo corpo, mesmas regras.

Exemplo de requisição

bash

curl "$BASE_URL/api/v1/admin/features?feature_type=select&per_page=50" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Características retornadas

json

{
  "features": [
    {
      "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",
      "created_at": "2026-04-29T19:57:53.063048Z",
      "updated_at": "2026-04-29T19:57:53.063048Z",
      "feature_id": "a827c238-e0ce-4ff3-9655-478b5e3adf1b",
      "feature": "Tamanho",
      "timestamp": 1777492673,
      "updated_timestamp": 1777492673
    }
  ],
  "total": 32,
  "page": 1,
  "per_page": 20,
  "total_pages": 2
}

Campos da resposta

featuresarray

Características da página. Sem o campo variants.

features[].iduuid

Id da característica.

features[].group_iduuid

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

features[].namestring

Nome, no idioma padrão da loja.

features[].codestring

Código interno, para uso por programas (size, weight). Pode ser vazio.

features[].feature_typestring

selectmulti_selecttextnumberdateboolgroupbrandauthorcolor

Tipo da característica.

features[].descriptionstring

Descrição longa, no idioma padrão. Pode conter HTML simples (negrito, itálico, links).

features[].purposestring

group_catalog_itemgroup_variation_catalog_item

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

features[].prefixstring

Prefixo de exibição do valor.

features[].suffixstring

Sufixo de exibição do valor (kg, cm).

features[].categories_pathstring

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

features[].display_on_productboolean

Mostra o valor na página do produto.

features[].display_on_catalogboolean

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

features[].filterableboolean

Pode ser usada como filtro da vitrine (apenas nos tipos de lista).

features[].comparableboolean

Entra na tabela de comparação de produtos.

features[].positioninteger

Posição de ordenação.

features[].statusstring

AHD

Letra de status.

features[].created_atstring

Criação, RFC 3339 em UTC.

features[].updated_atstring

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

features[].feature_iduuid

Repete id.

features[].featurestring

Repete name.

features[].timestampinteger

Criação em Unix timestamp (segundos).

features[].updated_timestampinteger

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

totalinteger

Total de características que atendem ao filtro, em todas as páginas.

pageinteger

Página retornada.

per_pageinteger

Itens por página aplicados.

total_pagesinteger

Quantidade de páginas.

Erros

Status	Quando	Corpo
401	Sem credenciais, chave de API inválida ou token expirado	`{"error":"missing authorization header"}` ou `{"error":"invalid or expired token"}`
403	Usuário sem o privilégio `manage_features`	`{"error":"insufficient privileges","required":"manage_features"}`
429	Limite de requisições (por exemplo, login repetido)	`{"error":"rate limit exceeded","detail":"too many requests, please try again later"}`
500	Falha interna, ou `group_id` que não é UUID	`{"error":"failed to list features","detail":"..."}`

Veja também

Listar características

Retorna as características cadastradas na loja, com filtros por tipo, status, grupo e categoria, e paginação.

A lista mistura características comuns e grupos (feature_type igual a group). Para ver só os grupos, use Listar grupos.

GET/api/v1/admin/featuresAdmin

Listar características

Ordenada por position e depois por nome. Exige o privilégio manage_features.

Parâmetros de consulta

pageintegerpadrão: 1

Página, a partir de 1.

per_pageintegerpadrão: 20

Itens por página, de 1 a 100. Valor acima de 100 vira 100; zero ou negativo vira 20.

feature_typestring

selectmulti_selecttextnumberdateboolgroupbrandauthorcolor

Filtra por tipo.

statusstring

AHDactivehiddendisabled

Filtra por status. Aceita a letra ou a palavra.

group_iduuid

Somente as características filhas deste grupo.

category_idstring

Somente as que valem para esta categoria: as de categories_path vazio (todas as categorias) e as que contêm o id da categoria. A busca é por trecho de texto, sem considerar subcategorias.

searchstring

Busca por trecho no nome ou na descrição, sem diferenciar maiúsculas de minúsculas.

GET/api/v1/admin/characteristicsAdmin

Apelido em português: listar características

Apelido de /api/v1/admin/features: mesmos parâmetros, mesmo corpo, mesmas regras.

Exemplo de requisição

bash

curl "$BASE_URL/api/v1/admin/features?feature_type=select&per_page=50" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Características retornadas

json

{
  "features": [
    {
      "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",
      "created_at": "2026-04-29T19:57:53.063048Z",
      "updated_at": "2026-04-29T19:57:53.063048Z",
      "feature_id": "a827c238-e0ce-4ff3-9655-478b5e3adf1b",
      "feature": "Tamanho",
      "timestamp": 1777492673,
      "updated_timestamp": 1777492673
    }
  ],
  "total": 32,
  "page": 1,
  "per_page": 20,
  "total_pages": 2
}

Campos da resposta

featuresarray

Características da página. Sem o campo variants.

features[].iduuid

Id da característica.

features[].group_iduuid

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

features[].namestring

Nome, no idioma padrão da loja.

features[].codestring

Código interno, para uso por programas (size, weight). Pode ser vazio.

features[].feature_typestring

selectmulti_selecttextnumberdateboolgroupbrandauthorcolor

Tipo da característica.

features[].descriptionstring

Descrição longa, no idioma padrão. Pode conter HTML simples (negrito, itálico, links).

features[].purposestring

group_catalog_itemgroup_variation_catalog_item

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

features[].prefixstring

Prefixo de exibição do valor.

features[].suffixstring

Sufixo de exibição do valor (kg, cm).

features[].categories_pathstring

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

features[].display_on_productboolean

Mostra o valor na página do produto.

features[].display_on_catalogboolean

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

features[].filterableboolean

Pode ser usada como filtro da vitrine (apenas nos tipos de lista).

features[].comparableboolean

Entra na tabela de comparação de produtos.

features[].positioninteger

Posição de ordenação.

features[].statusstring

AHD

Letra de status.

features[].created_atstring

Criação, RFC 3339 em UTC.

features[].updated_atstring

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

features[].feature_iduuid

Repete id.

features[].featurestring

Repete name.

features[].timestampinteger

Criação em Unix timestamp (segundos).

features[].updated_timestampinteger

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

totalinteger

Total de características que atendem ao filtro, em todas as páginas.

pageinteger

Página retornada.

per_pageinteger

Itens por página aplicados.

total_pagesinteger

Quantidade de páginas.

Erros

Status	Quando	Corpo
401	Sem credenciais, chave de API inválida ou token expirado	`{"error":"missing authorization header"}` ou `{"error":"invalid or expired token"}`
403	Usuário sem o privilégio `manage_features`	`{"error":"insufficient privileges","required":"manage_features"}`
429	Limite de requisições (por exemplo, login repetido)	`{"error":"rate limit exceeded","detail":"too many requests, please try again later"}`
500	Falha interna, ou `group_id` que não é UUID	`{"error":"failed to list features","detail":"..."}`