GETListar produtos

Retorna os produtos ativos da vitrine, com busca, filtros de categoria, vendedor, marca, preço, estoque e características, ordenação e paginação.

Use esta rota para qualquer grade de produtos: a home, uma categoria, uma coleção escolhida a dedo, o resultado de uma busca simples. Cada item é o cartão do produto: nome, imagens, preço, estoque, vendedor e o caminho canônico da URL. Para a página completa (SEO, breadcrumb, vídeos), abra o produto com Consultar produto.

A rota sempre devolve só produtos ativos (A) e aplica as regras de visibilidade da loja: grupos de usuário, vendedor ativo, região de entrega, "mostrar sem estoque" e "mostrar preço zero". Não existe parâmetro para ver rascunhos. Por padrão, produtos-filhos de variação ficam fora da lista (só o produto pai aparece). Para busca com relevância, sugestões e correção de digitação, use a API de busca; search/q aqui é um filtro de texto simples.

GET/api/v1/storefront/productsPública

Listar produtos da vitrine

Parâmetros de consulta

pageintegerpadrão: 1

Página, a partir de 1. Valor inválido volta para 1.

per_pageintegerpadrão: 20

Itens por página, de 1 a 100. Fora dessa faixa não gera erro e não é limitado a 100: volta ao padrão de 20. limit é aceito como apelido quando per_page não é enviado.

sort_bystringpadrão: created_at

created_atpricenamesales_countrating_avgupdated_atquantitypopularitystatuscategory

Campo de ordenação. Um valor desconhecido é ignorado e vale created_at. category ordena pelo nome da categoria no idioma pedido, com produtos sem categoria no fim.

sort_dirstringpadrão: desc

ascdesc

Sentido da ordenação. Qualquer valor diferente de asc vale desc. Empates são desfeitos pelo id do produto, então a paginação é estável.

idsstring

Lista de ids de produto (UUID) separados por vírgula, até 200. Devolve exatamente esses produtos (que passem na visibilidade), útil para vitrines de seleção manual. Os excedentes de 200 são ignorados.

category_iduuid

Produtos da categoria (principal ou adicional). Ativa o rebaixamento de indisponíveis para o fim da lista e as regras de vitrine da categoria (fixar, destacar, afundar).

category_idsstring

Várias categorias (OU). Vírgulas ou o parâmetro repetido.

include_subcategoriesbooleanpadrão: false

true inclui os produtos das subcategorias. A loja pode ligar isso para todas as listas nas configurações gerais.

vendor_iduuid

Somente produtos deste vendedor (lojista).

vendor_idsstring

Vários vendedores (OU). Vírgulas ou o parâmetro repetido.

brandstring

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

brand_idstring

Ids de variante de marca (UUID), separados por vírgula (OU). Combina com brand.

min_priceinteger

Preço mínimo em centavos. Valor que não é inteiro é ignorado.

max_priceinteger

Preço máximo em centavos.

on_saleboolean

true restringe a produtos em promoção (list_price maior que price).

in_stockbooleanpadrão: false

true esconde produtos sem saldo (produtos sem controle de estoque continuam). A configuração da loja "mostrar produtos sem estoque" desligada força true.

searchstring

Filtro de texto no catálogo. q é um apelido; se os dois vierem, vale search. Com busca ou categoria, produtos indisponíveis vão para o fim.

features[featureId]string

Filtro por característica: features[<id da característica>]=<id da variante>,<id da variante>. Dentro de uma característica vale OU, entre características vale E. Repita o parâmetro para várias características. Os ids vêm de Filtros da categoria.

features_hashstring

Forma compacta featureId.varianteA-varianteB.outroId.varianteC. Como os ids de variante são UUIDs e o separador é o hífen, só funciona com ids sem hífen. Prefira features[...].

exclude_variationsbooleanpadrão: true

false inclui na lista os produtos-filhos de variação (que normalmente ficam sob o pai).

parent_product_iduuid

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

langstring

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

Cabeçalhos

X-Tenant-IDstring

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

Authorizationstring

Opcional. Bearer $TOKEN de um cliente: libera produtos restritos ao grupo dele e preços do grupo. A resposta vira private, no-store.

X-Buyer-CEPstring

Opcional, em lojas com filtro de região de entrega: CEP do comprador. Também existem X-Buyer-State, X-Buyer-City e X-Buyer-District.

Exemplo de requisição

bash

curl "$BASE_URL/api/v1/storefront/products?category_id=345ac33e-4dcd-4d60-bedf-a2c2d47897d9&min_price=1000&max_price=50000&in_stock=true&sort_by=price&sort_dir=asc&per_page=24"

Resposta

200Produtos retornados (lista reduzida a 1 item)

json

{
  "page": 1,
  "per_page": 24,
  "total": 304,
  "total_pages": 13,
  "products": [
    {
      "id": "038235f3-7686-4742-b823-be3f26fa8fb8",
      "display_id": 8395,
      "name": "Luminária Vintage Roxo 03599 - PROMOÇÃO",
      "slug": "luminaria-vintage-roxo-03599-3599",
      "sku": "SD-003599",
      "short_description": "Luminária Vintage Roxo 03599, qualidade premium com envio rápido.",
      "description": "Luminária Vintage Roxo 03599. Produto de alta qualidade.",
      "category_id": "c7a1ebab-b4da-4cf9-9945-c676c7a51469",
      "canonical_path": ["escritorio", "luminaria-vintage-roxo-03599-3599", "p"],
      "price": 1990,
      "price_str": "19.90",
      "catalog_discount": 398,
      "price_tiers": [],
      "track_inventory": true,
      "quantity": 224,
      "amount": 224,
      "out_of_stock_action": "N",
      "min_quantity": 0,
      "max_quantity": 0,
      "quantity_step": 1,
      "sale_unit": "un",
      "zero_price_action": "P",
      "free_shipping": false,
      "requires_shipping": true,
      "has_unified_variations": false,
      "is_variation": false,
      "images": [
        {
          "id": "0ecce814-ada5-4f6e-8f93-e8fc6cbef954",
          "image_url": "/uploads/dfe2555e-bfd0-41a8-9fa1-9586999f3798/product/038235f3-7686-4742-b823-be3f26fa8fb8/ai_4490930b3b06407e9df05ff11f9e92be.png",
          "alt_text": "Luminária Vintage Roxo 03599",
          "is_primary": true,
          "position": 0
        }
      ],
      "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
      "vendor_name": "Loja Seller Teste",
      "vendor_slug": "loja-seller-teste-ot-vio",
      "rating_avg": 4.6,
      "rating_count": 0,
      "sales_count": 8,
      "view_count": 284,
      "status": "A",
      "created_at": "2021-07-16T13:48:19Z",
      "updated_at": "2026-09-15T14:45:43.412078Z"
    }
  ]
}

Campos da resposta

productsarray|null

Produtos da página. É null (não []) quando a página está além do fim ou nada casou.

totalinteger

Total de produtos que atendem ao filtro, em todas as páginas.

pageinteger

Página devolvida.

per_pageinteger

Tamanho de página aplicado (20 quando o pedido estava fora de 1 a 100).

total_pagesinteger

Quantidade de páginas.

products[].iduuid

Id do produto. product_id é um apelido com o mesmo valor.

products[].display_idinteger

Número amigável sequencial, para exibição. Não use como chave.

products[].namestring

Nome no idioma pedido. product é um apelido.

products[].slugstring

Slug da URL. seo_name é um apelido.

products[].skustring

Código do produto. product_code é um apelido. Pode ser omitido.

products[].short_descriptionstring

Resumo em texto. description pode conter HTML.

products[].category_iduuid

Categoria principal. main_category repete o valor.

products[].canonical_patharray

Segmentos da URL canônica (["categoria", "slug-do-produto", "p"]). Ausente se o produto não tem categoria.

products[].priceinteger

Preço unitário em centavos. Zero quando price_redacted é true.

products[].price_strstring

O mesmo preço em decimal ("19.90").

products[].list_priceinteger|null

Preço "de" em centavos, quando há. Omitido se não há.

products[].catalog_discountinteger

Desconto por unidade, em centavos, de promoção de catálogo ativa. O carrinho cobra price - catalog_discount. Omitido quando zero.

products[].price_redactedboolean

true quando a loja esconde preços de visitantes. Os campos de preço vêm zerados.

products[].price_tiersarray

Degraus de preço por quantidade (preços universais).

products[].track_inventoryboolean

false = estoque ilimitado.

products[].quantitynumber

Saldo na unidade de venda. Pode ser fracionado.

products[].out_of_stock_actionstring

NBS

Comportamento sem saldo: N bloqueia a compra, B aceita encomenda, S oferece aviso de reposição.

products[].has_unified_variationsboolean

true quando o cliente precisa escolher cor/tamanho antes de comprar (veja Variações).

products[].is_variationboolean

true para um produto-filho de variação.

products[].imagesarray

Imagens com id, image_url, alt_text, is_primary e position. A URL pode ser relativa ao domínio da loja.

products[].vendor_iduuid

Vendedor dono da oferta. Omitido em produto da própria loja. company_id e supplier são apelidos.

products[].vendor_namestring

Nome do vendedor. vendor_slug serve para montar a página do vendedor.

products[].rating_avgnumber

Nota média, de 0 a 5. rating_count é a quantidade de avaliações.

products[].created_atstring

Criação em RFC 3339 (UTC). timestamp e updated_timestamp repetem as datas em Unix (segundos).

O objeto do produto tem mais campos opcionais (dimensões, tags, variation_swatches, sell_unit, units_per_box, vendor_on_vacation, catalog_mode). Eles aparecem só quando o dado existe. Os campos da tabela acima são os estáveis.

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"}`
403	Chave de API sem o escopo `storefront:read`	`{"error":"missing_scope","required":"storefront:read"}`
500	Falha ao consultar o catálogo	`{"error":"failed to list products","detail":"..."}`

Parâmetros inválidos (min_price não numérico, sort_by desconhecido, page negativa) não geram 400: são ignorados ou voltam ao padrão.

Veja também