API atual/Referência completa/Página de produto

Características do produto

Retorna a ficha técnica de um produto e os selos de características para o cartão, já prontos para exibir.

Uma característica é um atributo do produto (marca, material, voltagem, cor). A loja decide, para cada uma, se ela aparece na página do produto (a ficha técnica) e/ou como selo no cartão da lista. Estas duas rotas devolvem os valores já resolvidos para exibição: você não precisa consultar a definição da característica nem os ids de variante.

Só entram características ativas e marcadas para a respectiva exibição. Para montar filtros a partir das mesmas características, veja Filtros da categoria.

Ficha técnica

GET/api/v1/storefront/products/{id}/featuresPública

Ficha técnica do produto

Parâmetros de caminho

iduuidobrigatório

Id do produto.

Exemplo de requisição

bash

curl "$BASE_URL/api/v1/storefront/products/b2794139-dbc7-4eac-ad65-726edc9a1699/features"

Resposta

200Características retornadas

json

{
  "total": 3,
  "features": [
    {
      "feature_id": "b8ff8f38-286f-45c8-89f5-cc5454c6a232",
      "feature_name": "Marca",
      "feature_type": "brand",
      "prefix": "",
      "suffix": "",
      "value": "Eco",
      "variant_id": "60be5bf5-a2d2-4dcf-8e9d-aab93a6f6acd",
      "position": 7
    },
    {
      "feature_id": "9f77bf2e-b4ad-487a-ae9c-9547ac40cbc4",
      "feature_name": "Modelo",
      "feature_type": "text",
      "group_id": "3737eedf-909a-4cf4-884b-68393ba5bb53",
      "group_name": "Descrição Geral",
      "prefix": "",
      "suffix": "",
      "value": "02928",
      "position": 70
    },
    {
      "feature_id": "b316a51a-50af-4a2f-8688-e562a407956b",
      "feature_name": "Cor",
      "feature_type": "color",
      "prefix": "",
      "suffix": "",
      "value": "Preto",
      "position": 100
    }
  ]
}

Campos da resposta

featuresarray

Características do produto que a loja quer na página, por position. Lista vazia se não há.

totalinteger

Quantidade de itens.

features[].feature_iduuid

Id da característica.

features[].feature_namestring

Nome para exibir ("Marca").

features[].feature_typestring

selectmulti_selecttextnumberdateboolgroupbrandauthorcolor

Tipo da característica.

features[].group_iduuid

Grupo de características ("Descrição Geral") a que ela pertence. Omitido se não tem grupo. Use para dividir a ficha em seções.

features[].group_namestring

Nome do grupo.

features[].prefixstring

Texto antes do valor (por exemplo "R$"). Pode ser vazio.

features[].suffixstring

Texto depois do valor (por exemplo "kg"). Pode ser vazio.

features[].valuestring

Valor resolvido para exibição: o texto, o número, a data ou o rótulo da variante escolhida.

features[].variant_iduuid

Variante escolhida, nas características de seleção. Combine com features[...] em Listar produtos para listar produtos "com o mesmo valor".

features[].image_urlstring

Imagem da variante (logo da marca, por exemplo). Omitido se não há.

features[].colorstring

Cor em hexadecimal, nas características do tipo color. Omitido nas demais.

features[].positioninteger

Ordem de exibição.

Selos de características

Mesma estrutura, mas apenas as características que a loja marcou para aparecer no cartão do produto (marca, material, origem): poucas e compactas. É a rota pensada para renderizar o cartão ou o cabeçalho da página.

GET/api/v1/storefront/products/{id}/catalog-featuresPública

Selos de características do produto

Parâmetros de caminho

iduuidobrigatório

Id do produto.

200Selos retornados

json

{ "features": [], "total": 0 }

A resposta tem o mesmo formato da ficha técnica (features e total). Esta rota nunca devolve erro: em qualquer falha interna ela responde 200 com {"features": [], "total": 0}, porque os selos não são essenciais e não podem quebrar a página.

Erros

Status	Quando	Exemplo de corpo
500	`/features` com `{id}` que não é UUID, ou falha ao consultar	`{"error":"failed to get product features","detail":"..."}`

Um produto inexistente não gera 404: a resposta vem com lista vazia.

Veja também

Características do produto

Retorna a ficha técnica de um produto e os selos de características para o cartão, já prontos para exibir.

Só entram características ativas e marcadas para a respectiva exibição. Para montar filtros a partir das mesmas características, veja Filtros da categoria.

Ficha técnica

GET/api/v1/storefront/products/{id}/featuresPública

Ficha técnica do produto

Parâmetros de caminho

iduuidobrigatório

Id do produto.

Exemplo de requisição

bash

curl "$BASE_URL/api/v1/storefront/products/b2794139-dbc7-4eac-ad65-726edc9a1699/features"

Resposta

200Características retornadas

json

{
  "total": 3,
  "features": [
    {
      "feature_id": "b8ff8f38-286f-45c8-89f5-cc5454c6a232",
      "feature_name": "Marca",
      "feature_type": "brand",
      "prefix": "",
      "suffix": "",
      "value": "Eco",
      "variant_id": "60be5bf5-a2d2-4dcf-8e9d-aab93a6f6acd",
      "position": 7
    },
    {
      "feature_id": "9f77bf2e-b4ad-487a-ae9c-9547ac40cbc4",
      "feature_name": "Modelo",
      "feature_type": "text",
      "group_id": "3737eedf-909a-4cf4-884b-68393ba5bb53",
      "group_name": "Descrição Geral",
      "prefix": "",
      "suffix": "",
      "value": "02928",
      "position": 70
    },
    {
      "feature_id": "b316a51a-50af-4a2f-8688-e562a407956b",
      "feature_name": "Cor",
      "feature_type": "color",
      "prefix": "",
      "suffix": "",
      "value": "Preto",
      "position": 100
    }
  ]
}

Campos da resposta

featuresarray

Características do produto que a loja quer na página, por position. Lista vazia se não há.

totalinteger

Quantidade de itens.

features[].feature_iduuid

Id da característica.

features[].feature_namestring

Nome para exibir ("Marca").

features[].feature_typestring

selectmulti_selecttextnumberdateboolgroupbrandauthorcolor

Tipo da característica.

features[].group_iduuid

Grupo de características ("Descrição Geral") a que ela pertence. Omitido se não tem grupo. Use para dividir a ficha em seções.

features[].group_namestring

Nome do grupo.

features[].prefixstring

Texto antes do valor (por exemplo "R$"). Pode ser vazio.

features[].suffixstring

Texto depois do valor (por exemplo "kg"). Pode ser vazio.

features[].valuestring

Valor resolvido para exibição: o texto, o número, a data ou o rótulo da variante escolhida.

features[].variant_iduuid

Variante escolhida, nas características de seleção. Combine com features[...] em Listar produtos para listar produtos "com o mesmo valor".

features[].image_urlstring

Imagem da variante (logo da marca, por exemplo). Omitido se não há.

features[].colorstring

Cor em hexadecimal, nas características do tipo color. Omitido nas demais.

features[].positioninteger

Ordem de exibição.

Selos de características

GET/api/v1/storefront/products/{id}/catalog-featuresPública

Selos de características do produto

Parâmetros de caminho

iduuidobrigatório

Id do produto.

200Selos retornados

json

{ "features": [], "total": 0 }

Erros

Status	Quando	Exemplo de corpo
500	`/features` com `{id}` que não é UUID, ou falha ao consultar	`{"error":"failed to get product features","detail":"..."}`

Um produto inexistente não gera 404: a resposta vem com lista vazia.