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

GETBusca

Busca produtos da vitrine por texto, com filtros, ordenação, paginação e contagens por faceta.

Procura produtos por texto (q) e devolve os resultados por relevância junto com facetas: contagens por categoria e por seller que você usa para montar filtros laterais ("Camisetas (1)", "Loja X (2)"). Use esta rota para a caixa de busca da loja; para listar uma categoria inteira ou uma seleção de ids, use Produtos.

Cada busca registra um evento de busca (search_event_id), que a vitrine usa para medir cliques e conversão.

GET/api/storefront/searchPública

Buscar produtos

Parâmetros de consulta

qstring

Texto da busca. Vazio e sem nenhum outro filtro devolve lista vazia, com 200 (não é erro). Vazio com algum filtro (categoria, seller, marca, preço, nota, estoque ou característica) navega pelo filtro. Bytes inválidos em UTF-8 são limpos antes da 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 volta para 20.

category_iduuid

Restringe a uma categoria.

vendor_iduuid

Restringe a um seller.

min_priceinteger

Preço mínimo em centavos. Valor não numérico é ignorado.

max_priceinteger

Preço máximo em centavos.

min_ratingnumber

Nota média mínima (por exemplo 4).

in_stockboolean

true1

Somente com saldo. Só true ou 1 ligam o filtro.

brandstring

Nome da marca.

sort_bystring

pricenamecreated_atrating_avgsales_countcategory

Campo de ordenação. Sem ele a ordem é por relevância.

sort_dirstring

ascdesc

Sentido da ordenação.

sortstring

price_ascprice_descnewestratingname_ascname_desccategory_asccategory_descsalesbest_selling

Atalho que vale só quando sort_by não vem.

langstring

Idioma dos textos. Sem ele, vale o cabeçalho Accept-Language; sem os dois, pt-BR.

features[<id>]string

Filtro por característica do produto, repetível: features[<id da característica>]=azul,verde (valores separados por vírgula).

Exemplo de requisição

bash

curl "$BASE_URL/api/storefront/search?q=camisa&per_page=5&sort=price_asc&in_stock=true"

Resposta

200Resultados e facetas (reduzido a 1 produto)

json

{
  "products": [
    {
      "id": "22fbd12a-1b6e-41ea-a84f-4d9cf06c8766",
      "name": "Camisa do Flamengo Masculina I 26 Adidas",
      "slug": "camisa-flamengo-masculina-i-26-adidas",
      "description": "Camisa oficial do Flamengo I 26 Adidas, listrada em vermelho e preto.",
      "price": 30000,
      "list_price": 44990,
      "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
      "category_id": "8fcaf422-1631-4282-b503-85cc57380649",
      "image_url": "/uploads/dfe2555e/product/22fbd12a/camisa.png",
      "rating_avg": 0,
      "rating_count": 0,
      "status": "A",
      "score": 0,
      "quantity": 38,
      "track_inventory": true,
      "out_of_stock_action": "N",
      "catalog_discount": 6000,
      "quantity_step": 1
    }
  ],
  "total": 2,
  "page": 1,
  "per_page": 1,
  "total_pages": 2,
  "took": 0,
  "query": "camisa",
  "facets": {
    "categories": [
      { "key": "8fcaf422-1631-4282-b503-85cc57380649", "label": "Camisetas", "doc_count": 1 }
    ],
    "vendors": [
      { "key": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36", "label": "Loja Seller Teste", "doc_count": 2 }
    ],
    "price_ranges": null,
    "ratings": null
  },
  "log_id": "a7ac9ee4-f24a-4e7c-9c3b-32ca2f000000",
  "search_event_id": "a7ac9ee4-f24a-4e7c-9c3b-32ca2f000000"
}

Campos da resposta

productsarray

Produtos da página. Cada item é um cartão enxuto (menos campos que em products). price e list_price em centavos.

total, page, per_page, total_pagesinteger

Paginação.

tookinteger

Tempo da busca em milissegundos.

querystring

A consulta, depois da limpeza.

facets.categoriesarray

Contagem de resultados por categoria: key (id), label (nome), doc_count.

facets.vendorsarray

Contagem por seller, no mesmo formato.

facets.price_rangesarray|null

Faixas de preço. Pode vir null.

facets.ratingsarray|null

Contagem por nota. Pode vir null.

did_you_meanstring

Sugestão de grafia, só quando total é 0 e existe um termo parecido na loja.

redirect_urlstring

Presente quando uma regra da loja manda redirecionar esta busca. Nesse caso products vem vazio: navegue para a URL.

bannerobject

Banner promocional opcional da regra da loja: title, image_url, link_url.

log_idstring

Id do registro da busca. search_event_id repete o valor.

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"}`

Veja também