API legada/Referência completa/Vitrine /api/storefront

GETProdutos

Lista os produtos ativos da vitrine com filtros e ordenação, e lê um produto pelo id ou pelo slug.

As duas leituras de catálogo da vitrine. A lista devolve o cartão de cada produto (nome, imagens, preço, estoque, vendedor); a leitura individual devolve a página completa de um produto (descrição, breadcrumb, SEO). Só aparecem produtos ativos (status A): rascunhos, desativados e em moderação respondem 404 ou ficam fora da lista, e não há parâmetro para vê-los.

As credenciais aceitas estão na visão geral.

Listar produtos

GET/api/storefront/productsPública

Listar produtos da vitrine

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 dessa faixa não gera erro: volta para 20. limit é aceito como apelido.

sort_bystringpadrão: created_at

created_atpricenamesales_countrating_avgupdated_atquantitypopularitystatuscategory

Campo de ordenação. Valor desconhecido é ignorado.

sort_dirstringpadrão: desc

ascdesc

Sentido. Qualquer valor diferente de asc vale desc.

idsstring

Até 200 ids de produto (UUID) separados por vírgula. Devolve exatamente esses produtos, desde que sejam visíveis.

category_iduuid

Produtos desta categoria.

category_idsstring

Várias categorias (OU), separadas por vírgula ou com o parâmetro repetido.

include_subcategoriesbooleanpadrão: false

true inclui os produtos das subcategorias.

vendor_iduuid

Somente produtos deste seller (lojista).

vendor_idsstring

Vários sellers (OU).

brandstring

Nome ou slug da marca; vários separados por vírgula (OU).

brand_idstring

Ids de marca (UUID) separados por vírgula.

min_priceinteger

Preço mínimo em centavos.

max_priceinteger

Preço máximo em centavos.

on_saleboolean

true restringe a produtos em promoção.

in_stockbooleanpadrão: false

true esconde produtos sem saldo.

searchstring

Filtro de texto simples. q é um apelido; se vierem os dois, vale search. Para busca com relevância e filtros por faceta, use Busca.

features[featureId]string

Filtro por característica, features[<id da característica>]=<id da variante>,<id da variante>: OU dentro da característica, E entre características.

features_hashstring

Forma compacta de features[...] para URLs amigáveis: idCaracteristica.idVariante1-idVariante2.outraCaracteristica.idVariante. Uma característica já enviada em features[...] tem prioridade.

exclude_variationsbooleanpadrão: true

false inclui os produtos-filhos de variação, que normalmente ficam sob o produto pai.

parent_product_iduuid

Somente filhos de variação deste produto pai. Use com exclude_variations=false.

langstring

Idioma dos textos (pt-BR, en, es). Também vale o cabeçalho Accept-Language.

Cabeçalhos

Authorizationstring

Opcional. Bearer $TOKEN de um cliente libera produtos restritos ao grupo dele e preços de grupo.

X-API-Keystring

Opcional. Chave sfk_... com o escopo storefront:read.

X-Tenant-IDstring

Identifica a loja quando a chamada não vai ao domínio dela.

Ler um produto

GET/api/storefront/products/{id}Pública

Ler um produto pelo id ou slug

Parâmetros de caminho

idstringobrigatório

UUID do produto ou o slug (camisa-flamengo-masculina-i-26-adidas). Código SKU e o número display_id não servem e dão 404.

Exemplo de requisição

bash

curl "$BASE_URL/api/storefront/products?per_page=2&sort_by=price&sort_dir=asc"

curl "$BASE_URL/api/storefront/products/camisa-flamengo-masculina-i-26-adidas"

Resposta

200Lista de produtos (reduzida a 1 item e campos principais)

json

{
  "page": 1,
  "per_page": 2,
  "total": 4976,
  "total_pages": 2488,
  "products": [
    {
      "id": "22fbd12a-1b6e-41ea-a84f-4d9cf06c8766",
      "display_id": 10497,
      "name": "Camisa do Flamengo Masculina I 26 Adidas",
      "slug": "camisa-flamengo-masculina-i-26-adidas",
      "sku": "FLA-I-26",
      "short_description": "Camisa oficial Flamengo I 26 Adidas",
      "category_id": "8fcaf422-1631-4282-b503-85cc57380649",
      "canonical_path": ["moda", "roupas", "camisetas", "camisa-flamengo-masculina-i-26-adidas", "p"],
      "price": 30000,
      "price_str": "300.00",
      "list_price": 44990,
      "list_price_str": "449.90",
      "catalog_discount": 6000,
      "track_inventory": true,
      "quantity": 38,
      "out_of_stock_action": "N",
      "min_quantity": 0,
      "max_quantity": 0,
      "quantity_step": 1,
      "sale_unit": "un",
      "free_shipping": false,
      "requires_shipping": true,
      "images": [
        {
          "id": "1ed7ed93-e870-4e59-b863-a577764e5d1a",
          "image_url": "/uploads/dfe2555e/product/22fbd12a/camisa.png",
          "alt_text": "Camisa do Flamengo Masculina I 26 Adidas",
          "is_primary": true,
          "position": 0
        }
      ],
      "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
      "vendor_name": "Loja Seller Teste",
      "rating_avg": 0,
      "rating_count": 0,
      "status": "A",
      "created_at": "2026-08-25T02:40:35.960912Z"
    }
  ]
}

Campos da resposta

page, per_page, total, total_pagesinteger

Paginação. total é a contagem de produtos que passam nos filtros.

products[].iduuid

Id do produto (product_id repete o valor).

products[].display_idinteger

Número curto e sequencial que o painel mostra. Não serve de chave na API.

products[].namestring

Nome (product repete o valor).

products[].slugstring

Parte da URL amigável. Serve para ler o produto.

products[].skustring

Código do produto no estoque do seller.

products[].priceinteger

Preço de venda em centavos, já com o desconto de catálogo. price_str repete em reais.

products[].list_priceinteger

Preço "de", em centavos (antes do desconto). list_price_str repete em reais.

products[].catalog_discountinteger

Desconto de catálogo aplicado, em centavos.

products[].quantityinteger

Saldo em estoque. amount repete o valor.

products[].track_inventoryboolean

false quer dizer que o produto não controla estoque.

products[].out_of_stock_actionstring

NBS

O que acontece sem saldo: N esconde o botão de comprar, B aceita encomenda (permite comprar mesmo sem saldo), S mostra o formulário "avise-me quando voltar".

products[].min_quantityinteger

Quantidade mínima por compra (0 é sem mínimo).

products[].max_quantityinteger

Quantidade máxima por compra (0 é sem máximo).

products[].quantity_stepinteger

Múltiplo de quantidade permitido.

products[].sale_unitstring

Unidade de venda (un).

products[].canonical_patharray

Segmentos da URL canônica da página do produto na vitrine.

products[].imagesarray

Imagens, com image_url relativo ao domínio da loja, is_primary e position.

products[].vendor_iduuid

Seller dono do produto. company_id repete o valor.

products[].statusstring

Sempre A nesta rota.

A resposta traz ainda dezenas de campos de apoio, em duplicidade, para clientes antigos (timestamp, updated_timestamp, seo_name, product_code, supplier, zero_price_action, price_tiers...). A leitura individual acrescenta breadcrumb, categories, seo e full_description.

200Produto trocou de endereço

json

{ "redirect": "/products/novo-slug", "slug": "novo-slug" }

Quando o slug pedido é antigo e a loja registrou um redirecionamento, a leitura devolve 200 com este corpo no lugar do produto. Siga o redirect.

Erros

Status	Quando	Corpo
401	Loja que exige login para navegar e chamada anônima	`{"error": "shopping_requires_login", "message": "this storefront requires login to browse"}`
403	Chave `sfk_` sem o escopo `storefront:read`	`{"error": "missing_scope", "required": "storefront:read"}`
404	Produto inexistente, inativo, restrito ao grupo do cliente ou de seller que não entrega na região	`{"error": "product not found"}`
500	Falha ao ler o produto	`{"error": "failed to get product", ...}`

Veja também

GETProdutos

Lista os produtos ativos da vitrine com filtros e ordenação, e lê um produto pelo id ou pelo slug.

As credenciais aceitas estão na visão geral.

Listar produtos

GET/api/storefront/productsPública

Listar produtos da vitrine

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 dessa faixa não gera erro: volta para 20. limit é aceito como apelido.

sort_bystringpadrão: created_at

created_atpricenamesales_countrating_avgupdated_atquantitypopularitystatuscategory

Campo de ordenação. Valor desconhecido é ignorado.

sort_dirstringpadrão: desc

ascdesc

Sentido. Qualquer valor diferente de asc vale desc.

idsstring

Até 200 ids de produto (UUID) separados por vírgula. Devolve exatamente esses produtos, desde que sejam visíveis.

category_iduuid

Produtos desta categoria.

category_idsstring

Várias categorias (OU), separadas por vírgula ou com o parâmetro repetido.

include_subcategoriesbooleanpadrão: false

true inclui os produtos das subcategorias.

vendor_iduuid

Somente produtos deste seller (lojista).

vendor_idsstring

Vários sellers (OU).

brandstring

Nome ou slug da marca; vários separados por vírgula (OU).

brand_idstring

Ids de marca (UUID) separados por vírgula.

min_priceinteger

Preço mínimo em centavos.

max_priceinteger

Preço máximo em centavos.

on_saleboolean

true restringe a produtos em promoção.

in_stockbooleanpadrão: false

true esconde produtos sem saldo.

searchstring

Filtro de texto simples. q é um apelido; se vierem os dois, vale search. Para busca com relevância e filtros por faceta, use Busca.

features[featureId]string

Filtro por característica, features[<id da característica>]=<id da variante>,<id da variante>: OU dentro da característica, E entre características.

features_hashstring

Forma compacta de features[...] para URLs amigáveis: idCaracteristica.idVariante1-idVariante2.outraCaracteristica.idVariante. Uma característica já enviada em features[...] tem prioridade.

exclude_variationsbooleanpadrão: true

false inclui os produtos-filhos de variação, que normalmente ficam sob o produto pai.

parent_product_iduuid

Somente filhos de variação deste produto pai. Use com exclude_variations=false.

langstring

Idioma dos textos (pt-BR, en, es). Também vale o cabeçalho Accept-Language.

Cabeçalhos

Authorizationstring

Opcional. Bearer $TOKEN de um cliente libera produtos restritos ao grupo dele e preços de grupo.

X-API-Keystring

Opcional. Chave sfk_... com o escopo storefront:read.

X-Tenant-IDstring

Identifica a loja quando a chamada não vai ao domínio dela.

Ler um produto

GET/api/storefront/products/{id}Pública

Ler um produto pelo id ou slug

Parâmetros de caminho

idstringobrigatório

UUID do produto ou o slug (camisa-flamengo-masculina-i-26-adidas). Código SKU e o número display_id não servem e dão 404.

Exemplo de requisição

bash

curl "$BASE_URL/api/storefront/products?per_page=2&sort_by=price&sort_dir=asc"

curl "$BASE_URL/api/storefront/products/camisa-flamengo-masculina-i-26-adidas"

Resposta

200Lista de produtos (reduzida a 1 item e campos principais)

json

{
  "page": 1,
  "per_page": 2,
  "total": 4976,
  "total_pages": 2488,
  "products": [
    {
      "id": "22fbd12a-1b6e-41ea-a84f-4d9cf06c8766",
      "display_id": 10497,
      "name": "Camisa do Flamengo Masculina I 26 Adidas",
      "slug": "camisa-flamengo-masculina-i-26-adidas",
      "sku": "FLA-I-26",
      "short_description": "Camisa oficial Flamengo I 26 Adidas",
      "category_id": "8fcaf422-1631-4282-b503-85cc57380649",
      "canonical_path": ["moda", "roupas", "camisetas", "camisa-flamengo-masculina-i-26-adidas", "p"],
      "price": 30000,
      "price_str": "300.00",
      "list_price": 44990,
      "list_price_str": "449.90",
      "catalog_discount": 6000,
      "track_inventory": true,
      "quantity": 38,
      "out_of_stock_action": "N",
      "min_quantity": 0,
      "max_quantity": 0,
      "quantity_step": 1,
      "sale_unit": "un",
      "free_shipping": false,
      "requires_shipping": true,
      "images": [
        {
          "id": "1ed7ed93-e870-4e59-b863-a577764e5d1a",
          "image_url": "/uploads/dfe2555e/product/22fbd12a/camisa.png",
          "alt_text": "Camisa do Flamengo Masculina I 26 Adidas",
          "is_primary": true,
          "position": 0
        }
      ],
      "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
      "vendor_name": "Loja Seller Teste",
      "rating_avg": 0,
      "rating_count": 0,
      "status": "A",
      "created_at": "2026-08-25T02:40:35.960912Z"
    }
  ]
}

Campos da resposta

page, per_page, total, total_pagesinteger

Paginação. total é a contagem de produtos que passam nos filtros.

products[].iduuid

Id do produto (product_id repete o valor).

products[].display_idinteger

Número curto e sequencial que o painel mostra. Não serve de chave na API.

products[].namestring

Nome (product repete o valor).

products[].slugstring

Parte da URL amigável. Serve para ler o produto.

products[].skustring

Código do produto no estoque do seller.

products[].priceinteger

Preço de venda em centavos, já com o desconto de catálogo. price_str repete em reais.

products[].list_priceinteger

Preço "de", em centavos (antes do desconto). list_price_str repete em reais.

products[].catalog_discountinteger

Desconto de catálogo aplicado, em centavos.

products[].quantityinteger

Saldo em estoque. amount repete o valor.

products[].track_inventoryboolean

false quer dizer que o produto não controla estoque.

products[].out_of_stock_actionstring

NBS

O que acontece sem saldo: N esconde o botão de comprar, B aceita encomenda (permite comprar mesmo sem saldo), S mostra o formulário "avise-me quando voltar".

products[].min_quantityinteger

Quantidade mínima por compra (0 é sem mínimo).

products[].max_quantityinteger

Quantidade máxima por compra (0 é sem máximo).

products[].quantity_stepinteger

Múltiplo de quantidade permitido.

products[].sale_unitstring

Unidade de venda (un).

products[].canonical_patharray

Segmentos da URL canônica da página do produto na vitrine.

products[].imagesarray

Imagens, com image_url relativo ao domínio da loja, is_primary e position.

products[].vendor_iduuid

Seller dono do produto. company_id repete o valor.

products[].statusstring

Sempre A nesta rota.

200Produto trocou de endereço

json

{ "redirect": "/products/novo-slug", "slug": "novo-slug" }

Quando o slug pedido é antigo e a loja registrou um redirecionamento, a leitura devolve 200 com este corpo no lugar do produto. Siga o redirect.

Erros

Status	Quando	Corpo
401	Loja que exige login para navegar e chamada anônima	`{"error": "shopping_requires_login", "message": "this storefront requires login to browse"}`
403	Chave `sfk_` sem o escopo `storefront:read`	`{"error": "missing_scope", "required": "storefront:read"}`
404	Produto inexistente, inativo, restrito ao grupo do cliente ou de seller que não entrega na região	`{"error": "product not found"}`
500	Falha ao ler o produto	`{"error": "failed to get product", ...}`