API atual/Referência completa/Configurações da loja

Busca da vitrine

Lê e grava a configuração da busca instantânea da vitrine: o que pesquisar, quantos resultados mostrar e os recursos de busca inteligente.

A busca instantânea é a caixa da vitrine que mostra resultados enquanto o cliente digita. Esta configuração define em que ela procura (produtos, categorias, marcas, sellers), quantos resultados de cada tipo mostra, a partir de quantas letras começa e se exibe preço e imagem. Também liga a busca por sentido (semântica) e a personalização "Para você".

Exigem o privilégio manage_settings.

Ler a configuração

GET/api/v1/admin/search-settingsAdmin

Ler a configuração da busca da vitrine

Devolve a configuração atual. Campos nunca gravados vêm com os padrões.

bash

curl "$BASE_URL/api/v1/admin/search-settings" \
  -H "Authorization: Bearer $TOKEN"

200Configuração

json

{
  "live_search_enabled": true,
  "search_products": true,
  "search_categories": true,
  "search_brands": true,
  "search_vendors": false,
  "products_under_categories": false,
  "max_product_results": 8,
  "max_category_results": 5,
  "max_brand_results": 5,
  "max_vendor_results": 5,
  "min_query_length": 2,
  "show_product_prices": true,
  "show_product_images": true,
  "semantic_search_enabled": true,
  "personalization_enabled": false
}

Gravar a configuração

PUT/api/v1/admin/search-settingsAdmin

Gravar a configuração da busca da vitrine

Grava o objeto inteiro. Diferente de PUT /settings, aqui não há mesclagem: campos omitidos são gravados como false ou 0. Leia, ajuste e reenvie o objeto completo. A resposta traz message e a configuração gravada.

Corpo da requisição

live_search_enabledbooleanpadrão: true

Liga a busca instantânea. Desligada, a busca devolve resultado vazio.

search_productsbooleanpadrão: true

Procura em produtos.

search_categoriesbooleanpadrão: true

Procura em categorias.

search_brandsbooleanpadrão: true

Procura em marcas.

search_vendorsbooleanpadrão: true

Procura em sellers.

products_under_categoriesbooleanpadrão: true

Mostra produtos agrupados sob a categoria encontrada.

max_product_resultsintegerpadrão: 8

Máximo de produtos na lista instantânea.

max_category_resultsintegerpadrão: 5

Máximo de categorias.

max_brand_resultsintegerpadrão: 5

Máximo de marcas.

max_vendor_resultsintegerpadrão: 5

Máximo de sellers.

min_query_lengthintegerpadrão: 2

Quantidade mínima de letras para começar a buscar. Abaixo disso a busca devolve vazio.

show_product_pricesbooleanpadrão: true

Mostra o preço nos resultados.

show_product_imagesbooleanpadrão: true

Mostra a imagem nos resultados.

semantic_search_enabledbooleanpadrão: true

Busca por sentido, além das palavras exatas, na caixa de busca, na página de busca e na lista instantânea.

personalization_enabledbooleanpadrão: false

Reordena os resultados e a página de categoria conforme o interesse do cliente ("Para você"). Desligado por padrão.

bash

curl -X PUT "$BASE_URL/api/v1/admin/search-settings" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "live_search_enabled": true, "search_products": true, "search_categories": true,
    "search_brands": true, "search_vendors": false, "products_under_categories": false,
    "max_product_results": 10, "max_category_results": 5, "max_brand_results": 5,
    "max_vendor_results": 5, "min_query_length": 3, "show_product_prices": true,
    "show_product_images": true, "semantic_search_enabled": true, "personalization_enabled": false
  }'

200Configuração gravada

json

{
  "message": "search settings updated",
  "settings": {
    "live_search_enabled": true,
    "search_products": true,
    "search_categories": true,
    "search_brands": true,
    "search_vendors": false,
    "products_under_categories": false,
    "max_product_results": 10,
    "max_category_results": 5,
    "max_brand_results": 5,
    "max_vendor_results": 5,
    "min_query_length": 3,
    "show_product_prices": true,
    "show_product_images": true,
    "semantic_search_enabled": true,
    "personalization_enabled": false
  }
}

Erros

Status	Quando	Corpo de exemplo
400	Corpo que não é JSON.	`{"error":"invalid request body","detail":"..."}`
401	Sem token ou token expirado.	`{"error":"invalid or expired token"}`
403	Sem `manage_settings`.	`{"error":"insufficient privileges","required":"manage_settings"}`
500	Falha ao ler ou gravar.	`{"error":"failed to update search settings","detail":"..."}`

Veja também

Busca da vitrine

Lê e grava a configuração da busca instantânea da vitrine: o que pesquisar, quantos resultados mostrar e os recursos de busca inteligente.

Exigem o privilégio manage_settings.

Ler a configuração

GET/api/v1/admin/search-settingsAdmin

Ler a configuração da busca da vitrine

Devolve a configuração atual. Campos nunca gravados vêm com os padrões.

bash

curl "$BASE_URL/api/v1/admin/search-settings" \
  -H "Authorization: Bearer $TOKEN"

200Configuração

json

{
  "live_search_enabled": true,
  "search_products": true,
  "search_categories": true,
  "search_brands": true,
  "search_vendors": false,
  "products_under_categories": false,
  "max_product_results": 8,
  "max_category_results": 5,
  "max_brand_results": 5,
  "max_vendor_results": 5,
  "min_query_length": 2,
  "show_product_prices": true,
  "show_product_images": true,
  "semantic_search_enabled": true,
  "personalization_enabled": false
}

Gravar a configuração

PUT/api/v1/admin/search-settingsAdmin

Gravar a configuração da busca da vitrine

Corpo da requisição

live_search_enabledbooleanpadrão: true

Liga a busca instantânea. Desligada, a busca devolve resultado vazio.

search_productsbooleanpadrão: true

Procura em produtos.

search_categoriesbooleanpadrão: true

Procura em categorias.

search_brandsbooleanpadrão: true

Procura em marcas.

search_vendorsbooleanpadrão: true

Procura em sellers.

products_under_categoriesbooleanpadrão: true

Mostra produtos agrupados sob a categoria encontrada.

max_product_resultsintegerpadrão: 8

Máximo de produtos na lista instantânea.

max_category_resultsintegerpadrão: 5

Máximo de categorias.

max_brand_resultsintegerpadrão: 5

Máximo de marcas.

max_vendor_resultsintegerpadrão: 5

Máximo de sellers.

min_query_lengthintegerpadrão: 2

Quantidade mínima de letras para começar a buscar. Abaixo disso a busca devolve vazio.

show_product_pricesbooleanpadrão: true

Mostra o preço nos resultados.

show_product_imagesbooleanpadrão: true

Mostra a imagem nos resultados.

semantic_search_enabledbooleanpadrão: true

Busca por sentido, além das palavras exatas, na caixa de busca, na página de busca e na lista instantânea.

personalization_enabledbooleanpadrão: false

Reordena os resultados e a página de categoria conforme o interesse do cliente ("Para você"). Desligado por padrão.

bash

curl -X PUT "$BASE_URL/api/v1/admin/search-settings" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "live_search_enabled": true, "search_products": true, "search_categories": true,
    "search_brands": true, "search_vendors": false, "products_under_categories": false,
    "max_product_results": 10, "max_category_results": 5, "max_brand_results": 5,
    "max_vendor_results": 5, "min_query_length": 3, "show_product_prices": true,
    "show_product_images": true, "semantic_search_enabled": true, "personalization_enabled": false
  }'

200Configuração gravada

json

{
  "message": "search settings updated",
  "settings": {
    "live_search_enabled": true,
    "search_products": true,
    "search_categories": true,
    "search_brands": true,
    "search_vendors": false,
    "products_under_categories": false,
    "max_product_results": 10,
    "max_category_results": 5,
    "max_brand_results": 5,
    "max_vendor_results": 5,
    "min_query_length": 3,
    "show_product_prices": true,
    "show_product_images": true,
    "semantic_search_enabled": true,
    "personalization_enabled": false
  }
}

Erros

Status	Quando	Corpo de exemplo
400	Corpo que não é JSON.	`{"error":"invalid request body","detail":"..."}`
401	Sem token ou token expirado.	`{"error":"invalid or expired token"}`
403	Sem `manage_settings`.	`{"error":"insufficient privileges","required":"manage_settings"}`
500	Falha ao ler ou gravar.	`{"error":"failed to update search settings","detail":"..."}`