API atual/Referência completa/Conteúdo e características do produto

Apelido characteristics

As rotas /characteristics dos produtos, que repetem /features e acrescentam a adição de uma característica por vez.

"Característica" é o nome em português de "feature". A API expõe as mesmas operações sob dois caminhos: /products/{id}/features (nome em inglês) e /products/{id}/characteristics (nome em português, usado pelo painel). Elas leem e gravam os mesmos dados e seguem as mesmas regras de tipo, valor e permissão descritas em Características do produto.

A diferença é uma só: characteristics tem também o POST, que acrescenta ou troca uma característica sem apagar as outras. É a rota certa para "marcar este produto como Voltagem 220V" sem reenviar a ficha inteira.

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

Lista os valores de características de um produto (alias de /features)

Exige o privilégio manage_features. Mesma resposta de GET /products/{id}/features.

Path parameters

iduuidobrigatório

Id do produto.

POST/api/v1/admin/products/{id}/characteristicsAdmin

Adiciona ou substitui uma característica de um produto

Exige o privilégio manage_features. Lê os valores atuais, tira o da mesma feature_id (se houver), junta o novo e regrava tudo. Resposta 201 com a lista completa já atualizada.

Path parameters

iduuidobrigatório

Id do produto.

Corpo da requisição

feature_iduuidobrigatório

Id da característica (definição).

variant_iduuid

Id da opção, para características de seleção.

value_textstring

Texto, "true"/"false" ou nome da opção (veja os tipos na home da seção).

value_numinteger

Número inteiro. Decimal é multiplicado por 100.

value_datestring

Data AAAA-MM-DD.

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

Substitui todos os valores de características de um produto (alias de /features)

Exige o privilégio manage_features. Igual a PUT /products/{id}/features: corpo {"values":[...]}, substitui tudo, não é atômico. Os campos de cada item estão em Características do produto.

Path parameters

iduuidobrigatório

Id do produto.

Corpo da requisição

valuesarrayobrigatório

Lista completa de valores. Cada item tem feature_id e variant_id, value_text, value_num ou value_date.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/admin/products/74dd8f08-8b06-43a8-9a8b-3ef5e7478d52/characteristics" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "feature_id": "0f1f91af-3ab6-4a3c-a321-27caa2fd3372", "value_text": "Brasil" }'

Resposta

201Característica adicionada (POST)

json

{
  "values": [
    {
      "id": "0b8c4f0e-1c62-4d8a-8d3e-6a3a1f5f2b11",
      "product_id": "74dd8f08-8b06-43a8-9a8b-3ef5e7478d52",
      "feature_id": "9f77bf2e-b4ad-487a-ae9c-9547ac40cbc4",
      "value_text": "Corrida Leve 2026",
      "created_at": "2026-10-11T20:54:02.100412Z"
    },
    {
      "id": "7d1e0a52-5b8f-4f55-a0a1-0c9c8f6f9a42",
      "product_id": "74dd8f08-8b06-43a8-9a8b-3ef5e7478d52",
      "feature_id": "0f1f91af-3ab6-4a3c-a321-27caa2fd3372",
      "value_text": "Brasil",
      "created_at": "2026-10-11T20:54:02.104871Z"
    }
  ],
  "total": 2
}

Response fields

valuesarray

Todos os valores do produto depois da operação (não só o novo). Campos iguais aos de Características do produto.

totalinteger

Quantidade de valores.

O GET e o PUT respondem 200 com o mesmo formato.

Erros

Status	Quando	Corpo
400	Corpo não é JSON válido	`{"error":"invalid request body","detail":"..."}`
400	`POST` sem `feature_id`	`{"error":"feature_id is required"}`
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	`POST` com característica inexistente, opção inválida ou id fora do formato	`{"error":"failed to add product characteristic","detail":"..."}`
500	`PUT` com valor inválido	`{"error":"failed to set product feature values","detail":"..."}`

Veja também

Apelido characteristics

As rotas /characteristics dos produtos, que repetem /features e acrescentam a adição de uma característica por vez.

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

Lista os valores de características de um produto (alias de /features)

Exige o privilégio manage_features. Mesma resposta de GET /products/{id}/features.

Path parameters

iduuidobrigatório

Id do produto.

POST/api/v1/admin/products/{id}/characteristicsAdmin

Adiciona ou substitui uma característica de um produto

Exige o privilégio manage_features. Lê os valores atuais, tira o da mesma feature_id (se houver), junta o novo e regrava tudo. Resposta 201 com a lista completa já atualizada.

Path parameters

iduuidobrigatório

Id do produto.

Corpo da requisição

feature_iduuidobrigatório

Id da característica (definição).

variant_iduuid

Id da opção, para características de seleção.

value_textstring

Texto, "true"/"false" ou nome da opção (veja os tipos na home da seção).

value_numinteger

Número inteiro. Decimal é multiplicado por 100.

value_datestring

Data AAAA-MM-DD.

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

Substitui todos os valores de características de um produto (alias de /features)

Path parameters

iduuidobrigatório

Id do produto.

Corpo da requisição

valuesarrayobrigatório

Lista completa de valores. Cada item tem feature_id e variant_id, value_text, value_num ou value_date.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/admin/products/74dd8f08-8b06-43a8-9a8b-3ef5e7478d52/characteristics" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "feature_id": "0f1f91af-3ab6-4a3c-a321-27caa2fd3372", "value_text": "Brasil" }'

Resposta

201Característica adicionada (POST)

json

{
  "values": [
    {
      "id": "0b8c4f0e-1c62-4d8a-8d3e-6a3a1f5f2b11",
      "product_id": "74dd8f08-8b06-43a8-9a8b-3ef5e7478d52",
      "feature_id": "9f77bf2e-b4ad-487a-ae9c-9547ac40cbc4",
      "value_text": "Corrida Leve 2026",
      "created_at": "2026-10-11T20:54:02.100412Z"
    },
    {
      "id": "7d1e0a52-5b8f-4f55-a0a1-0c9c8f6f9a42",
      "product_id": "74dd8f08-8b06-43a8-9a8b-3ef5e7478d52",
      "feature_id": "0f1f91af-3ab6-4a3c-a321-27caa2fd3372",
      "value_text": "Brasil",
      "created_at": "2026-10-11T20:54:02.104871Z"
    }
  ],
  "total": 2
}

Response fields

valuesarray

Todos os valores do produto depois da operação (não só o novo). Campos iguais aos de Características do produto.

totalinteger

Quantidade de valores.

O GET e o PUT respondem 200 com o mesmo formato.

Erros

Status	Quando	Corpo
400	Corpo não é JSON válido	`{"error":"invalid request body","detail":"..."}`
400	`POST` sem `feature_id`	`{"error":"feature_id is required"}`
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	`POST` com característica inexistente, opção inválida ou id fora do formato	`{"error":"failed to add product characteristic","detail":"..."}`
500	`PUT` com valor inválido	`{"error":"failed to set product feature values","detail":"..."}`