API atual/Referência completa/Vitrine: layout, menus e temas

Preferências de exibição

Lê e altera como a vitrine lista e mostra os produtos: itens por página, ordenação, cartão de produto, estoque, formato de data e moeda.

As preferências de exibição controlam o comportamento visual das listagens e da página do produto: quantos produtos por página e por linha, a ordenação inicial, se produtos esgotados aparecem, qual desenho de cartão de produto usar, que informações mostrar e como formatar datas e moeda. A vitrine lê estas preferências a cada visita; a mesma configuração também é publicada para o público na rota da vitrine GET /api/v1/storefront/settings/appearance.

Exigem o privilégio manage_settings.

Ler as preferências

GET/api/v1/admin/settings/appearanceAdmin

Ler as preferências de exibição, com os padrões aplicados

Devolve todas as preferências. Campos que a loja nunca configurou vêm com o valor padrão.

bash

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

200Preferências

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"
}

Alterar as preferências

PUT/api/v1/admin/settings/appearanceAdmin

Alterar as preferências de exibição

Envia só os campos que quer mudar: o corpo é mesclado com o que já está salvo (os campos que você não mandar ficam como estão). A resposta traz as preferências completas, já com os padrões aplicados.

Corpo da requisição

products_per_pageintegerpadrão: 20

Produtos por página nas listagens.

products_per_rowintegerpadrão: 4

Colunas da grade de produtos.

default_product_sortingstringpadrão: newest

namepricenewestpopularity

Campo de ordenação inicial.

default_sort_orderstring

ascdesc

Sentido da ordenação.

show_prices_with_taxboolean

Se os preços exibidos incluem imposto.

show_out_of_stockboolean

Se produtos sem estoque aparecem nas listagens.

listing_strict_stockbooleanpadrão: false

Com show_out_of_stock desligado, também esconde produtos de "avise-me" e grupos de variação sem filho em estoque.

pwa_enabledbooleanpadrão: false

Se a vitrine registra o aplicativo instalável (PWA). Desligado, a vitrine desregistra o que já estava instalado nos navegadores dos visitantes.

show_zero_pricebooleanpadrão: true

Se produtos com preço zero aparecem. Desligado, somem das listagens e a página do produto responde 404.

enable_quick_viewboolean

Visualização rápida ao passar o mouse no cartão.

thumbnail_widthintegerpadrão: 300

Largura da miniatura, em pixels.

thumbnail_heightintegerpadrão: 300

Altura da miniatura, em pixels.

product_detail_image_sizeintegerpadrão: 800

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

categories_per_pageintegerpadrão: 12

Categorias por página.

available_per_page_valuesstringpadrão: 10,20,50,100

Opções de itens por página oferecidas ao cliente, separadas por vírgula.

show_product_codeboolean

Mostra o código (SKU) na página do produto.

show_product_weightboolean

Mostra o peso na página do produto.

show_product_stockbooleanpadrão: true

Mostra a disponibilidade em estoque na página do produto. Se a chave faltar, vale true.

backorder_notice_enabledbooleanpadrão: true

Mostra o aviso "sob encomenda" em produtos esgotados que vendem sob encomenda.

backorder_notice_textstring

Texto do aviso. Vazio usa o texto padrão traduzido.

date_formatstringpadrão: DD/MM/YYYY

Formato de exibição de datas.

currency_formatstringpadrão: R$ #.###,##

Formato de exibição de moeda.

preferred_layout_editorstringpadrão: visual

visualadvancedtheme_builder

Editor de layout que o painel abre por padrão.

rendering_enginestringpadrão: layouts

layoutstheme_builder

Qual motor desenha a vitrine para o cliente. A vitrine confia nesta chave e não alterna sozinha entre os motores.

sticky_buybar_enabledbooleanpadrão: true

Barra de compra fixa na página do produto.

product_card_templatestringpadrão: default

defaultmodernfashiontechcompact

Desenho do cartão de produto.

listing_view_modesarray

Modos de visualização que a barra da listagem oferece, entre grid-2, grid-3, grid-4 e list. Vazio oferece todos.

listing_default_viewstringpadrão: grid-4

Modo inicial para quem não tem preferência salva. Precisa estar em listing_view_modes; se não estiver, é corrigido automaticamente.

bash

curl -X PUT "$BASE_URL/api/v1/admin/settings/appearance" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"products_per_page":24,"product_card_template":"compact"}'

Resposta

200Preferências atualizadas

O corpo é o mesmo objeto da leitura, com as alterações aplicadas.

Campos da resposta

*any

Os mesmos campos descritos no corpo da requisição, todos presentes e com os padrões aplicados. Um campo ausente no corpo guardado volta com o padrão indicado.

Erros

Status	Quando	Corpo de exemplo
400	Corpo que não é JSON, ou vazio.	`{"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 gravar.	`{"error":"failed to update appearance settings","detail":"..."}`

Veja também

Preferências de exibição

Lê e altera como a vitrine lista e mostra os produtos: itens por página, ordenação, cartão de produto, estoque, formato de data e moeda.

Exigem o privilégio manage_settings.

Ler as preferências

GET/api/v1/admin/settings/appearanceAdmin

Ler as preferências de exibição, com os padrões aplicados

Devolve todas as preferências. Campos que a loja nunca configurou vêm com o valor padrão.

bash

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

200Preferências

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"
}

Alterar as preferências

PUT/api/v1/admin/settings/appearanceAdmin

Alterar as preferências de exibição

Corpo da requisição

products_per_pageintegerpadrão: 20

Produtos por página nas listagens.

products_per_rowintegerpadrão: 4

Colunas da grade de produtos.

default_product_sortingstringpadrão: newest

namepricenewestpopularity

Campo de ordenação inicial.

default_sort_orderstring

ascdesc

Sentido da ordenação.

show_prices_with_taxboolean

Se os preços exibidos incluem imposto.

show_out_of_stockboolean

Se produtos sem estoque aparecem nas listagens.

listing_strict_stockbooleanpadrão: false

Com show_out_of_stock desligado, também esconde produtos de "avise-me" e grupos de variação sem filho em estoque.

pwa_enabledbooleanpadrão: false

Se a vitrine registra o aplicativo instalável (PWA). Desligado, a vitrine desregistra o que já estava instalado nos navegadores dos visitantes.

show_zero_pricebooleanpadrão: true

Se produtos com preço zero aparecem. Desligado, somem das listagens e a página do produto responde 404.

enable_quick_viewboolean

Visualização rápida ao passar o mouse no cartão.

thumbnail_widthintegerpadrão: 300

Largura da miniatura, em pixels.

thumbnail_heightintegerpadrão: 300

Altura da miniatura, em pixels.

product_detail_image_sizeintegerpadrão: 800

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

categories_per_pageintegerpadrão: 12

Categorias por página.

available_per_page_valuesstringpadrão: 10,20,50,100

Opções de itens por página oferecidas ao cliente, separadas por vírgula.

show_product_codeboolean

Mostra o código (SKU) na página do produto.

show_product_weightboolean

Mostra o peso na página do produto.

show_product_stockbooleanpadrão: true

Mostra a disponibilidade em estoque na página do produto. Se a chave faltar, vale true.

backorder_notice_enabledbooleanpadrão: true

Mostra o aviso "sob encomenda" em produtos esgotados que vendem sob encomenda.

backorder_notice_textstring

Texto do aviso. Vazio usa o texto padrão traduzido.

date_formatstringpadrão: DD/MM/YYYY

Formato de exibição de datas.

currency_formatstringpadrão: R$ #.###,##

Formato de exibição de moeda.

preferred_layout_editorstringpadrão: visual

visualadvancedtheme_builder

Editor de layout que o painel abre por padrão.

rendering_enginestringpadrão: layouts

layoutstheme_builder

Qual motor desenha a vitrine para o cliente. A vitrine confia nesta chave e não alterna sozinha entre os motores.

sticky_buybar_enabledbooleanpadrão: true

Barra de compra fixa na página do produto.

product_card_templatestringpadrão: default

defaultmodernfashiontechcompact

Desenho do cartão de produto.

listing_view_modesarray

Modos de visualização que a barra da listagem oferece, entre grid-2, grid-3, grid-4 e list. Vazio oferece todos.

listing_default_viewstringpadrão: grid-4

Modo inicial para quem não tem preferência salva. Precisa estar em listing_view_modes; se não estiver, é corrigido automaticamente.

bash

curl -X PUT "$BASE_URL/api/v1/admin/settings/appearance" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"products_per_page":24,"product_card_template":"compact"}'

Resposta

200Preferências atualizadas

O corpo é o mesmo objeto da leitura, com as alterações aplicadas.

Campos da resposta

*any

Os mesmos campos descritos no corpo da requisição, todos presentes e com os padrões aplicados. Um campo ausente no corpo guardado volta com o padrão indicado.

Erros

Status	Quando	Corpo de exemplo
400	Corpo que não é JSON, ou vazio.	`{"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 gravar.	`{"error":"failed to update appearance settings","detail":"..."}`