VenddorDocumentação API
API atualAPI legada
Guia rápidoReferência completa
Carregando índice…
API atual/Referência completa/Ferramentas do catálogo do seller

Características

Lista as características de produto da loja e os valores permitidos de cada uma, para o seller escolher ao cadastrar produtos.

Listar características

Devolve as características ativas da loja. Por padrão só vêm as que servem de eixo de variação ou seleção (select, multi_select e brand); passe feature_type=all para todas. O seller não cria nem altera características: isso é do administrador.

GET/api/v1/vendor/featuresSeller

Listar características

Cabeçalhos

Authorizationstringobrigatório
Bearer $TOKEN. Token de acesso de um usuário do painel do seller (lojista), obtido no login (veja Tokens).

Parâmetros de consulta

feature_typestring
Tipo a listar. Omitido, vêm select, multi_select e brand. all traz todos os tipos.
searchstring
Texto procurado no nome.
category_iduuid
Só as características que valem para esta categoria (ou para todas).
pageintegerpadrão: 1
Página, a partir de 1.
per_pageintegerpadrão: 100
Itens por página. Padrão 100, máximo 100.

Exemplo de requisição

bash
curl "$BASE_URL/api/v1/vendor/features?feature_type=select&per_page=50" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Características
json
{
  "features": [
    {
      "id": "dfae5ba1-09d3-41c1-85dc-be137fb5b61c",
      "name": "Material",
      "code": "",
      "feature_type": "select",
      "description": "",
      "purpose": "group_catalog_item",
      "prefix": "",
      "suffix": "",
      "categories_path": "795ac349-83c1-4bcc-a64a-3317bf84ab5e,47377eee-567c-46f0-83d6-e46f224af80c",
      "display_on_product": true,
      "display_on_catalog": false,
      "filterable": false,
      "comparable": true,
      "position": 0,
      "status": "A",
      "created_at": "2026-07-19T09:03:39.153946Z",
      "updated_at": "2026-10-11T03:11:17.679394Z",
      "feature_id": "dfae5ba1-09d3-41c1-85dc-be137fb5b61c",
      "feature": "Material",
      "timestamp": 1784451819,
      "updated_timestamp": 1791688277
    }
  ],
  "total": 11,
  "page": 1,
  "per_page": 50,
  "total_pages": 1
}

Campos da resposta

totalinteger
Total de características que atendem ao filtro.
pageinteger
Página.
per_pageinteger
Itens por página.
total_pagesinteger
Total de páginas.
featuresarray
Características da página.
features[].iduuid
Id da característica.
features[].namestring
Nome mostrado ao cliente.
features[].codestring
Código interno. Pode ser vazio.
features[].feature_typestring
Tipo: select, multi_select, brand, author, color, text, number, date, bool ou group.
features[].purposestring
Papel nas variações do produto: group_catalog_item (gera itens de catálogo distintos, como Cor), group_variation_catalog_item (gera variações dentro do item, como Tamanho) ou vazio.
features[].prefixstring
Prefixo de exibição (por exemplo R$).
features[].suffixstring
Sufixo de exibição (por exemplo kg).
features[].categories_pathstring
Ids de categoria onde a característica vale, separados por vírgula. Vazio, vale em todas.
features[].display_on_productboolean
Aparece na página do produto.
features[].display_on_catalogboolean
Aparece nas listas de produtos.
features[].filterableboolean
Pode ser usada como filtro.
features[].comparableboolean
Aparece na comparação de produtos.
features[].positioninteger
Ordem de exibição.
features[].statusstring
Situação (letra): A ativa, H oculta.
features[].group_iduuid
Característica-grupo pai. Ausente se não houver.
features[].feature_iduuid
Apelido de id, mantido por compatibilidade com a plataforma 1.0.
features[].featurestring
Apelido de name (compatibilidade 1.0).
features[].timestampinteger
Criação em Unix (segundos). Compatibilidade 1.0.
features[].updated_timestampinteger
Última alteração em Unix (segundos).
features[].created_atstring
RFC 3339.
features[].updated_atstring
RFC 3339.

Erros

StatusQuandoCorpo
401Sem token ou token inválido/expirado.{"error":"missing authorization header"} / {"error":"invalid or expired token"}
403O token não é de um usuário seller (por exemplo, é de um administrador da loja).{"error":"insufficient permissions"}
403O cadastro do seller ainda está em análise (só a tela de cadastro funciona até a aprovação).{"error":"vendor_pending_review","message":"..."}
403O usuário tem papel de seller, mas não está ligado a nenhum seller.{"error":"no vendor account associated with this user"}
403O usuário da equipe do seller não tem nenhum dos privilégios exigidos: vendor_catalog, vendor_view_catalog, vendor_manage_products, vendor_manage_master, vendor_manage_mix, vendor_manage_quotes, vendor_manage_features, vendor_import_products.{"error":"insufficient vendor privileges","privilege_required_any":["vendor_catalog","vendor_view_catalog","vendor_manage_products","vendor_manage_master","vendor_manage_mix","vendor_manage_quotes","vendor_manage_features","vendor_import_products"]}
500Falha ao listar (inclui category_id que não é UUID).{"error":"failed to list features","detail":"..."}
Sem `feature_type`, a paginação é por tipo

No modo padrão a plataforma faz três consultas (select, multi_select, brand), cada uma com seu page e per_page, e junta o resultado. A resposta vem sem page, per_page e total_pages, só com features e total (a soma). Para paginar de verdade, passe um feature_type explícito ou all.

Valores de uma característica

Devolve os valores permitidos de uma característica de lista (por exemplo, Cor: Azul, Verde). Característica de valor livre devolve lista vazia.

GET/api/v1/vendor/features/{id}/variantsSeller

Listar os valores de uma característica

Cabeçalhos

Authorizationstringobrigatório
Bearer $TOKEN. Token de acesso de um usuário do painel do seller (lojista), obtido no login (veja Tokens).

Parâmetros de caminho

iduuidobrigatório
Id da característica.

Exemplo de requisição

bash
curl "$BASE_URL/api/v1/vendor/features/$FEATURE_ID/variants" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Valores
json
{
  "variants": [
    {
      "id": "d6befb0c-4d7b-4f23-af05-74a402108cc7",
      "feature_id": "dfae5ba1-09d3-41c1-85dc-be137fb5b61c",
      "value": "algodão",
      "code": "",
      "position": 0,
      "created_at": "2026-07-19T20:23:02.039066Z",
      "variant_id": "d6befb0c-4d7b-4f23-af05-74a402108cc7",
      "variant": "algodão",
      "timestamp": 1784492582
    }
  ],
  "total": 1
}

Campos da resposta

variantsarray
Valores da característica.
variants[].iduuid
Id do valor.
variants[].feature_iduuid
Característica dona.
variants[].valuestring
Texto do valor.
variants[].codestring
Código interno.
variants[].positioninteger
Ordem.
variants[].image_urlstring
Imagem do valor (amostra de cor, logo da marca). Ausente se não houver.
variants[].colorstring
Cor do valor. Ausente se não houver.
variants[].variant_iduuid
Apelido de id (compatibilidade 1.0).
variants[].variantstring
Apelido de value (compatibilidade 1.0).
variants[].timestampinteger
Criação em Unix (segundos).
variants[].created_atstring
RFC 3339.
totalinteger
Quantidade de valores.

Erros

StatusQuandoCorpo
401Sem token ou token inválido/expirado.{"error":"missing authorization header"} / {"error":"invalid or expired token"}
403O token não é de um usuário seller (por exemplo, é de um administrador da loja).{"error":"insufficient permissions"}
403O cadastro do seller ainda está em análise (só a tela de cadastro funciona até a aprovação).{"error":"vendor_pending_review","message":"..."}
403O usuário tem papel de seller, mas não está ligado a nenhum seller.{"error":"no vendor account associated with this user"}
403O usuário da equipe do seller não tem nenhum dos privilégios exigidos: vendor_catalog, vendor_view_catalog, vendor_manage_products, vendor_manage_master, vendor_manage_mix, vendor_manage_quotes, vendor_manage_features, vendor_import_products.{"error":"insufficient vendor privileges","privilege_required_any":["vendor_catalog","vendor_view_catalog","vendor_manage_products","vendor_manage_master","vendor_manage_mix","vendor_manage_quotes","vendor_manage_features","vendor_import_products"]}
500id que não é UUID, ou falha ao consultar.{"error":"failed to get feature variants","detail":"..."}
Característica inexistente

Um id bem formado que não existe devolve 200 com lista vazia, não 404.

Anterior
Anexos e imagens
Próxima
Campos do importador
Nesta página
  • Listar características
  • Exemplo de requisição
  • Resposta
  • Erros
  • Valores de uma característica
  • Exemplo de requisição
  • Resposta
  • Erros