Busca

Endpoints públicos para parceiros realizarem busca textual e navegação por categoria/loja no catálogo.

Base URL

https://{sua-loja}/api/v2/public/

Autenticação

Endpoints públicos — não exigem autenticação. Filtros padrão aplicados em todos os resultados:

has_stock_b:true
status_s:2
telesales_exclusive_b:false

Parâmetros comuns

Campos disponíveis em fl / fq / sort

Exemplos de filtros (fq)

fq=brand:Nike
fq=!has_stock:false
fq=rating:5
fq=sale_price:[50 TO 200]

Múltiplos fq podem ser enviados repetindo o parâmetro: ?fq=brand:Nike&fq=rating:5.

Limites e validações

• fq: máximo de 20 filtros por requisição; cada filtro com até 50 caracteres.
• fl: apenas caracteres A-Z a-z 0-9 _ . * são aceitos.
• sort: campos devem bater com ^[A-Za-z0-9_.]+$; direção asc ou desc.
• products_ids: somente IDs numéricos.
• Em fq, valores numéricos em id:... recebem automaticamente o prefixo sku_.

GET /search/

Busca textual no catálogo.

Query params

Exemplo — Request

curl "https://sua-loja.com/api/v2/public/search/?q=camiseta&fl=id,name,sale_price&sort=sale_price%20asc"

Exemplo — Response 200 OK

{
  "count": 128,
  "next": "https://sua-loja.com/api/v2/public/search/?q=camiseta&page=2",
  "previous": null,
  "results": [
    { "id": "sku_1", "name": "camiseta-preta-p", "sale_price": 59.90 },
    { "id": "sku_2", "name": "camiseta-preta-m", "sale_price": 59.90 }
  ]
}

GET /search/{slug}/

Navegação por categoria ou loja. Retorna listagem paginada, com metadados de facetas, ordenação disponível e breadcrumb.

Path params

Query params

Exemplo — Request

curl "https://sua-loja.com/api/v2/public/search/roupas/camisetas/?fq=brand:Acme&sort=sale_price%20desc&p=2"

Exemplo — Response 200 OK

{
  "count": 42,
  "previous": "https://sua-loja.com/api/v2/public/search/roupas/camisetas/?p=1",
  "next": null,
  "results": [
    {
      "id": "sku_99",
      "name": "camiseta-acme-g",
      "title": "Camiseta Acme G",
      "sale_price": 129.90,
      "unit_price": 149.90,
      "brand": "Acme",
      "has_stock": true
    }
  ],
  "term": "camisetas",
  "query": "roupas/camisetas",
  "sort_options": [ "..." ],
  "map_list": { "...": "..." }
}

Observações

• Quando o slug bate com a página promocional configurada (SHOP_SEARCH_PAGE_PROMOTION), o endpoint automaticamente usa o engine promocional.
• Os campos id e name são sempre incluídos, mesmo se omitidos em fl.

Códigos de resposta