Busca em lote

Busca vários termos de uma vez e devolve os produtos agrupados por termo, mais a lista dos termos que não acharam nada.

Use esta rota quando o cliente cola uma lista de compras ("caneta azul", "papel A4", "grampeador") e a vitrine precisa mostrar, para cada linha, o que existe na loja e o que não existe. É o caso típico de lojas B2B e de atacado.

Cada termo roda como uma busca normal, com as mesmas regras de visibilidade (produtos escondidos não aparecem). Diferente de Buscar produtos, aqui não há busca semântica: o termo ou casa com o texto, ou fica em unmatched. Também não há facetas nem paginação: você escolhe quantos produtos quer por termo.

POST/api/v1/storefront/search/bulkPública

Buscar vários termos de uma vez

Corpo da requisição

termsarrayobrigatório

Lista de textos a buscar. Cada texto é aparado e os vazios são descartados. Duplicados (sem diferenciar maiúsculas) são removidos. No máximo 100 termos; o que passar disso é ignorado e a resposta traz truncated: true.

per_termintegerpadrão: 5

Quantos produtos devolver por termo, de 1 a 20. Acima de 20 vale 20. Zero ou negativo volta a 5.

max_resultsinteger

Apelido de per_term, usado só quando per_term não é enviado.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/storefront/search/bulk" \
  -H "Content-Type: application/json" \
  -d '{"terms":["camiseta","sandália","xyzzyq"],"per_term":3}'

Resposta

200Resultados por termo

json

{
  "results": [
    {
      "term": "camiseta",
      "products": [
        {
          "id": "db033935-75ea-4b6f-abbb-13d0fcd6386d",
          "name": "Camiseta Lite Verde 00146",
          "slug": "camiseta-lite-verde-00146-146",
          "price": 39990,
          "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
          "category_id": "8fcaf422-1631-4282-b503-85cc57380649",
          "rating_avg": 4.9,
          "rating_count": 17,
          "status": "A",
          "quantity": 1,
          "track_inventory": true
        }
      ],
      "total": 158
    },
    { "term": "xyzzyq", "products": [], "total": 0 }
  ],
  "unmatched": ["xyzzyq"],
  "total": 1,
  "terms": 2,
  "truncated": false,
  "per_term": 1
}

Campos da resposta

resultsarray

Um item por termo, na ordem em que você enviou (depois de limpar e remover duplicados).

results[].termstring

O termo buscado.

results[].productsarray

Até per_term produtos, no mesmo formato descrito em Buscar produtos. Vazio se nada casou ou se a busca daquele termo falhou.

results[].totalinteger

Quantos produtos casam com o termo no total (não só os devolvidos).

unmatchedarray

Termos sem nenhum produto, na ordem de entrada. Um termo cuja busca falhou por erro interno também cai aqui.

totalinteger

Soma dos produtos devolvidos em todos os termos (não a soma dos total).

termsinteger

Quantos termos foram de fato buscados.

truncatedboolean

true se você mandou mais de 100 termos.

per_terminteger

Limite por termo que foi aplicado.

Erros

Status	Quando	Corpo
400	Nenhum termo útil (lista ausente, vazia, só espaços ou corpo que não é JSON)	`{"error":"no search terms provided"}`
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"}`

Veja também