API atual/Guia rápido/Grupos de características

Listar grupos

Retorna os grupos de características da loja, com busca, filtros e paginação.

Use esta operação para montar o seletor de grupos de uma tela de cadastro, ou para descobrir o id de um grupo antes de criar características dentro dele. É o mesmo que listar características com o tipo fixado em group.

GET/api/v1/admin/feature-groupsAdmin

Listar grupos de características

Ordenada por position e depois por nome. Exige o privilégio manage_features. O parâmetro feature_type, se enviado, é ignorado: o tipo é sempre group.

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.

statusstring

AHDactivehiddendisabled

Filtra por status, em letra ou palavra.

searchstring

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

category_idstring

Somente os grupos que valem para esta categoria (os de categories_path vazio e os que contêm o id).

GET/api/v1/admin/characteristic-groupsAdmin

Apelido em português: listar grupos de características

Apelido de /api/v1/admin/feature-groups: mesmos parâmetros e mesma resposta.

Exemplo de requisição

bash

curl "$BASE_URL/api/v1/admin/feature-groups?per_page=50" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Grupos retornados

json

{
  "features": [
    {
      "id": "734326ad-8530-43ce-966e-6ec26f0f26de",
      "name": "Dimensões",
      "code": "dimensions",
      "feature_type": "group",
      "description": "Largura, altura, profundidade e peso",
      "purpose": "",
      "prefix": "",
      "suffix": "",
      "categories_path": "",
      "display_on_product": true,
      "display_on_catalog": false,
      "filterable": false,
      "comparable": true,
      "position": 30,
      "status": "A",
      "created_at": "2026-04-29T19:57:53.005899Z",
      "updated_at": "2026-04-29T19:57:53.005899Z",
      "feature_id": "734326ad-8530-43ce-966e-6ec26f0f26de",
      "feature": "Dimensões",
      "timestamp": 1777492673,
      "updated_timestamp": 1777492673
    }
  ],
  "total": 8,
  "page": 1,
  "per_page": 20,
  "total_pages": 1
}

Campos da resposta

featuresarray

Os grupos da página. A chave é features, não groups.

features[].iduuid

Id do grupo. É o valor de group_id nas características filhas. O campo feature_id repete o valor.

features[].namestring

Nome do grupo, no idioma padrão. O campo feature repete o valor.

features[].codestring

Código interno. Pode ser vazio.

features[].feature_typestring

group

Sempre group.

features[].descriptionstring

Descrição do grupo.

features[].categories_pathstring

Ids de categoria separados por vírgula. As características criadas no grupo herdam este valor. Vazio vale para todas.

features[].display_on_productboolean

Mostra o bloco na página do produto.

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.

totalinteger

Total de grupos que atendem ao filtro.

pageinteger

Página retornada.

per_pageinteger

Itens por página aplicados.

total_pagesinteger

Quantidade de páginas.

Os demais campos (purpose, prefix, suffix, display_on_catalog, filterable, comparable, timestamp, updated_timestamp) existem em todo item, mas não têm significado prático em um grupo.

Erros

Status	Quando	Corpo
401	Sem credenciais ou token expirado	`{"error":"missing authorization header"}` ou `{"error":"invalid or expired token"}`
403	Sem o privilégio `manage_features`	`{"error":"insufficient privileges","required":"manage_features"}`
429	Limite de requisições	`{"error":"rate limit exceeded","detail":"too many requests, please try again later"}`
500	Falha interna	`{"error":"failed to list features","detail":"..."}`

Veja também