API atual/Guia rápido/Conteúdo e características do produto

Características do produto

Lê as características de um produto e substitui todos os valores de uma vez.

Use estas rotas para preencher a ficha técnica de um produto: material, peso, marca, voltagem e o que mais a loja tiver cadastrado como característica. Antes de ler esta página, passe pela home da seção: ela explica o que é uma característica, os tipos e como cada tipo recebe o valor.

A API trabalha com valores: GET lista o que o produto tem e PUT substitui tudo pelo que você enviar.

GET/api/v1/admin/products/{id}/featuresAdmin

Lista os valores de características de um produto

Exige o privilégio manage_features. Devolve os valores gravados no produto, sem ordenação especial (ordem de criação).

Path parameters

iduuidobrigatório

Id do produto.

PUT/api/v1/admin/products/{id}/featuresAdmin

Substitui todos os valores de características de um produto

Exige o privilégio manage_features. Apaga todos os valores atuais do produto e grava a lista enviada. Lista vazia ({"values":[]}) limpa a ficha. Ao terminar, a vitrine é atualizada para refletir a mudança (listagens por marca e filtros incluídos).

Path parameters

iduuidobrigatório

Id do produto.

Corpo da requisição

valuesarrayobrigatório

Lista completa de valores do produto. No máximo um item por característica.

feature_iduuidobrigatório

Id da característica (definição). Liste as características da loja na seção de Características.

variant_iduuid

Id da opção escolhida, para select, multi_select, color, brand e author.

value_textstring

Texto livre (text), "true" ou "false" (bool), ou o nome ou código da opção no lugar de variant_id. Em brand e author, texto novo cria a opção.

value_numinteger

Número inteiro (number). Número com casas decimais é multiplicado por 100: 1.5 é gravado como 150.

value_datestring

Data AAAA-MM-DD (date).

Exemplo de requisição

bash

# Ler
curl "$BASE_URL/api/v1/admin/products/74dd8f08-8b06-43a8-9a8b-3ef5e7478d52/features" \
  -H "Authorization: Bearer $TOKEN"

# Substituir todos os valores
curl -X PUT "$BASE_URL/api/v1/admin/products/74dd8f08-8b06-43a8-9a8b-3ef5e7478d52/features" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "values": [
      { "feature_id": "9f77bf2e-b4ad-487a-ae9c-9547ac40cbc4", "value_text": "Corrida Leve 2026" },
      { "feature_id": "9e65272d-76ee-4e77-9dcb-9ff620d554b1", "value_num": 320 },
      { "feature_id": "093075db-b1ce-4dbb-8d1c-60d1b253a072", "variant_id": "d82d6649-bee7-40c5-b14f-6cb593bec904" }
    ]
  }'

Resposta

200Valores do produto (GET e PUT)

json

{
  "values": [
    {
      "id": "b8c5f7cc-f455-4957-9336-785be6cc2738",
      "product_id": "74dd8f08-8b06-43a8-9a8b-3ef5e7478d52",
      "feature_id": "9f77bf2e-b4ad-487a-ae9c-9547ac40cbc4",
      "value_text": "Corrida Leve 2026",
      "created_at": "2026-10-11T20:53:35.128433Z"
    },
    {
      "id": "328c8f3e-5580-495c-9a50-4ee39c0a39ab",
      "product_id": "74dd8f08-8b06-43a8-9a8b-3ef5e7478d52",
      "feature_id": "9e65272d-76ee-4e77-9dcb-9ff620d554b1",
      "value_num": 320,
      "created_at": "2026-10-11T20:53:35.132215Z"
    },
    {
      "id": "4c6433a7-ee5c-428f-839b-df851edf313a",
      "product_id": "74dd8f08-8b06-43a8-9a8b-3ef5e7478d52",
      "feature_id": "093075db-b1ce-4dbb-8d1c-60d1b253a072",
      "variant_id": "d82d6649-bee7-40c5-b14f-6cb593bec904",
      "created_at": "2026-10-11T20:53:35.134085Z"
    }
  ],
  "total": 3
}

Response fields

valuesarray

Valores do produto.

values[].iduuid

Id do registro de valor (muda a cada PUT).

values[].product_iduuid

O produto.

values[].feature_iduuid

A característica.

values[].variant_iduuid

A opção escolhida. Ausente nos tipos sem opção. Em brand e author vem preenchido mesmo quando você enviou só value_text.

values[].value_textstring

Texto, quando houve.

values[].value_numinteger

Número inteiro, quando houve.

values[].value_datestring

Data, quando houve.

values[].created_atstring

Quando o valor foi gravado (RFC 3339).

totalinteger

Quantidade de valores.

Erros

Status	Quando	Corpo
400	Corpo do `PUT` não é JSON válido	`{"error":"invalid request body","detail":"invalid character 'b' looking for beginning of object key string"}`
401	Sem credenciais ou token expirado	`{"error":"invalid or expired token"}`
403	Sem o privilégio `manage_features`	`{"error":"insufficient privileges","required":"manage_features"}`
500	Opção que não existe numa característica de seleção	`{"error":"failed to set product feature values","detail":"\"Alienigena\" não é um valor válido para a característica \"Gênero\". Valores aceitos: Masculino, Feminino, Unissex, Infantil"}`
500	`feature_id` que não existe	`{"error":"failed to set product feature values","detail":"o registro referenciado não existe ..."}`
500	`feature_id` ausente ou fora do formato UUID	`{"error":"failed to set product feature values","detail":"o valor \"\" não é um uuid válido ..."}`
500	A mesma característica duas vezes na lista	`{"error":"failed to set product feature values","detail":"já existe um registro com esse valor ..."}`

As mensagens de detail saem em português, como o servidor devolve. Todas as falhas de validação do PUT chegam como 500, não 400: leia o detail.

Veja também

Características do produto

Lê as características de um produto e substitui todos os valores de uma vez.

A API trabalha com valores: GET lista o que o produto tem e PUT substitui tudo pelo que você enviar.

GET/api/v1/admin/products/{id}/featuresAdmin

Lista os valores de características de um produto

Exige o privilégio manage_features. Devolve os valores gravados no produto, sem ordenação especial (ordem de criação).

Path parameters

iduuidobrigatório

Id do produto.

PUT/api/v1/admin/products/{id}/featuresAdmin

Substitui todos os valores de características de um produto

Path parameters

iduuidobrigatório

Id do produto.

Corpo da requisição

valuesarrayobrigatório

Lista completa de valores do produto. No máximo um item por característica.

feature_iduuidobrigatório

Id da característica (definição). Liste as características da loja na seção de Características.

variant_iduuid

Id da opção escolhida, para select, multi_select, color, brand e author.

value_textstring

Texto livre (text), "true" ou "false" (bool), ou o nome ou código da opção no lugar de variant_id. Em brand e author, texto novo cria a opção.

value_numinteger

Número inteiro (number). Número com casas decimais é multiplicado por 100: 1.5 é gravado como 150.

value_datestring

Data AAAA-MM-DD (date).

Exemplo de requisição

bash

# Ler
curl "$BASE_URL/api/v1/admin/products/74dd8f08-8b06-43a8-9a8b-3ef5e7478d52/features" \
  -H "Authorization: Bearer $TOKEN"

# Substituir todos os valores
curl -X PUT "$BASE_URL/api/v1/admin/products/74dd8f08-8b06-43a8-9a8b-3ef5e7478d52/features" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "values": [
      { "feature_id": "9f77bf2e-b4ad-487a-ae9c-9547ac40cbc4", "value_text": "Corrida Leve 2026" },
      { "feature_id": "9e65272d-76ee-4e77-9dcb-9ff620d554b1", "value_num": 320 },
      { "feature_id": "093075db-b1ce-4dbb-8d1c-60d1b253a072", "variant_id": "d82d6649-bee7-40c5-b14f-6cb593bec904" }
    ]
  }'

Resposta

200Valores do produto (GET e PUT)

json

{
  "values": [
    {
      "id": "b8c5f7cc-f455-4957-9336-785be6cc2738",
      "product_id": "74dd8f08-8b06-43a8-9a8b-3ef5e7478d52",
      "feature_id": "9f77bf2e-b4ad-487a-ae9c-9547ac40cbc4",
      "value_text": "Corrida Leve 2026",
      "created_at": "2026-10-11T20:53:35.128433Z"
    },
    {
      "id": "328c8f3e-5580-495c-9a50-4ee39c0a39ab",
      "product_id": "74dd8f08-8b06-43a8-9a8b-3ef5e7478d52",
      "feature_id": "9e65272d-76ee-4e77-9dcb-9ff620d554b1",
      "value_num": 320,
      "created_at": "2026-10-11T20:53:35.132215Z"
    },
    {
      "id": "4c6433a7-ee5c-428f-839b-df851edf313a",
      "product_id": "74dd8f08-8b06-43a8-9a8b-3ef5e7478d52",
      "feature_id": "093075db-b1ce-4dbb-8d1c-60d1b253a072",
      "variant_id": "d82d6649-bee7-40c5-b14f-6cb593bec904",
      "created_at": "2026-10-11T20:53:35.134085Z"
    }
  ],
  "total": 3
}

Response fields

valuesarray

Valores do produto.

values[].iduuid

Id do registro de valor (muda a cada PUT).

values[].product_iduuid

O produto.

values[].feature_iduuid

A característica.

values[].variant_iduuid

A opção escolhida. Ausente nos tipos sem opção. Em brand e author vem preenchido mesmo quando você enviou só value_text.

values[].value_textstring

Texto, quando houve.

values[].value_numinteger

Número inteiro, quando houve.

values[].value_datestring

Data, quando houve.

values[].created_atstring

Quando o valor foi gravado (RFC 3339).

totalinteger

Quantidade de valores.

Erros

Status	Quando	Corpo
400	Corpo do `PUT` não é JSON válido	`{"error":"invalid request body","detail":"invalid character 'b' looking for beginning of object key string"}`
401	Sem credenciais ou token expirado	`{"error":"invalid or expired token"}`
403	Sem o privilégio `manage_features`	`{"error":"insufficient privileges","required":"manage_features"}`
500	Opção que não existe numa característica de seleção	`{"error":"failed to set product feature values","detail":"\"Alienigena\" não é um valor válido para a característica \"Gênero\". Valores aceitos: Masculino, Feminino, Unissex, Infantil"}`
500	`feature_id` que não existe	`{"error":"failed to set product feature values","detail":"o registro referenciado não existe ..."}`
500	`feature_id` ausente ou fora do formato UUID	`{"error":"failed to set product feature values","detail":"o valor \"\" não é um uuid válido ..."}`
500	A mesma característica duas vezes na lista	`{"error":"failed to set product feature values","detail":"já existe um registro com esse valor ..."}`

As mensagens de detail saem em português, como o servidor devolve. Todas as falhas de validação do PUT chegam como 500, não 400: leia o detail.