Marcas

Lista as marcas com produtos ativos, consulta uma marca pelo slug e lista os produtos dela com paginação.

Marca é uma característica especial do produto (tipo brand): cada valor dela, como "Eco" ou "Nike", é uma marca. Estas rotas alimentam a página "Todas as marcas" e a página de uma marca. Elas só mostram marcas que têm pelo menos um produto ativo, para a página nunca levar a uma lista vazia. A marca é identificada pelo slug (eco, eco-azul), que também é aceito como brand em Listar produtos.

Todas aceitam ?lang= ou Accept-Language para traduzir nome e descrição da marca.

Listar marcas

GET/api/v1/storefront/brandsPública

Listar marcas com produtos ativos

Parâmetros de consulta

langstring

Idioma de name e description da marca.

Exemplo de requisição

bash

curl "$BASE_URL/api/v1/storefront/brands"

Resposta

200Marcas retornadas (reduzido)

json

{
  "total": 2,
  "brands": [
    {
      "id": "60be5bf5-a2d2-4dcf-8e9d-aab93a6f6acd",
      "feature_id": "b8ff8f38-286f-45c8-89f5-cc5454c6a232",
      "name": "Eco",
      "description": "",
      "code": "eco",
      "position": 0,
      "slug": "eco",
      "product_count": 1
    },
    {
      "id": "fb3519a7-2dc4-47e9-8da3-476a7322e902",
      "feature_id": "b8ff8f38-286f-45c8-89f5-cc5454c6a232",
      "name": "Eco Verde",
      "description": "",
      "code": "eco-verde",
      "position": 0,
      "slug": "eco-verde",
      "product_count": 3
    }
  ]
}

Campos da resposta

brandsarray

Marcas com pelo menos um produto ativo.

totalinteger

Quantidade de marcas na lista (a rota não é paginada).

brands[].iduuid

Id da marca (id da variante da característica de marca). Serve para brand_id em Listar produtos.

brands[].feature_iduuid

Id da característica "Marca" à qual a marca pertence.

brands[].namestring

Nome, no idioma pedido.

brands[].descriptionstring

Descrição, no idioma pedido. Pode ser vazia.

brands[].codestring

Código interno da marca.

brands[].positioninteger

Ordem de exibição.

brands[].slugstring

Slug da URL: o {slug} das rotas abaixo.

brands[].product_countinteger

Produtos ativos da marca.

Consultar uma marca

A busca pelo slug tenta, nesta ordem, o código da marca, o nome exato e o nome transformado em slug. Slug desconhecido responde 404.

GET/api/v1/storefront/brands/{slug}Pública

Consultar uma marca pelo slug

Parâmetros de caminho

slugstringobrigatório

Slug da marca, como vem em brands[].slug.

Parâmetros de consulta

langstring

Idioma dos textos da marca.

200Marca retornada

json

{
  "id": "60be5bf5-a2d2-4dcf-8e9d-aab93a6f6acd",
  "feature_id": "b8ff8f38-286f-45c8-89f5-cc5454c6a232",
  "name": "Eco",
  "description": "",
  "code": "eco",
  "position": 0,
  "slug": "eco",
  "product_count": 1
}

Listar produtos de uma marca

Devolve a marca e uma página dos produtos dela. Aplica a mesma visibilidade da lista de produtos (produto ativo, grupos de usuário, vendedor ativo, regras de preço zero e estoque da loja) e colapsa ofertas de vendedores do mesmo produto mestre em um cartão, quando o módulo de produtos mestre está ligado. Para filtros adicionais (preço, categoria, características), use Listar produtos com brand=<slug>.

GET/api/v1/storefront/brands/{slug}/productsPública

Produtos de uma marca, paginados

Parâmetros de caminho

slugstringobrigatório

Slug da marca.

Parâmetros de consulta

pageintegerpadrão: 1

Página, a partir de 1.

per_pageintegerpadrão: 20

Itens por página, de 1 a 100. Fora da faixa volta para 20.

sort_bystringpadrão: created_at

created_atpricenamesales_countrating_avgupdated_atquantitypopularitystatus

Ordenação. Valor desconhecido vira created_at.

sort_dirstringpadrão: desc

ascdesc

Sentido da ordenação.

langstring

Idioma dos textos da marca.

Exemplo de requisição

bash

curl "$BASE_URL/api/v1/storefront/brands/eco/products?per_page=12&sort_by=price&sort_dir=asc"

Resposta

200Produtos da marca (lista reduzida)

json

{
  "brand": {
    "id": "60be5bf5-a2d2-4dcf-8e9d-aab93a6f6acd",
    "feature_id": "b8ff8f38-286f-45c8-89f5-cc5454c6a232",
    "name": "Eco",
    "description": "",
    "code": "eco",
    "position": 0,
    "slug": "eco",
    "product_count": 1
  },
  "page": 1,
  "per_page": 12,
  "total": 1,
  "total_pages": 1,
  "products": [
    {
      "id": "b2794139-dbc7-4eac-ad65-726edc9a1699",
      "name": "Teclado Eco Preto 02928",
      "slug": "teclado-eco-preto-02928-2928",
      "sku": "SD-002928",
      "price": 49990,
      "quantity": 6,
      "track_inventory": true,
      "status": "A"
    }
  ]
}

Campos da resposta

brandobject

A marca, no mesmo formato de "Consultar uma marca" acima.

productsarray

Produtos da página, no formato do cartão de Listar produtos. null quando a marca não tem produtos visíveis ou a página passou do fim.

totalinteger

Total de produtos da marca visíveis.

pageinteger

Página devolvida.

per_pageinteger

Tamanho de página aplicado.

total_pagesinteger

Quantidade de páginas.

Erros

Status	Quando	Exemplo de corpo
401	A loja exige login para navegar e a requisição é anônima	`{"error":"shopping_requires_login","message":"this storefront requires login to browse"}`
404	Slug de marca desconhecido	`{"error":"BRAND_NOT_FOUND"}`
500	Falha ao consultar	`{"error":"failed to list brands","detail":"..."}`

Veja também

API atual/Referência completa/Catálogo

Marcas

Lista as marcas com produtos ativos, consulta uma marca pelo slug e lista os produtos dela com paginação.

Todas aceitam ?lang= ou Accept-Language para traduzir nome e descrição da marca.

Listar marcas

GET/api/v1/storefront/brandsPública

Listar marcas com produtos ativos

Parâmetros de consulta

langstring

Idioma de name e description da marca.

Exemplo de requisição

bash

curl "$BASE_URL/api/v1/storefront/brands"

Resposta

200Marcas retornadas (reduzido)

json

{
  "total": 2,
  "brands": [
    {
      "id": "60be5bf5-a2d2-4dcf-8e9d-aab93a6f6acd",
      "feature_id": "b8ff8f38-286f-45c8-89f5-cc5454c6a232",
      "name": "Eco",
      "description": "",
      "code": "eco",
      "position": 0,
      "slug": "eco",
      "product_count": 1
    },
    {
      "id": "fb3519a7-2dc4-47e9-8da3-476a7322e902",
      "feature_id": "b8ff8f38-286f-45c8-89f5-cc5454c6a232",
      "name": "Eco Verde",
      "description": "",
      "code": "eco-verde",
      "position": 0,
      "slug": "eco-verde",
      "product_count": 3
    }
  ]
}

Campos da resposta

brandsarray

Marcas com pelo menos um produto ativo.

totalinteger

Quantidade de marcas na lista (a rota não é paginada).

brands[].iduuid

Id da marca (id da variante da característica de marca). Serve para brand_id em Listar produtos.

brands[].feature_iduuid

Id da característica "Marca" à qual a marca pertence.

brands[].namestring

Nome, no idioma pedido.

brands[].descriptionstring

Descrição, no idioma pedido. Pode ser vazia.

brands[].codestring

Código interno da marca.

brands[].positioninteger

Ordem de exibição.

brands[].slugstring

Slug da URL: o {slug} das rotas abaixo.

brands[].product_countinteger

Produtos ativos da marca.

Consultar uma marca

A busca pelo slug tenta, nesta ordem, o código da marca, o nome exato e o nome transformado em slug. Slug desconhecido responde 404.

GET/api/v1/storefront/brands/{slug}Pública

Consultar uma marca pelo slug

Parâmetros de caminho

slugstringobrigatório

Slug da marca, como vem em brands[].slug.

Parâmetros de consulta

langstring

Idioma dos textos da marca.

200Marca retornada

json

{
  "id": "60be5bf5-a2d2-4dcf-8e9d-aab93a6f6acd",
  "feature_id": "b8ff8f38-286f-45c8-89f5-cc5454c6a232",
  "name": "Eco",
  "description": "",
  "code": "eco",
  "position": 0,
  "slug": "eco",
  "product_count": 1
}

Listar produtos de uma marca

GET/api/v1/storefront/brands/{slug}/productsPública

Produtos de uma marca, paginados

Parâmetros de caminho

slugstringobrigatório

Slug da marca.

Parâmetros de consulta

pageintegerpadrão: 1

Página, a partir de 1.

per_pageintegerpadrão: 20

Itens por página, de 1 a 100. Fora da faixa volta para 20.

sort_bystringpadrão: created_at

created_atpricenamesales_countrating_avgupdated_atquantitypopularitystatus

Ordenação. Valor desconhecido vira created_at.

sort_dirstringpadrão: desc

ascdesc

Sentido da ordenação.

langstring

Idioma dos textos da marca.

Exemplo de requisição

bash

curl "$BASE_URL/api/v1/storefront/brands/eco/products?per_page=12&sort_by=price&sort_dir=asc"

Resposta

200Produtos da marca (lista reduzida)

json

{
  "brand": {
    "id": "60be5bf5-a2d2-4dcf-8e9d-aab93a6f6acd",
    "feature_id": "b8ff8f38-286f-45c8-89f5-cc5454c6a232",
    "name": "Eco",
    "description": "",
    "code": "eco",
    "position": 0,
    "slug": "eco",
    "product_count": 1
  },
  "page": 1,
  "per_page": 12,
  "total": 1,
  "total_pages": 1,
  "products": [
    {
      "id": "b2794139-dbc7-4eac-ad65-726edc9a1699",
      "name": "Teclado Eco Preto 02928",
      "slug": "teclado-eco-preto-02928-2928",
      "sku": "SD-002928",
      "price": 49990,
      "quantity": 6,
      "track_inventory": true,
      "status": "A"
    }
  ]
}

Campos da resposta

brandobject

A marca, no mesmo formato de "Consultar uma marca" acima.

productsarray

Produtos da página, no formato do cartão de Listar produtos. null quando a marca não tem produtos visíveis ou a página passou do fim.

totalinteger

Total de produtos da marca visíveis.

pageinteger

Página devolvida.

per_pageinteger

Tamanho de página aplicado.

total_pagesinteger

Quantidade de páginas.

Erros

Status	Quando	Exemplo de corpo
401	A loja exige login para navegar e a requisição é anônima	`{"error":"shopping_requires_login","message":"this storefront requires login to browse"}`
404	Slug de marca desconhecido	`{"error":"BRAND_NOT_FOUND"}`
500	Falha ao consultar	`{"error":"failed to list brands","detail":"..."}`