Ficha técnica da categoria

Lê e grava a lista de características (atributos) que os produtos de uma categoria devem preencher, cada uma marcada como obrigatória ou recomendada.

A ficha técnica de uma categoria é a lista de características que os produtos dela devem ter. Características (atributos como voltagem, material ou tamanho) são os campos estruturados do produto que alimentam os filtros da loja. Numa categoria "Ventiladores", a ficha pode pedir Voltagem (obrigatória) e Potência (recomendada).

A ficha não cria a característica: ela só escolhe quais características já cadastradas a categoria usa. As características em si são cadastradas na seção de características da plataforma. A marcação required entra no cálculo de qualidade do cadastro do produto: um produto da categoria que não preenche uma característica obrigatória perde pontos de completude.

GET/api/v1/admin/categories/{id}/feature-templateAdmin

Consulta o modelo de características de uma categoria

Parâmetros de caminho

iduuidobrigatório

Id da categoria.

PUT/api/v1/admin/categories/{id}/feature-templateAdmin

Substitui o modelo de características de uma categoria

Substitui a ficha inteira: as características que você não enviar saem da ficha. Para só acrescentar uma, leia a ficha, some o item e grave a lista completa. Enviar items vazio apaga a ficha própria da categoria (e ela volta a herdar da ancestral, se houver).

Parâmetros de caminho

iduuidobrigatório

Id da categoria.

Corpo da requisição

itemsarrayobrigatório

Características da ficha.

feature_iduuidobrigatório

Id da característica (veja a seção de características). Um valor que não é UUID dá erro.

requirementstringpadrão: recommended

requiredrecommended

required marca a característica como obrigatória; qualquer outro valor (inclusive ausente) vira recommended.

positioninteger

Ordem de exibição, a partir de 1. Se for 0 ou ausente, vale a posição do item na lista enviada.

Exemplo de requisição

bash

curl -X PUT "$BASE_URL/api/v1/admin/categories/b53fa6b9-a1a5-4862-9fac-cdc5585017c7/feature-template" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"items":[{"feature_id":"dfae5ba1-09d3-41c1-85dc-be137fb5b61c","requirement":"required","position":1}]}'

Resposta

200Ficha lida

json

{
  "items": [
    {
      "feature_id": "dfae5ba1-09d3-41c1-85dc-be137fb5b61c",
      "feature_name": "Material QA",
      "requirement": "required",
      "position": 1
    }
  ],
  "inherited_from": null
}

200Ficha gravada

json

{ "status": "ok" }

Campos da resposta

itemsarray

Características da ficha, em ordem de position. Vazio quando nem a categoria nem as ancestrais têm ficha.

items[].feature_iduuid

Id da característica.

items[].feature_namestring

Nome da característica.

items[].requirementstring

requiredrecommended

Obrigatória ou recomendada.

items[].positioninteger

Ordem de exibição.

inherited_fromuuid

Id da ancestral de onde a ficha foi herdada. null quando a ficha é da própria categoria (ou não existe).

statusstring

ok no PUT.

Erros

Status	Quando	Corpo
400	Corpo inválido	`{"error":"invalid body","detail":"..."}`
401	Token ausente ou expirado	`{"error":"invalid or expired token"}`
403	Sem o privilégio `manage_catalog`	`{"error":"insufficient privileges","privilege_required_any":["manage_catalog"]}`
500	`feature_id` ou `{id}` que não é UUID, ou característica inexistente	`{"error":"failed","detail":"o valor \"nope\" não é um uuid válido. Envie o identificador completo, com os 36 caracteres e os hífens. Corrija o campo e reenvie."}`

Veja também

Ficha técnica da categoria

Lê e grava a lista de características (atributos) que os produtos de uma categoria devem preencher, cada uma marcada como obrigatória ou recomendada.

GET/api/v1/admin/categories/{id}/feature-templateAdmin

Consulta o modelo de características de uma categoria

Parâmetros de caminho

iduuidobrigatório

Id da categoria.

PUT/api/v1/admin/categories/{id}/feature-templateAdmin

Substitui o modelo de características de uma categoria

Parâmetros de caminho

iduuidobrigatório

Id da categoria.

Corpo da requisição

itemsarrayobrigatório

Características da ficha.

feature_iduuidobrigatório

Id da característica (veja a seção de características). Um valor que não é UUID dá erro.

requirementstringpadrão: recommended

requiredrecommended

required marca a característica como obrigatória; qualquer outro valor (inclusive ausente) vira recommended.

positioninteger

Ordem de exibição, a partir de 1. Se for 0 ou ausente, vale a posição do item na lista enviada.

Exemplo de requisição

bash

curl -X PUT "$BASE_URL/api/v1/admin/categories/b53fa6b9-a1a5-4862-9fac-cdc5585017c7/feature-template" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"items":[{"feature_id":"dfae5ba1-09d3-41c1-85dc-be137fb5b61c","requirement":"required","position":1}]}'

Resposta

200Ficha lida

json

{
  "items": [
    {
      "feature_id": "dfae5ba1-09d3-41c1-85dc-be137fb5b61c",
      "feature_name": "Material QA",
      "requirement": "required",
      "position": 1
    }
  ],
  "inherited_from": null
}

200Ficha gravada

json

{ "status": "ok" }

Campos da resposta

itemsarray

Características da ficha, em ordem de position. Vazio quando nem a categoria nem as ancestrais têm ficha.

items[].feature_iduuid

Id da característica.

items[].feature_namestring

Nome da característica.

items[].requirementstring

requiredrecommended

Obrigatória ou recomendada.

items[].positioninteger

Ordem de exibição.

inherited_fromuuid

Id da ancestral de onde a ficha foi herdada. null quando a ficha é da própria categoria (ou não existe).

statusstring

ok no PUT.

Erros

Status	Quando	Corpo
400	Corpo inválido	`{"error":"invalid body","detail":"..."}`
401	Token ausente ou expirado	`{"error":"invalid or expired token"}`
403	Sem o privilégio `manage_catalog`	`{"error":"insufficient privileges","privilege_required_any":["manage_catalog"]}`
500	`feature_id` ou `{id}` que não é UUID, ou característica inexistente	`{"error":"failed","detail":"o valor \"nope\" não é um uuid válido. Envie o identificador completo, com os 36 caracteres e os hífens. Corrija o campo e reenvie."}`