Alterar característica

Altera os dados de uma característica existente: nome, exibição, filtro, categorias, status e traduções.

Use esta operação para renomear uma característica, ligar ou desligar o filtro, restringir a categorias, ocultá-la ou gravar traduções. As alterações valem para todos os produtos que já têm valor nela. Para mexer nas opções (Vermelho, P, M), use Opções de uma característica.

Só os campos enviados mudam; os demais ficam como estão. Isso vale também para PUT: ele não substitui a característica inteira, é uma alteração parcial igual ao PATCH. O tipo (feature_type) não pode ser alterado depois de criado: para mudar o tipo, crie uma nova característica.

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

Exige o privilégio manage_features. Alteração parcial: envie só o que muda. PATCH na mesma rota faz exatamente o mesmo.

Parâmetros de caminho

iduuidobrigatório

Id da característica.

Corpo da requisição

namestring

Novo nome, no idioma padrão. Único por tipo, sem diferenciar maiúsculas de minúsculas. Tags HTML são removidas.

codestring

Código interno.

group_iduuid

Move a característica para outro grupo.

descriptionstring

Descrição longa. Aceita HTML simples seguro.

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 vale para 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

Permite usar como filtro da vitrine.

comparableboolean

Inclui na tabela de comparação.

positioninteger

Posição de ordenação.

statusstring

AHDactivehiddendisabled

Status, em letra ou palavra.

descriptionsobject

Traduções a gravar. Chave é o código do idioma; valor é {"name": "...", "description": "..."}. Só os idiomas enviados mudam. Em grupo, só name conta. Não mexe nas colunas do idioma padrão.

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

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

Alterar característica (PATCH)

Mesmo comportamento, corpo e respostas de PUT /api/v1/admin/features/{id}.

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

Apelido em português: alterar característica (PUT)

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

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

Apelido em português: alterar característica (PATCH)

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

Exemplo de requisição

bash

curl -X PATCH "$BASE_URL/api/v1/admin/features/6d750dc5-6207-4809-9342-f9834c93a877" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "filterable": true,
    "display_on_catalog": true,
    "comparable": true,
    "descriptions": { "en": { "name": "Color", "description": "Product color" } }
  }'

Resposta

200Característica alterada

json

{
  "id": "6d750dc5-6207-4809-9342-f9834c93a877",
  "name": "Cor do produto",
  "code": "",
  "feature_type": "color",
  "description": "",
  "purpose": "",
  "prefix": "",
  "suffix": "",
  "categories_path": "",
  "display_on_product": false,
  "display_on_catalog": true,
  "filterable": true,
  "comparable": true,
  "position": 7,
  "status": "A",
  "variants": [
    {
      "id": "cef745f3-0270-4ddf-ae9d-b2fbe62cb11d",
      "feature_id": "6d750dc5-6207-4809-9342-f9834c93a877",
      "value": "vermelho",
      "code": "",
      "position": 0,
      "color": "#FF0000",
      "created_at": "2026-10-11T20:50:08.512903Z",
      "variant_id": "cef745f3-0270-4ddf-ae9d-b2fbe62cb11d",
      "variant": "vermelho",
      "timestamp": 1791751808
    }
  ],
  "created_at": "2026-10-11T20:50:08.498114Z",
  "updated_at": "2026-10-11T20:50:41.220871Z",
  "feature_id": "6d750dc5-6207-4809-9342-f9834c93a877",
  "feature": "Cor do produto",
  "timestamp": 1791751808,
  "updated_timestamp": 1791751841
}

A resposta é a característica completa, no formato de Consultar característica.

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 `manage_features`	`{"error":"insufficient privileges","required":"manage_features"}`
409	Nome repetido para o mesmo tipo	`{"error":"failed to update feature","detail":"duplicate_feature_name: a feature named \"Cor\" already exists"}`
500	Característica inexistente, corpo sem campos, `id` que não é UUID	`{"error":"failed to update feature","detail":"feature not found"}` ou `"detail":"no fields to update"`

Veja também

Alterar característica

Altera os dados de uma característica existente: nome, exibição, filtro, categorias, status e traduções.

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

Alterar característica

Exige o privilégio manage_features. Alteração parcial: envie só o que muda. PATCH na mesma rota faz exatamente o mesmo.

Parâmetros de caminho

iduuidobrigatório

Id da característica.

Corpo da requisição

namestring

Novo nome, no idioma padrão. Único por tipo, sem diferenciar maiúsculas de minúsculas. Tags HTML são removidas.

codestring

Código interno.

group_iduuid

Move a característica para outro grupo.

descriptionstring

Descrição longa. Aceita HTML simples seguro.

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 vale para 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

Permite usar como filtro da vitrine.

comparableboolean

Inclui na tabela de comparação.

positioninteger

Posição de ordenação.

statusstring

AHDactivehiddendisabled

Status, em letra ou palavra.

descriptionsobject

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

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

Alterar característica (PATCH)

Mesmo comportamento, corpo e respostas de PUT /api/v1/admin/features/{id}.

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

Apelido em português: alterar característica (PUT)

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

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

Apelido em português: alterar característica (PATCH)

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

Exemplo de requisição

bash

curl -X PATCH "$BASE_URL/api/v1/admin/features/6d750dc5-6207-4809-9342-f9834c93a877" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "filterable": true,
    "display_on_catalog": true,
    "comparable": true,
    "descriptions": { "en": { "name": "Color", "description": "Product color" } }
  }'

Resposta

200Característica alterada

json

{
  "id": "6d750dc5-6207-4809-9342-f9834c93a877",
  "name": "Cor do produto",
  "code": "",
  "feature_type": "color",
  "description": "",
  "purpose": "",
  "prefix": "",
  "suffix": "",
  "categories_path": "",
  "display_on_product": false,
  "display_on_catalog": true,
  "filterable": true,
  "comparable": true,
  "position": 7,
  "status": "A",
  "variants": [
    {
      "id": "cef745f3-0270-4ddf-ae9d-b2fbe62cb11d",
      "feature_id": "6d750dc5-6207-4809-9342-f9834c93a877",
      "value": "vermelho",
      "code": "",
      "position": 0,
      "color": "#FF0000",
      "created_at": "2026-10-11T20:50:08.512903Z",
      "variant_id": "cef745f3-0270-4ddf-ae9d-b2fbe62cb11d",
      "variant": "vermelho",
      "timestamp": 1791751808
    }
  ],
  "created_at": "2026-10-11T20:50:08.498114Z",
  "updated_at": "2026-10-11T20:50:41.220871Z",
  "feature_id": "6d750dc5-6207-4809-9342-f9834c93a877",
  "feature": "Cor do produto",
  "timestamp": 1791751808,
  "updated_timestamp": 1791751841
}

A resposta é a característica completa, no formato de Consultar característica.

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 `manage_features`	`{"error":"insufficient privileges","required":"manage_features"}`
409	Nome repetido para o mesmo tipo	`{"error":"failed to update feature","detail":"duplicate_feature_name: a feature named \"Cor\" already exists"}`
500	Característica inexistente, corpo sem campos, `id` que não é UUID	`{"error":"failed to update feature","detail":"feature not found"}` ou `"detail":"no fields to update"`