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

Alterar grupo

Altera o nome, a posição, o status ou as categorias de um grupo de características, incluindo as traduções do nome.

Use esta operação para renomear um grupo, reordenar os blocos da ficha técnica, ocultar um grupo ou gravar o nome em outro idioma. PUT e PATCH fazem exatamente a mesma coisa: ambos são alterações parciais, e só os campos enviados mudam. O feature_type fica sempre em group, qualquer que seja o corpo.

PATCH/api/v1/admin/feature-groups/{id}Admin

Alterar um grupo de características (PATCH)

Exige o privilégio manage_features. Responde 200 com o grupo inteiro.

Parâmetros de caminho

iduuidobrigatório

Id do grupo.

Corpo da requisição

namestring

Novo nome, no idioma padrão. Único entre os grupos, sem diferenciar maiúsculas de minúsculas.

codestring

Código interno.

descriptionstring

Descrição do grupo.

categories_pathstring

Ids de categoria separados por vírgula. Vazio vale para todas as categorias. Não é repassado às características que já estão no grupo.

display_on_productboolean

Mostra o bloco na página do produto.

positioninteger

Posição de ordenação.

statusstring

AHDactivehiddendisabled

Status, em letra ou palavra.

descriptionsobject

Traduções do nome. Chave é o código do idioma; o valor é {"name": "..."}. Só os idiomas enviados mudam.

Pelo menos um campo é obrigatório. Um corpo {} volta 500 com no fields to update.

PUT/api/v1/admin/feature-groups/{id}Admin

Alterar um grupo de características (PUT)

Mesmo comportamento, corpo e respostas do PATCH acima. O PUT não substitui o grupo inteiro.

PATCH/api/v1/admin/characteristic-groups/{id}Admin

Apelido em português: alterar um grupo (PATCH)

Apelido de /api/v1/admin/feature-groups/{id}: mesmo corpo e mesmas regras.

PUT/api/v1/admin/characteristic-groups/{id}Admin

Apelido em português: alterar um grupo (PUT)

Apelido de /api/v1/admin/feature-groups/{id}: mesmo corpo e mesmas regras.

Exemplo de requisição

bash

curl -X PATCH "$BASE_URL/api/v1/admin/feature-groups/7c1221b4-ddb6-468c-b17e-be1dc5e7c888" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Dimensões e peso", "position": 31, "descriptions": { "en": { "name": "Size and weight" } } }'

Resposta

200Grupo alterado

json

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

Os campos são os de Listar grupos.

Erros

Status	Quando	Corpo
400	Corpo que não é JSON	`{"error":"invalid request body","detail":"..."}`
400	Nome vazio depois de remover o HTML	`{"error":"failed to update 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 outro grupo com esse nome	`{"error":"failed to update feature","detail":"duplicate_group_name: a group named \"Dimensões\" already exists"}`
500	Grupo inexistente, corpo sem campos, ou `id` que não é UUID	`{"error":"failed to update feature","detail":"feature not found"}` ou `"detail":"no fields to update"`

Veja também

Alterar grupo

Altera o nome, a posição, o status ou as categorias de um grupo de características, incluindo as traduções do nome.

PATCH/api/v1/admin/feature-groups/{id}Admin

Alterar um grupo de características (PATCH)

Exige o privilégio manage_features. Responde 200 com o grupo inteiro.

Parâmetros de caminho

iduuidobrigatório

Id do grupo.

Corpo da requisição

namestring

Novo nome, no idioma padrão. Único entre os grupos, sem diferenciar maiúsculas de minúsculas.

codestring

Código interno.

descriptionstring

Descrição do grupo.

categories_pathstring

Ids de categoria separados por vírgula. Vazio vale para todas as categorias. Não é repassado às características que já estão no grupo.

display_on_productboolean

Mostra o bloco na página do produto.

positioninteger

Posição de ordenação.

statusstring

AHDactivehiddendisabled

Status, em letra ou palavra.

descriptionsobject

Traduções do nome. Chave é o código do idioma; o valor é {"name": "..."}. Só os idiomas enviados mudam.

Pelo menos um campo é obrigatório. Um corpo {} volta 500 com no fields to update.

PUT/api/v1/admin/feature-groups/{id}Admin

Alterar um grupo de características (PUT)

Mesmo comportamento, corpo e respostas do PATCH acima. O PUT não substitui o grupo inteiro.

PATCH/api/v1/admin/characteristic-groups/{id}Admin

Apelido em português: alterar um grupo (PATCH)

Apelido de /api/v1/admin/feature-groups/{id}: mesmo corpo e mesmas regras.

PUT/api/v1/admin/characteristic-groups/{id}Admin

Apelido em português: alterar um grupo (PUT)

Apelido de /api/v1/admin/feature-groups/{id}: mesmo corpo e mesmas regras.

Exemplo de requisição

bash

curl -X PATCH "$BASE_URL/api/v1/admin/feature-groups/7c1221b4-ddb6-468c-b17e-be1dc5e7c888" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Dimensões e peso", "position": 31, "descriptions": { "en": { "name": "Size and weight" } } }'

Resposta

200Grupo alterado

json

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

Os campos são os de Listar grupos.

Erros

Status	Quando	Corpo
400	Corpo que não é JSON	`{"error":"invalid request body","detail":"..."}`
400	Nome vazio depois de remover o HTML	`{"error":"failed to update 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 outro grupo com esse nome	`{"error":"failed to update feature","detail":"duplicate_group_name: a group named \"Dimensões\" already exists"}`
500	Grupo inexistente, corpo sem campos, ou `id` que não é UUID	`{"error":"failed to update feature","detail":"feature not found"}` ou `"detail":"no fields to update"`