API atual/Referência completa/Tema e layout

Layouts de página

Lê o layout de uma página (a árvore de contêineres, linhas, colunas e blocos), os blocos compartilhados de cabeçalho e rodapé e o layout simples antigo.

Um layout diz quais blocos aparecem em uma página e em que lugar. As duas rotas principais são page-layout/{dispatch} (a página inteira) e shared-layout (as partes comuns a todas as páginas: painel superior, cabeçalho e rodapé). A terceira, layout/{dispatch}, é o sistema simples antigo, mantido só por compatibilidade.

Todas são públicas, sem cache, e filtram no servidor os blocos restritos a grupos de clientes que o visitante não tem: o corpo não carrega o campo de restrição nem os blocos escondidos.

Layout de uma página

GET/api/v1/storefront/page-layout/{dispatch}Pública

Consulta o layout avançado de uma página

Devolve o layout da página identificada por dispatch. A API escolhe o melhor candidato, nesta ordem: (1) a página específica de um objeto, se você passar object_id (por exemplo, um produto ou categoria com layout próprio); (2) a página padrão daquele dispatch; (3) a página catch-all default. Por isso um dispatch desconhecido não dá erro: ele recebe o layout default. Só responde 204 quando a loja não tem layout nenhum.

Quando a loja tem um tema ativo, o layout do tema ativo tem prioridade; se ele não tiver a página, vale o layout padrão geral.

Parâmetros de caminho

dispatchstringobrigatório

Identificador da página, como index.index (home), categories.view, products.view, search.view, checkout.cart, auth.login. Veja a lista na home da seção.

Parâmetros de consulta

object_idstring

Id (UUID) de um produto, categoria ou outro objeto com layout próprio. Opcional.

layout_idinteger

Renderiza um layout específico (por exemplo, um rascunho) em vez do padrão. Usado pelo editor ao vivo. Com ele, nenhum bloco é escondido por restrição de grupo.

preview_draftstring

1

Com 1, sobrepõe o rascunho do editor visual clássico ao layout publicado. Combine com layout_id.

Exemplo de requisição

bash

curl "$BASE_URL/api/v1/storefront/page-layout/products.view?object_id=22fbd12a-1b6e-41ea-a84f-4d9cf06c8766"

Resposta

200Layout da página

json

{
  "layout": { "id": 166, "name": "Default", "theme_variant": "", "is_default": true },
  "page": {
    "id": 3788,
    "layout_id": 166,
    "dispatch": "default",
    "name": "Default (Catch-all)",
    "is_default": true,
    "position": 0,
    "seo_title": "",
    "seo_description": "",
    "seo_keywords": "",
    "og_image": "",
    "og_type": "website",
    "canonical_url": "",
    "no_index": false,
    "custom_html_code": ""
  },
  "containers": [
    { "id": 14434, "page_id": 3788, "position": "top_panel", "sort_order": 0, "uses_default": false },
    { "id": 14435, "page_id": 3788, "position": "header", "sort_order": 1, "uses_default": false },
    {
      "id": 14436,
      "page_id": 3788,
      "position": "content",
      "sort_order": 2,
      "uses_default": false,
      "rows": [
        {
          "id": 11189,
          "container_id": 14436,
          "sort_order": 0,
          "full_width": true,
          "spacing": "normal",
          "display_mode": "normal",
          "visibility": { "desktop": true, "tablet": true, "mobile": true },
          "columns": [
            {
              "id": 11958,
              "row_id": 11189,
              "sort_order": 0,
              "width_desktop": 12,
              "width_tablet": 12,
              "width_mobile": 12,
              "visibility": { "desktop": true, "tablet": true, "mobile": true },
              "blocks": [
                {
                  "id": 15257,
                  "column_id": 11958,
                  "block_type": "main_content",
                  "sort_order": 0,
                  "name": "Main Content",
                  "config": {},
                  "content": {},
                  "visibility": { "desktop": true, "tablet": true, "mobile": true },
                  "status": "A",
                  "cache_ttl": 300
                }
              ]
            }
          ]
        }
      ]
    },
    { "id": 14437, "page_id": 3788, "position": "footer", "sort_order": 3, "uses_default": false }
  ]
}

A resposta real é maior (a mesma resposta lista todas as páginas do layout em layout.pages); o exemplo acima mostra só o necessário para desenhar uma página.

Campos da resposta

layoutobject

O conjunto de layouts a que a página pertence: id, name, theme_variant, is_default e a lista pages.

pageobject

A página escolhida para este dispatch.

page.dispatchstring

Dispatch da página escolhida. Pode ser default mesmo que você tenha pedido outro (veja acima).

page.seo_titlestring

Título SEO configurado para a página. Vazio quando não há.

page.seo_descriptionstring

Descrição SEO.

page.seo_keywordsstring

Palavras-chave SEO.

page.og_imagestring

Imagem de compartilhamento (Open Graph).

page.og_typestring

Tipo Open Graph (website).

page.canonical_urlstring

URL canônica da página, se fixada.

page.no_indexboolean

true: a página não deve ser indexada por buscadores.

page.custom_html_codestring

HTML personalizado da página.

containersarray

Contêineres da página já resolvidos (com os compartilhados do layout padrão). Cada um tem position (top_panel, header, content, footer), sort_order e, quando tem conteúdo próprio, rows.

containers[].uses_defaultboolean

true quando o contêiner herda o conteúdo do layout padrão.

containers[].rows[]object

Linhas: full_width, spacing (tight, normal...), display_mode, visibility por tamanho de tela e columns.

containers[].rows[].columns[]object

Colunas: width_desktop, width_tablet, width_mobile (largura numa grade de 12), visibility e blocks.

blocks[].block_typestring

Tipo do bloco (breadcrumbs, main_content, banners, listas de produtos...).

blocks[].configobject

Configuração do bloco, específica de cada block_type.

blocks[].contentobject

Conteúdo estático do bloco, quando houver.

blocks[].statusstring

A quando o bloco está ativo.

blocks[].cache_ttlinteger

Sugestão de cache do bloco, em segundos.

Erros

Status	Quando	Corpo
204	A loja não tem layout configurado	corpo vazio
404	Loja não identificada	`{"error":"tenant not found","message":"could not resolve storefront from request"}`
500	Falha ao ler o layout	`{"error":"failed to get page layout","detail":"..."}`

Blocos compartilhados

GET/api/v1/storefront/shared-layoutPública

Consulta os contêineres compartilhados (painel superior, cabeçalho, rodapé)

Devolve os contêineres top_panel, header e footer do layout padrão, que o casco da vitrine desenha em todas as páginas. Busque uma vez e reaproveite entre páginas. Sem parâmetros. Responde 204 se a loja não tem contêineres compartilhados (use o cabeçalho e o rodapé padrão do seu front-end).

Exemplo de requisição

bash

curl "$BASE_URL/api/v1/storefront/shared-layout"

Resposta

200Contêineres compartilhados

json

{
  "containers": [
    { "id": 14434, "page_id": 3788, "position": "top_panel", "sort_order": 0, "uses_default": false },
    { "id": 14435, "page_id": 3788, "position": "header", "sort_order": 1, "uses_default": false },
    { "id": 14437, "page_id": 3788, "position": "footer", "sort_order": 3, "uses_default": false }
  ]
}

Campos da resposta

containersarray

Contêineres compartilhados, no mesmo formato de containers de uma página (com rows, columns e blocks quando têm conteúdo).

Erros

Status	Quando	Corpo
204	Sem contêineres compartilhados	corpo vazio
500	Falha ao ler	`{"error":"failed to get shared layout","detail":"..."}`

Layout simples (descontinuado)

GET/api/v1/storefront/layout/{dispatch}Pública

Consulta o layout simples legado de um tipo de página

Sistema antigo de layout em lista plana de blocos. Não use em integrações novas: use page-layout. A rota traduz o dispatch em um tipo de página (index.index e index para homepage, products.view para product, categories.view para category, companies.view para vendor) e devolve o layout padrão desse tipo. Qualquer outro valor vira homepage, então layout/qualquer-coisa devolve o layout da home. Responde 204 se não houver layout.

Parâmetros de caminho

dispatchstringobrigatório

index.index, index, products.view, categories.view ou companies.view. Outros valores caem na home.

Exemplo de requisição

bash

curl "$BASE_URL/api/v1/storefront/layout/index.index"

Resposta

200Layout simples

json

{
  "id": 9,
  "name": "Standard Homepage",
  "page_type": "homepage",
  "is_default": true,
  "blocks": [
    {
      "id": "1a1a2400-e07f-4529-b73e-b557538817fa",
      "type": "logo",
      "position": "header",
      "order": 0,
      "title": "Store Logo",
      "config": { "alignment": "left", "alt_text": "Store Logo", "link_to_home": true, "max_height": 60 },
      "visible": true
    },
    {
      "id": "8fba21e9-c053-4d95-82b2-33ad8f1ceaff",
      "type": "featured_products",
      "position": "main",
      "order": 0,
      "title": "Featured Products",
      "config": { "columns": 4, "count": 8, "sort": "popular", "title": "Featured Products", "view_type": "grid" },
      "visible": true
    }
  ]
}

Campos da resposta

idinteger

Id do layout.

namestring

Nome do layout.

page_typestring

homepageproductcategoryvendor

Tipo de página a que serve.

is_defaultboolean

true quando é o layout padrão desse tipo.

blocksarray

Blocos em lista plana.

blocks[].typestring

Tipo do bloco (logo, search_bar, hero_banner, featured_products...).

blocks[].positionstring

Região da página (header, main_top, main, main_bottom...).

blocks[].orderinteger

Ordem dentro da região.

blocks[].configobject

Configuração específica do tipo.

blocks[].visibleboolean

Se o bloco está visível.

Erros

Status	Quando	Corpo
204	Nenhum layout configurado	corpo vazio
500	Falha ao ler	`{"error":"failed to get layout","detail":"..."}`

Veja também

API atual/Referência completa/Tema e layout

Layouts de página

Lê o layout de uma página (a árvore de contêineres, linhas, colunas e blocos), os blocos compartilhados de cabeçalho e rodapé e o layout simples antigo.

Todas são públicas, sem cache, e filtram no servidor os blocos restritos a grupos de clientes que o visitante não tem: o corpo não carrega o campo de restrição nem os blocos escondidos.

Layout de uma página

GET/api/v1/storefront/page-layout/{dispatch}Pública

Consulta o layout avançado de uma página

Quando a loja tem um tema ativo, o layout do tema ativo tem prioridade; se ele não tiver a página, vale o layout padrão geral.

Parâmetros de caminho

dispatchstringobrigatório

Identificador da página, como index.index (home), categories.view, products.view, search.view, checkout.cart, auth.login. Veja a lista na home da seção.

Parâmetros de consulta

object_idstring

Id (UUID) de um produto, categoria ou outro objeto com layout próprio. Opcional.

layout_idinteger

Renderiza um layout específico (por exemplo, um rascunho) em vez do padrão. Usado pelo editor ao vivo. Com ele, nenhum bloco é escondido por restrição de grupo.

preview_draftstring

1

Com 1, sobrepõe o rascunho do editor visual clássico ao layout publicado. Combine com layout_id.

Exemplo de requisição

bash

curl "$BASE_URL/api/v1/storefront/page-layout/products.view?object_id=22fbd12a-1b6e-41ea-a84f-4d9cf06c8766"

Resposta

200Layout da página

json

{
  "layout": { "id": 166, "name": "Default", "theme_variant": "", "is_default": true },
  "page": {
    "id": 3788,
    "layout_id": 166,
    "dispatch": "default",
    "name": "Default (Catch-all)",
    "is_default": true,
    "position": 0,
    "seo_title": "",
    "seo_description": "",
    "seo_keywords": "",
    "og_image": "",
    "og_type": "website",
    "canonical_url": "",
    "no_index": false,
    "custom_html_code": ""
  },
  "containers": [
    { "id": 14434, "page_id": 3788, "position": "top_panel", "sort_order": 0, "uses_default": false },
    { "id": 14435, "page_id": 3788, "position": "header", "sort_order": 1, "uses_default": false },
    {
      "id": 14436,
      "page_id": 3788,
      "position": "content",
      "sort_order": 2,
      "uses_default": false,
      "rows": [
        {
          "id": 11189,
          "container_id": 14436,
          "sort_order": 0,
          "full_width": true,
          "spacing": "normal",
          "display_mode": "normal",
          "visibility": { "desktop": true, "tablet": true, "mobile": true },
          "columns": [
            {
              "id": 11958,
              "row_id": 11189,
              "sort_order": 0,
              "width_desktop": 12,
              "width_tablet": 12,
              "width_mobile": 12,
              "visibility": { "desktop": true, "tablet": true, "mobile": true },
              "blocks": [
                {
                  "id": 15257,
                  "column_id": 11958,
                  "block_type": "main_content",
                  "sort_order": 0,
                  "name": "Main Content",
                  "config": {},
                  "content": {},
                  "visibility": { "desktop": true, "tablet": true, "mobile": true },
                  "status": "A",
                  "cache_ttl": 300
                }
              ]
            }
          ]
        }
      ]
    },
    { "id": 14437, "page_id": 3788, "position": "footer", "sort_order": 3, "uses_default": false }
  ]
}

A resposta real é maior (a mesma resposta lista todas as páginas do layout em layout.pages); o exemplo acima mostra só o necessário para desenhar uma página.

Campos da resposta

layoutobject

O conjunto de layouts a que a página pertence: id, name, theme_variant, is_default e a lista pages.

pageobject

A página escolhida para este dispatch.

page.dispatchstring

Dispatch da página escolhida. Pode ser default mesmo que você tenha pedido outro (veja acima).

page.seo_titlestring

Título SEO configurado para a página. Vazio quando não há.

page.seo_descriptionstring

Descrição SEO.

page.seo_keywordsstring

Palavras-chave SEO.

page.og_imagestring

Imagem de compartilhamento (Open Graph).

page.og_typestring

Tipo Open Graph (website).

page.canonical_urlstring

URL canônica da página, se fixada.

page.no_indexboolean

true: a página não deve ser indexada por buscadores.

page.custom_html_codestring

HTML personalizado da página.

containersarray

containers[].uses_defaultboolean

true quando o contêiner herda o conteúdo do layout padrão.

containers[].rows[]object

Linhas: full_width, spacing (tight, normal...), display_mode, visibility por tamanho de tela e columns.

containers[].rows[].columns[]object

Colunas: width_desktop, width_tablet, width_mobile (largura numa grade de 12), visibility e blocks.

blocks[].block_typestring

Tipo do bloco (breadcrumbs, main_content, banners, listas de produtos...).

blocks[].configobject

Configuração do bloco, específica de cada block_type.

blocks[].contentobject

Conteúdo estático do bloco, quando houver.

blocks[].statusstring

A quando o bloco está ativo.

blocks[].cache_ttlinteger

Sugestão de cache do bloco, em segundos.

Erros

Status	Quando	Corpo
204	A loja não tem layout configurado	corpo vazio
404	Loja não identificada	`{"error":"tenant not found","message":"could not resolve storefront from request"}`
500	Falha ao ler o layout	`{"error":"failed to get page layout","detail":"..."}`

Blocos compartilhados

GET/api/v1/storefront/shared-layoutPública

Consulta os contêineres compartilhados (painel superior, cabeçalho, rodapé)

Exemplo de requisição

bash

curl "$BASE_URL/api/v1/storefront/shared-layout"

Resposta

200Contêineres compartilhados

json

{
  "containers": [
    { "id": 14434, "page_id": 3788, "position": "top_panel", "sort_order": 0, "uses_default": false },
    { "id": 14435, "page_id": 3788, "position": "header", "sort_order": 1, "uses_default": false },
    { "id": 14437, "page_id": 3788, "position": "footer", "sort_order": 3, "uses_default": false }
  ]
}

Campos da resposta

containersarray

Contêineres compartilhados, no mesmo formato de containers de uma página (com rows, columns e blocks quando têm conteúdo).

Erros

Status	Quando	Corpo
204	Sem contêineres compartilhados	corpo vazio
500	Falha ao ler	`{"error":"failed to get shared layout","detail":"..."}`

Layout simples (descontinuado)

GET/api/v1/storefront/layout/{dispatch}Pública

Consulta o layout simples legado de um tipo de página

Parâmetros de caminho

dispatchstringobrigatório

index.index, index, products.view, categories.view ou companies.view. Outros valores caem na home.

Exemplo de requisição

bash

curl "$BASE_URL/api/v1/storefront/layout/index.index"

Resposta

200Layout simples

json

{
  "id": 9,
  "name": "Standard Homepage",
  "page_type": "homepage",
  "is_default": true,
  "blocks": [
    {
      "id": "1a1a2400-e07f-4529-b73e-b557538817fa",
      "type": "logo",
      "position": "header",
      "order": 0,
      "title": "Store Logo",
      "config": { "alignment": "left", "alt_text": "Store Logo", "link_to_home": true, "max_height": 60 },
      "visible": true
    },
    {
      "id": "8fba21e9-c053-4d95-82b2-33ad8f1ceaff",
      "type": "featured_products",
      "position": "main",
      "order": 0,
      "title": "Featured Products",
      "config": { "columns": 4, "count": 8, "sort": "popular", "title": "Featured Products", "view_type": "grid" },
      "visible": true
    }
  ]
}

Campos da resposta

idinteger

Id do layout.

namestring

Nome do layout.

page_typestring

homepageproductcategoryvendor

Tipo de página a que serve.

is_defaultboolean

true quando é o layout padrão desse tipo.

blocksarray

Blocos em lista plana.

blocks[].typestring

Tipo do bloco (logo, search_bar, hero_banner, featured_products...).

blocks[].positionstring

Região da página (header, main_top, main, main_bottom...).

blocks[].orderinteger

Ordem dentro da região.

blocks[].configobject

Configuração específica do tipo.

blocks[].visibleboolean

Se o bloco está visível.

Erros

Status	Quando	Corpo
204	Nenhum layout configurado	corpo vazio
500	Falha ao ler	`{"error":"failed to get layout","detail":"..."}`