Buscar produtos

Devolve os produtos que casam com um texto e com filtros de categoria, seller, marca, preço, nota e estoque, com ordenação, paginação e facetas para a barra lateral.

Use esta rota para montar a página de resultados da busca da loja e, com category_id, também a página de uma categoria. Você manda o texto digitado (q), os filtros que o cliente marcou e a ordenação, e recebe a página de produtos, o total e as facetas: as contagens por categoria, seller (lojista) e marca que alimentam a barra lateral de filtros.

A rota é pública. Ela grava a busca no painel de analytics da loja e devolve ids para você registrar o clique (Registrar cliques). Não altera estoque, carrinho nem pedidos.

GET/api/v1/storefront/searchPública

Buscar produtos da vitrine

Cabeçalhos

Authorizationstring

Opcional. Bearer $TOKEN de um cliente logado. Sem ele você é tratado como visitante (preço pode vir escondido, conforme a loja). Chave de API precisa do escopo storefront:read.

X-Tenant-IDstring

Só quando você chama o endereço geral da API. No endereço da loja ($BASE_URL) a loja já é identificada pelo domínio. Veja Lojas e domínios.

X-Session-Idstring

Opcional. Identifica o visitante anônimo para o registro da busca. O cookie de sessão da vitrine também serve.

Parâmetros de consulta

qstring

Texto buscado. Casa com nome, descrição e SKU do produto (e de variações), sem diferenciar acento nem maiúsculas. Bytes inválidos em UTF-8 são descartados.

category_iduuid

Só produtos desta categoria (como categoria principal ou adicional). Subcategorias não entram automaticamente: filtre pelo id da subcategoria.

vendor_iduuid

Só produtos deste seller (lojista).

brandstring

Nome da marca, exatamente como aparece em facets.brands[].key.

min_priceinteger

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

max_priceinteger

Preço máximo em centavos. Valor que não é inteiro é ignorado.

min_ratingnumber

Nota mínima da avaliação, de 0 a 5 (por exemplo 4).

in_stockboolean

true1

Com true ou 1, só produtos com estoque. Qualquer outro valor é ignorado.

features[CÓDIGO]string

Filtro por característica do produto (cor, tamanho etc.). A chave entre colchetes é o id ou o código da característica, como em facets.attributes[].feature_id e code. Valores separados por vírgula (features[cor]=Azul,Verde) valem como "ou" dentro da característica; características diferentes se combinam como "e". Para característica numérica mande uma faixa min-max. Repita o parâmetro para várias características.

sort_bystring

pricenamecreated_atrating_avgsales_countcategory

Campo de ordenação. Sem ele a ordem é por relevância (quando há q) ou do mais novo para o mais antigo.

sort_dirstringpadrão: desc

ascdesc

Sentido da ordenação de sort_by. rating_avg e sales_count são sempre do maior para o menor.

sortstring

price_ascprice_descnewestratingrating_descname_ascname_desccategory_asccategory_descsalesbest_selling

Atalho de ordenação, usado só quando sort_by não foi enviado. É o mesmo vocabulário de /search/meili.

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 a 20.

Exemplo de requisição

bash

curl "$BASE_URL/api/v1/storefront/search?q=camiseta&min_price=5000&max_price=50000&in_stock=true&sort=price_asc&per_page=2"

Resposta

200Resultados

json

{
  "products": [
    {
      "id": "db033935-75ea-4b6f-abbb-13d0fcd6386d",
      "name": "Camiseta Lite Verde 00146",
      "slug": "camiseta-lite-verde-00146-146",
      "description": "Camiseta Lite Verde 00146. Produto de alta qualidade, ideal para uso diário.",
      "price": 39990,
      "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
      "category_id": "8fcaf422-1631-4282-b503-85cc57380649",
      "image_url": "/uploads/dfe2555e-bfd0-41a8-9fa1-9586999f3798/product/db033935-75ea-4b6f-abbb-13d0fcd6386d/foto.png",
      "rating_avg": 4.9,
      "rating_count": 17,
      "status": "A",
      "score": 0,
      "quantity": 1,
      "track_inventory": true,
      "zero_price_action": "P",
      "out_of_stock_action": "N",
      "quantity_step": 1
    }
  ],
  "total": 158,
  "page": 1,
  "per_page": 2,
  "total_pages": 79,
  "took": 0,
  "query": "camiseta",
  "facets": {
    "categories": [{ "key": "8fcaf422-1631-4282-b503-85cc57380649", "label": "Camisetas", "doc_count": 158 }],
    "vendors": [{ "key": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36", "label": "Loja Seller Teste", "doc_count": 158 }],
    "brands": [{ "key": "Eco", "label": "Eco", "doc_count": 1 }],
    "price_ranges": null,
    "ratings": null
  },
  "log_id": "e0e3b1ce-6cd2-4ddc-a847-e97af386a2f0",
  "search_event_id": "3e19709e-6461-4f10-9e79-87e38f3d92b4"
}

200Sem texto e sem filtro

json

{ "products": [], "total": 0, "page": 1, "per_page": 20, "total_pages": 0, "took": 0, "query": "" }

Campos da resposta

productsarray

Produtos da página. Vazia quando nada casou, quando a requisição não tem texto nem filtro, ou quando há redirect_url.

products[].iduuid

Id do produto. É o id que as demais rotas da vitrine esperam.

products[].namestring

Nome do produto.

products[].slugstring

Trecho do endereço da página do produto.

products[].descriptionstring

Descrição, que pode conter HTML.

products[].priceinteger

Preço de venda em centavos. 0 com price_redacted: true quando o preço está escondido de visitantes.

products[].list_priceinteger

Preço "de" em centavos, quando maior que price. Ausente se não existe.

products[].catalog_discountinteger

Desconto por unidade, em centavos, das promoções de catálogo ativas. Ausente quando é zero. Já vem refletido no preço cobrado no carrinho.

products[].price_redactedboolean

true quando o preço foi zerado por ser visitante em loja que restringe preço.

products[].vendor_iduuid

Seller dono da oferta.

products[].category_iduuid

Categoria principal.

products[].image_urlstring

Caminho da imagem principal, relativo ao endereço da loja. Pode ser ausente.

products[].rating_avgnumber

Nota média, de 0 a 5.

products[].rating_countinteger

Quantidade de avaliações.

products[].statusstring

Sempre A (ativo) na vitrine.

products[].scorenumber

Pontuação de relevância interna. Não use para ordenar; a lista já vem ordenada.

products[].quantitynumber

Estoque disponível. Fracionário em lojas que vendem por peso.

products[].track_inventoryboolean

false quando a loja não controla estoque desse produto: ele está sempre disponível.

products[].zero_price_actionstring

O que fazer quando o preço é zero, configurado na loja (por exemplo P, pedir preço).

products[].out_of_stock_actionstring

O que fazer sem estoque, configurado na loja (por exemplo N, nada).

products[].has_unified_variationsboolean

true quando o produto tem variações (cor, tamanho) e não pode ir ao carrinho só com o id do produto: abra a página do produto e escolha a variação.

products[].matched_variant_skustring

Quando o texto buscado foi o SKU de uma variação, qual SKU casou. O card é do produto pai.

products[].matched_variant_idinteger

Id da variação que casou, quando existe.

products[].sell_unitstring

Unidade de venda (por exemplo kg, un), em lojas de atacado.

products[].quantity_stepnumber

Múltiplo de compra. A quantidade no carrinho deve ser múltipla dele.

products[].min_quantitynumber

Quantidade mínima de compra.

products[].units_per_boxinteger

Unidades por caixa, em lojas de atacado.

products[].unit_weight_kgnumber

Peso de uma unidade em kg.

products[].weightnumber

Peso do produto.

totalinteger

Total de produtos que casam, em todas as páginas.

pageinteger

Página devolvida.

per_pageinteger

Itens por página aplicados.

total_pagesinteger

Total de páginas.

tookinteger

Tempo de busca em milissegundos. Pode vir 0.

querystring

O texto buscado, já limpo.

facetsobject

Contagens para os filtros, calculadas sobre o resultado atual (o filtro de uma faceta não esconde as outras opções dela mesma). Ausente se a loja não pôde calcular.

categoriesarray

Itens {key, label, doc_count}. key é o category_id para usar no filtro, label o nome para exibir.

vendorsarray

Itens {key, label, doc_count}. key é o vendor_id.

brandsarray

Itens {key, label, doc_count}. key é o nome da marca, valor de brand.

price_rangesarray

Faixas {key, from, to, doc_count} em centavos. Na busca padrão da loja vem null; calcule as faixas na vitrine a partir de min_price e max_price.

ratingsarray

Contagens por nota. Na busca padrão vem null.

attributesarray

Características configuradas como filtro pela loja: {feature_id, code, name, display_type, position, buckets[]}. display_type é checkbox, chips, slider ou swatch. Cada bucket tem value, count e, conforme o tipo, variant_id, image_url, min_cents e max_cents. Para filtrar mande features[code]=value.

log_iduuid

Id do registro da busca. Reenvie em POST /search/click.

search_event_iduuid

Id do evento da busca. Reenvie em POST /search/events.

did_you_meanstring

Correção sugerida. Só aparece quando total é 0 e existe um termo parecido (até 2 letras de diferença) na loja.

redirect_urlstring

Endereço para onde a vitrine deve navegar. Aparece quando o lojista cadastrou um redirecionamento para o termo; products vem vazio.

bannerobject

Banner promocional da busca {title, image_url, link_url}, quando o lojista configurou um para o termo. Só na primeira página.

Erros

Status	Quando	Corpo
401	A loja exige login para navegar e a chamada não tem token	`{"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 search products","detail":"..."}`

Um texto sem resultado não é erro: a resposta é 200 com products: [], total: 0 e, se houver, did_you_mean.

Veja também

Buscar produtos

Devolve os produtos que casam com um texto e com filtros de categoria, seller, marca, preço, nota e estoque, com ordenação, paginação e facetas para a barra lateral.

A rota é pública. Ela grava a busca no painel de analytics da loja e devolve ids para você registrar o clique (Registrar cliques). Não altera estoque, carrinho nem pedidos.

GET/api/v1/storefront/searchPública

Buscar produtos da vitrine

Cabeçalhos

Authorizationstring

Opcional. Bearer $TOKEN de um cliente logado. Sem ele você é tratado como visitante (preço pode vir escondido, conforme a loja). Chave de API precisa do escopo storefront:read.

X-Tenant-IDstring

Só quando você chama o endereço geral da API. No endereço da loja ($BASE_URL) a loja já é identificada pelo domínio. Veja Lojas e domínios.

X-Session-Idstring

Opcional. Identifica o visitante anônimo para o registro da busca. O cookie de sessão da vitrine também serve.

Parâmetros de consulta

qstring

Texto buscado. Casa com nome, descrição e SKU do produto (e de variações), sem diferenciar acento nem maiúsculas. Bytes inválidos em UTF-8 são descartados.

category_iduuid

Só produtos desta categoria (como categoria principal ou adicional). Subcategorias não entram automaticamente: filtre pelo id da subcategoria.

vendor_iduuid

Só produtos deste seller (lojista).

brandstring

Nome da marca, exatamente como aparece em facets.brands[].key.

min_priceinteger

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

max_priceinteger

Preço máximo em centavos. Valor que não é inteiro é ignorado.

min_ratingnumber

Nota mínima da avaliação, de 0 a 5 (por exemplo 4).

in_stockboolean

true1

Com true ou 1, só produtos com estoque. Qualquer outro valor é ignorado.

features[CÓDIGO]string

sort_bystring

pricenamecreated_atrating_avgsales_countcategory

Campo de ordenação. Sem ele a ordem é por relevância (quando há q) ou do mais novo para o mais antigo.

sort_dirstringpadrão: desc

ascdesc

Sentido da ordenação de sort_by. rating_avg e sales_count são sempre do maior para o menor.

sortstring

price_ascprice_descnewestratingrating_descname_ascname_desccategory_asccategory_descsalesbest_selling

Atalho de ordenação, usado só quando sort_by não foi enviado. É o mesmo vocabulário de /search/meili.

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 a 20.

Exemplo de requisição

bash

curl "$BASE_URL/api/v1/storefront/search?q=camiseta&min_price=5000&max_price=50000&in_stock=true&sort=price_asc&per_page=2"

Resposta

200Resultados

json

{
  "products": [
    {
      "id": "db033935-75ea-4b6f-abbb-13d0fcd6386d",
      "name": "Camiseta Lite Verde 00146",
      "slug": "camiseta-lite-verde-00146-146",
      "description": "Camiseta Lite Verde 00146. Produto de alta qualidade, ideal para uso diário.",
      "price": 39990,
      "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
      "category_id": "8fcaf422-1631-4282-b503-85cc57380649",
      "image_url": "/uploads/dfe2555e-bfd0-41a8-9fa1-9586999f3798/product/db033935-75ea-4b6f-abbb-13d0fcd6386d/foto.png",
      "rating_avg": 4.9,
      "rating_count": 17,
      "status": "A",
      "score": 0,
      "quantity": 1,
      "track_inventory": true,
      "zero_price_action": "P",
      "out_of_stock_action": "N",
      "quantity_step": 1
    }
  ],
  "total": 158,
  "page": 1,
  "per_page": 2,
  "total_pages": 79,
  "took": 0,
  "query": "camiseta",
  "facets": {
    "categories": [{ "key": "8fcaf422-1631-4282-b503-85cc57380649", "label": "Camisetas", "doc_count": 158 }],
    "vendors": [{ "key": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36", "label": "Loja Seller Teste", "doc_count": 158 }],
    "brands": [{ "key": "Eco", "label": "Eco", "doc_count": 1 }],
    "price_ranges": null,
    "ratings": null
  },
  "log_id": "e0e3b1ce-6cd2-4ddc-a847-e97af386a2f0",
  "search_event_id": "3e19709e-6461-4f10-9e79-87e38f3d92b4"
}

200Sem texto e sem filtro

json

{ "products": [], "total": 0, "page": 1, "per_page": 20, "total_pages": 0, "took": 0, "query": "" }

Campos da resposta

productsarray

Produtos da página. Vazia quando nada casou, quando a requisição não tem texto nem filtro, ou quando há redirect_url.

products[].iduuid

Id do produto. É o id que as demais rotas da vitrine esperam.

products[].namestring

Nome do produto.

products[].slugstring

Trecho do endereço da página do produto.

products[].descriptionstring

Descrição, que pode conter HTML.

products[].priceinteger

Preço de venda em centavos. 0 com price_redacted: true quando o preço está escondido de visitantes.

products[].list_priceinteger

Preço "de" em centavos, quando maior que price. Ausente se não existe.

products[].catalog_discountinteger

Desconto por unidade, em centavos, das promoções de catálogo ativas. Ausente quando é zero. Já vem refletido no preço cobrado no carrinho.

products[].price_redactedboolean

true quando o preço foi zerado por ser visitante em loja que restringe preço.

products[].vendor_iduuid

Seller dono da oferta.

products[].category_iduuid

Categoria principal.

products[].image_urlstring

Caminho da imagem principal, relativo ao endereço da loja. Pode ser ausente.

products[].rating_avgnumber

Nota média, de 0 a 5.

products[].rating_countinteger

Quantidade de avaliações.

products[].statusstring

Sempre A (ativo) na vitrine.

products[].scorenumber

Pontuação de relevância interna. Não use para ordenar; a lista já vem ordenada.

products[].quantitynumber

Estoque disponível. Fracionário em lojas que vendem por peso.

products[].track_inventoryboolean

false quando a loja não controla estoque desse produto: ele está sempre disponível.

products[].zero_price_actionstring

O que fazer quando o preço é zero, configurado na loja (por exemplo P, pedir preço).

products[].out_of_stock_actionstring

O que fazer sem estoque, configurado na loja (por exemplo N, nada).

products[].has_unified_variationsboolean

true quando o produto tem variações (cor, tamanho) e não pode ir ao carrinho só com o id do produto: abra a página do produto e escolha a variação.

products[].matched_variant_skustring

Quando o texto buscado foi o SKU de uma variação, qual SKU casou. O card é do produto pai.

products[].matched_variant_idinteger

Id da variação que casou, quando existe.

products[].sell_unitstring

Unidade de venda (por exemplo kg, un), em lojas de atacado.

products[].quantity_stepnumber

Múltiplo de compra. A quantidade no carrinho deve ser múltipla dele.

products[].min_quantitynumber

Quantidade mínima de compra.

products[].units_per_boxinteger

Unidades por caixa, em lojas de atacado.

products[].unit_weight_kgnumber

Peso de uma unidade em kg.

products[].weightnumber

Peso do produto.

totalinteger

Total de produtos que casam, em todas as páginas.

pageinteger

Página devolvida.

per_pageinteger

Itens por página aplicados.

total_pagesinteger

Total de páginas.

tookinteger

Tempo de busca em milissegundos. Pode vir 0.

querystring

O texto buscado, já limpo.

facetsobject

Contagens para os filtros, calculadas sobre o resultado atual (o filtro de uma faceta não esconde as outras opções dela mesma). Ausente se a loja não pôde calcular.

categoriesarray

Itens {key, label, doc_count}. key é o category_id para usar no filtro, label o nome para exibir.

vendorsarray

Itens {key, label, doc_count}. key é o vendor_id.

brandsarray

Itens {key, label, doc_count}. key é o nome da marca, valor de brand.

price_rangesarray

Faixas {key, from, to, doc_count} em centavos. Na busca padrão da loja vem null; calcule as faixas na vitrine a partir de min_price e max_price.

ratingsarray

Contagens por nota. Na busca padrão vem null.

attributesarray

log_iduuid

Id do registro da busca. Reenvie em POST /search/click.

search_event_iduuid

Id do evento da busca. Reenvie em POST /search/events.

did_you_meanstring

Correção sugerida. Só aparece quando total é 0 e existe um termo parecido (até 2 letras de diferença) na loja.

redirect_urlstring

Endereço para onde a vitrine deve navegar. Aparece quando o lojista cadastrou um redirecionamento para o termo; products vem vazio.

bannerobject

Banner promocional da busca {title, image_url, link_url}, quando o lojista configurou um para o termo. Só na primeira página.

Erros

Status	Quando	Corpo
401	A loja exige login para navegar e a chamada não tem token	`{"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 search products","detail":"..."}`

Um texto sem resultado não é erro: a resposta é 200 com products: [], total: 0 e, se houver, did_you_mean.