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

Aparência, filtros e busca

Lê como a loja quer exibir as listagens (colunas, ordem, imagens, formatos), quais filtros mostrar na lateral e como a busca ao vivo se comporta.

Três leituras públicas para montar páginas de categoria e de busca do jeito que o lojista configurou: appearance (grade, ordenação, imagens, formatos de data e moeda), filters (quais filtros aparecem na lateral e com que nome) e search (o que a busca ao vivo procura). Todas são GET sem parâmetros e sem cache.

Aparência

GET/api/v1/storefront/settings/appearancePública

Consulta as configurações de aparência da vitrine

Devolve todas as opções de aparência, que são seguras para o público.

Exemplo de requisição

bash

curl "$BASE_URL/api/v1/storefront/settings/appearance"

Resposta

200Aparência

json

{
  "products_per_page": 20,
  "products_per_row": 4,
  "default_product_sorting": "newest",
  "default_sort_order": "desc",
  "show_prices_with_tax": true,
  "show_out_of_stock": true,
  "pwa_enabled": false,
  "show_zero_price": true,
  "enable_quick_view": true,
  "thumbnail_width": 300,
  "thumbnail_height": 300,
  "product_detail_image_size": 800,
  "categories_per_page": 12,
  "available_per_page_values": "10,20,50,100",
  "show_product_code": true,
  "show_product_weight": false,
  "show_product_stock": true,
  "backorder_notice_enabled": true,
  "backorder_notice_text": "",
  "date_format": "DD/MM/YYYY",
  "currency_format": "R$ #.###,##",
  "preferred_layout_editor": "visual",
  "rendering_engine": "layouts",
  "sticky_buybar_enabled": true,
  "product_card_template": "modern",
  "listing_view_modes": ["grid-2", "grid-3", "grid-4", "list"],
  "listing_default_view": "grid-4"
}

Campos da resposta

products_per_pageinteger

Produtos por página nas listagens.

available_per_page_valuesstring

Opções de "itens por página" separadas por vírgula ("10,20,50,100").

products_per_rowinteger

Colunas da grade de produtos.

categories_per_pageinteger

Categorias por página.

default_product_sortingstring

namepricenewestpopularity

Campo de ordenação inicial.

default_sort_orderstring

ascdesc

Sentido da ordenação inicial.

listing_view_modesarray

Modos de visualização oferecidos na barra da listagem: grid-2, grid-3, grid-4, list. Com um só modo, esconda o seletor.

listing_default_viewstring

grid-2grid-3grid-4list

Modo inicial para quem não tem preferência salva. Sempre é um dos modos de listing_view_modes.

product_card_templatestring

defaultmodernfashiontechcompact

Modelo visual do cartão de produto.

show_prices_with_taxboolean

Exibir preços com imposto incluído.

show_out_of_stockboolean

Listar produtos sem estoque.

show_zero_priceboolean

Listar produtos com preço zero. Quando false, produto sem preço some das listagens e a página dele responde 404.

enable_quick_viewboolean

Janela de visualização rápida do produto.

thumbnail_widthinteger

Largura das miniaturas, em pixels.

thumbnail_heightinteger

Altura das miniaturas, em pixels.

product_detail_image_sizeinteger

Largura da imagem principal da página do produto, em pixels.

show_product_codeboolean

Mostrar o SKU na página do produto.

show_product_weightboolean

Mostrar o peso.

show_product_stockboolean

Mostrar a disponibilidade de estoque.

backorder_notice_enabledboolean

Mostrar aviso "sob encomenda" em produto sem estoque que vende por encomenda.

backorder_notice_textstring

Texto do aviso. Vazio: use o texto padrão traduzido ("Sob encomenda").

sticky_buybar_enabledboolean

Barra fixa de compra na página do produto.

date_formatstring

Formato de data (DD/MM/YYYY).

currency_formatstring

Máscara de moeda (R$ #.###,##).

pwa_enabledboolean

A loja usa o modo de aplicativo instalável (PWA).

rendering_enginestring

layoutstheme_builder

Fonte que desenha a loja: layouts avançados ou o construtor de temas. O front-end deve confiar neste campo e não misturar os dois.

preferred_layout_editorstring

visualadvancedtheme_builder

Editor de layout que o painel abre por padrão. Não afeta a vitrine.

listing_strict_stockboolean

Presente só quando ligado: com show_out_of_stock desligado, também esconde produtos de reserva e grupos de variação sem filho em estoque.

Filtros da lateral

GET/api/v1/storefront/settings/filtersPública

Consulta a configuração da barra lateral de filtros da vitrine

Diz quais painéis de filtro mostrar nas listagens e como chamá-los.

Exemplo de requisição

bash

curl "$BASE_URL/api/v1/storefront/settings/filters"

Resposta

200Filtros

json

{
  "enable_price_filter": true,
  "enable_brand_filter": true,
  "enable_feature_filters": true,
  "enable_vendor_filter": false,
  "enable_stock_filter": false,
  "enable_free_shipping_filter": true,
  "price_filter": true,
  "price_filter_name": "Preço",
  "stock_filter": true,
  "stock_filter_name": "Em estoque",
  "free_shipping_filter": true,
  "free_shipping_filter_name": "Frete grátis",
  "vendor_filter": true,
  "vendor_filter_name": "Vendedor",
  "feature_display_names": {
    "537e1e37-c45d-4451-973e-833246808099": "Material do produto"
  }
}

Campos da resposta

enable_price_filterboolean

Chave geral do filtro de preço.

enable_brand_filterboolean

Chave geral do filtro de marca.

enable_feature_filtersboolean

Chave geral dos filtros por característica (cor, material...).

enable_vendor_filterboolean

Chave geral do filtro de seller.

enable_stock_filterboolean

Chave geral do filtro "em estoque".

enable_free_shipping_filterboolean

Chave geral do filtro "frete grátis".

price_filterboolean

Filtro de preço ligado na tela de filtros do painel.

price_filter_namestring

Rótulo do filtro de preço.

stock_filterboolean

Filtro de estoque ligado.

stock_filter_namestring

Rótulo do filtro de estoque.

free_shipping_filterboolean

Filtro de frete grátis ligado.

free_shipping_filter_namestring

Rótulo do filtro de frete grátis.

vendor_filterboolean

Filtro de seller ligado.

vendor_filter_namestring

Rótulo do filtro de seller.

feature_display_namesobject

Mapa id da característica (UUID) para o rótulo que a lateral deve mostrar no lugar do nome original da característica. Ausente quando não há ajustes.

Busca ao vivo

GET/api/v1/storefront/settings/searchPública

Consulta a configuração da busca ao vivo

Configura a caixa de busca com sugestões enquanto o cliente digita e escolhe o motor da página de resultados.

Exemplo de requisição

bash

curl "$BASE_URL/api/v1/storefront/settings/search"

Resposta

200Busca

json

{
  "live_search_enabled": true,
  "min_query_length": 2,
  "products_under_categories": false,
  "search_brands": true,
  "search_categories": true,
  "search_products": true,
  "search_vendors": false,
  "semantic_search_enabled": true,
  "show_product_images": true,
  "show_product_prices": true
}

Campos da resposta

live_search_enabledboolean

Mostrar sugestões enquanto o cliente digita.

min_query_lengthinteger

Quantidade mínima de caracteres antes de buscar.

search_productsboolean

As sugestões incluem produtos.

search_categoriesboolean

As sugestões incluem categorias.

search_brandsboolean

As sugestões incluem marcas.

search_vendorsboolean

As sugestões incluem sellers.

products_under_categoriesboolean

Mostrar produtos agrupados sob a categoria encontrada.

show_product_pricesboolean

Mostrar preço nas sugestões.

show_product_imagesboolean

Mostrar imagem nas sugestões.

semantic_search_enabledboolean

A busca combina texto e significado (busca híbrida). Quando true, a página de resultados usa a rota de busca completa, que devolve marcas e características como filtros.

Erros

Status	Quando	Corpo
404	Loja não identificada	`{"error":"tenant not found","message":"could not resolve storefront from request"}`
500	Falha ao ler	`{"error":"failed to get search settings","detail":"..."}`

Veja também

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

Aparência, filtros e busca

Lê como a loja quer exibir as listagens (colunas, ordem, imagens, formatos), quais filtros mostrar na lateral e como a busca ao vivo se comporta.

Aparência

GET/api/v1/storefront/settings/appearancePública

Consulta as configurações de aparência da vitrine

Devolve todas as opções de aparência, que são seguras para o público.

Exemplo de requisição

bash

curl "$BASE_URL/api/v1/storefront/settings/appearance"

Resposta

200Aparência

json

{
  "products_per_page": 20,
  "products_per_row": 4,
  "default_product_sorting": "newest",
  "default_sort_order": "desc",
  "show_prices_with_tax": true,
  "show_out_of_stock": true,
  "pwa_enabled": false,
  "show_zero_price": true,
  "enable_quick_view": true,
  "thumbnail_width": 300,
  "thumbnail_height": 300,
  "product_detail_image_size": 800,
  "categories_per_page": 12,
  "available_per_page_values": "10,20,50,100",
  "show_product_code": true,
  "show_product_weight": false,
  "show_product_stock": true,
  "backorder_notice_enabled": true,
  "backorder_notice_text": "",
  "date_format": "DD/MM/YYYY",
  "currency_format": "R$ #.###,##",
  "preferred_layout_editor": "visual",
  "rendering_engine": "layouts",
  "sticky_buybar_enabled": true,
  "product_card_template": "modern",
  "listing_view_modes": ["grid-2", "grid-3", "grid-4", "list"],
  "listing_default_view": "grid-4"
}

Campos da resposta

products_per_pageinteger

Produtos por página nas listagens.

available_per_page_valuesstring

Opções de "itens por página" separadas por vírgula ("10,20,50,100").

products_per_rowinteger

Colunas da grade de produtos.

categories_per_pageinteger

Categorias por página.

default_product_sortingstring

namepricenewestpopularity

Campo de ordenação inicial.

default_sort_orderstring

ascdesc

Sentido da ordenação inicial.

listing_view_modesarray

Modos de visualização oferecidos na barra da listagem: grid-2, grid-3, grid-4, list. Com um só modo, esconda o seletor.

listing_default_viewstring

grid-2grid-3grid-4list

Modo inicial para quem não tem preferência salva. Sempre é um dos modos de listing_view_modes.

product_card_templatestring

defaultmodernfashiontechcompact

Modelo visual do cartão de produto.

show_prices_with_taxboolean

Exibir preços com imposto incluído.

show_out_of_stockboolean

Listar produtos sem estoque.

show_zero_priceboolean

Listar produtos com preço zero. Quando false, produto sem preço some das listagens e a página dele responde 404.

enable_quick_viewboolean

Janela de visualização rápida do produto.

thumbnail_widthinteger

Largura das miniaturas, em pixels.

thumbnail_heightinteger

Altura das miniaturas, em pixels.

product_detail_image_sizeinteger

Largura da imagem principal da página do produto, em pixels.

show_product_codeboolean

Mostrar o SKU na página do produto.

show_product_weightboolean

Mostrar o peso.

show_product_stockboolean

Mostrar a disponibilidade de estoque.

backorder_notice_enabledboolean

Mostrar aviso "sob encomenda" em produto sem estoque que vende por encomenda.

backorder_notice_textstring

Texto do aviso. Vazio: use o texto padrão traduzido ("Sob encomenda").

sticky_buybar_enabledboolean

Barra fixa de compra na página do produto.

date_formatstring

Formato de data (DD/MM/YYYY).

currency_formatstring

Máscara de moeda (R$ #.###,##).

pwa_enabledboolean

A loja usa o modo de aplicativo instalável (PWA).

rendering_enginestring

layoutstheme_builder

Fonte que desenha a loja: layouts avançados ou o construtor de temas. O front-end deve confiar neste campo e não misturar os dois.

preferred_layout_editorstring

visualadvancedtheme_builder

Editor de layout que o painel abre por padrão. Não afeta a vitrine.

listing_strict_stockboolean

Presente só quando ligado: com show_out_of_stock desligado, também esconde produtos de reserva e grupos de variação sem filho em estoque.

Filtros da lateral

GET/api/v1/storefront/settings/filtersPública

Consulta a configuração da barra lateral de filtros da vitrine

Diz quais painéis de filtro mostrar nas listagens e como chamá-los.

Exemplo de requisição

bash

curl "$BASE_URL/api/v1/storefront/settings/filters"

Resposta

200Filtros

json

{
  "enable_price_filter": true,
  "enable_brand_filter": true,
  "enable_feature_filters": true,
  "enable_vendor_filter": false,
  "enable_stock_filter": false,
  "enable_free_shipping_filter": true,
  "price_filter": true,
  "price_filter_name": "Preço",
  "stock_filter": true,
  "stock_filter_name": "Em estoque",
  "free_shipping_filter": true,
  "free_shipping_filter_name": "Frete grátis",
  "vendor_filter": true,
  "vendor_filter_name": "Vendedor",
  "feature_display_names": {
    "537e1e37-c45d-4451-973e-833246808099": "Material do produto"
  }
}

Campos da resposta

enable_price_filterboolean

Chave geral do filtro de preço.

enable_brand_filterboolean

Chave geral do filtro de marca.

enable_feature_filtersboolean

Chave geral dos filtros por característica (cor, material...).

enable_vendor_filterboolean

Chave geral do filtro de seller.

enable_stock_filterboolean

Chave geral do filtro "em estoque".

enable_free_shipping_filterboolean

Chave geral do filtro "frete grátis".

price_filterboolean

Filtro de preço ligado na tela de filtros do painel.

price_filter_namestring

Rótulo do filtro de preço.

stock_filterboolean

Filtro de estoque ligado.

stock_filter_namestring

Rótulo do filtro de estoque.

free_shipping_filterboolean

Filtro de frete grátis ligado.

free_shipping_filter_namestring

Rótulo do filtro de frete grátis.

vendor_filterboolean

Filtro de seller ligado.

vendor_filter_namestring

Rótulo do filtro de seller.

feature_display_namesobject

Mapa id da característica (UUID) para o rótulo que a lateral deve mostrar no lugar do nome original da característica. Ausente quando não há ajustes.

Busca ao vivo

GET/api/v1/storefront/settings/searchPública

Consulta a configuração da busca ao vivo

Configura a caixa de busca com sugestões enquanto o cliente digita e escolhe o motor da página de resultados.

Exemplo de requisição

bash

curl "$BASE_URL/api/v1/storefront/settings/search"

Resposta

200Busca

json

{
  "live_search_enabled": true,
  "min_query_length": 2,
  "products_under_categories": false,
  "search_brands": true,
  "search_categories": true,
  "search_products": true,
  "search_vendors": false,
  "semantic_search_enabled": true,
  "show_product_images": true,
  "show_product_prices": true
}

Campos da resposta

live_search_enabledboolean

Mostrar sugestões enquanto o cliente digita.

min_query_lengthinteger

Quantidade mínima de caracteres antes de buscar.

search_productsboolean

As sugestões incluem produtos.

search_categoriesboolean

As sugestões incluem categorias.

search_brandsboolean

As sugestões incluem marcas.

search_vendorsboolean

As sugestões incluem sellers.

products_under_categoriesboolean

Mostrar produtos agrupados sob a categoria encontrada.

show_product_pricesboolean

Mostrar preço nas sugestões.

show_product_imagesboolean

Mostrar imagem nas sugestões.

semantic_search_enabledboolean

A busca combina texto e significado (busca híbrida). Quando true, a página de resultados usa a rota de busca completa, que devolve marcas e características como filtros.

Erros

Status	Quando	Corpo
404	Loja não identificada	`{"error":"tenant not found","message":"could not resolve storefront from request"}`
500	Falha ao ler	`{"error":"failed to get search settings","detail":"..."}`