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

Criar grupo

Cria um grupo de características, como Dimensões ou Especificações Técnicas, para organizar a ficha técnica dos produtos.

Use esta operação para criar o título que vai reunir características. O grupo nasce vazio: depois, crie as características dele com group_id em Criar característica. Se você quer que todas as características do bloco valham só para algumas categorias, defina categories_path no grupo antes de criar as filhas, porque elas copiam esse valor na criação.

POST/api/v1/admin/feature-groupsAdmin

Criar um grupo de características

Responde 201 com o grupo criado. O feature_type é fixado em group, mesmo que você envie outro valor. Exige o privilégio manage_features.

Corpo da requisição

namestringobrigatório

Nome do grupo, no idioma padrão. Tags HTML são removidas. Único entre os grupos, sem diferenciar maiúsculas de minúsculas.

descriptionstring

Descrição do grupo.

codestring

Código interno para uso por programas.

categories_pathstringpadrão:

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

display_on_productbooleanpadrão: false

Mostra o bloco na página do produto.

positionintegerpadrão: 0

Posição de ordenação.

descriptionsobject

Traduções do nome. Chave é o código do idioma; o valor é {"name": "..."}. Em grupo, só o nome é gravado.

POST/api/v1/admin/characteristic-groupsAdmin

Apelido em português: criar um grupo de características

Apelido de /api/v1/admin/feature-groups: mesmo corpo, mesmas regras.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/admin/feature-groups" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Dimensões da embalagem",
    "display_on_product": true,
    "position": 35,
    "descriptions": { "en": { "name": "Package dimensions" } }
  }'

Resposta

201Grupo criado

json

{
  "id": "7c1221b4-ddb6-468c-b17e-be1dc5e7c888",
  "name": "Dimensões da embalagem",
  "code": "",
  "feature_type": "group",
  "description": "",
  "purpose": "",
  "prefix": "",
  "suffix": "",
  "categories_path": "",
  "display_on_product": true,
  "display_on_catalog": false,
  "filterable": false,
  "comparable": false,
  "position": 35,
  "status": "A",
  "created_at": "2026-10-11T20:50:37.374209Z",
  "updated_at": "2026-10-11T20:50:37.374209Z",
  "feature_id": "7c1221b4-ddb6-468c-b17e-be1dc5e7c888",
  "feature": "Dimensões da embalagem",
  "timestamp": 1791751837,
  "updated_timestamp": 1791751837
}

Os campos são os de Listar grupos. Guarde o id: é o group_id das características filhas.

Erros

Status	Quando	Corpo
400	Corpo que não é JSON	`{"error":"invalid request body","detail":"..."}`
400	`name` ausente	`{"error":"name 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 o privilégio `manage_features`	`{"error":"insufficient privileges","required":"manage_features"}`
409	Já existe um grupo com esse nome	`{"error":"failed to create feature","detail":"duplicate_group_name: a group named \"Dimensões da embalagem\" already exists"}`

Veja também