VenddorDocumentação API
API atualAPI legada
Guia rápidoReferência completa
Carregando índice…
API atual/Referência completa/Layouts avançados

Criar e gerenciar layouts

Cria, renomeia, duplica, promove a padrão e exclui layouts avançados da loja.

Um layout é a "planta" completa da vitrine. A loja pode ter vários, mas só o marcado como padrão (is_default) é servido aos clientes. Estas cinco rotas cobrem o ciclo de vida do layout inteiro. Para editar o conteúdo dele, veja as páginas de estrutura e de blocos.

Escritas aqui mudam a loja no ar

Promover um layout a padrão troca o que os clientes veem imediatamente. Para editar sem risco, trabalhe em um rascunho e publique no fim.

Criar layout

Cria um layout novo. Por padrão ele nasce como cópia profunda do layout padrão atual (mesmas páginas, linhas e blocos), para você partir de uma base que funciona. Se a loja ainda não tem layout padrão, ou se você enviar seed_blank: true, nasce um layout vazio.

POST/api/v1/admin/advanced-layoutsAdmin

Criar um layout

Requer o privilégio manage_layouts.

Corpo da requisição

namestringobrigatório
Nome do layout.
theme_variantstringpadrão: default
Variante visual do tema.
is_defaultbooleanpadrão: false
Marca o novo layout como padrão. Só é considerado quando o layout nasce vazio.
seed_blankbooleanpadrão: false
true cria um layout vazio em vez de copiar o padrão.
theme_iduuid
Tema da vitrine ao qual o layout pertence. Só é considerado no layout vazio; a cópia do padrão não recebe este valor.

Exemplo de requisição

bash
curl -X POST "$BASE_URL/api/v1/admin/advanced-layouts" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Layout da Black Friday",
    "seed_blank": false
  }'

Resposta

201Layout criado
json
{
  "id": 135,
  "name": "Novo Layout Avançado",
  "theme_variant": "default",
  "is_default": false,
  "pages": [
    {
      "id": 2930,
      "layout_id": 135,
      "dispatch": "index.index",
      "name": "Homepage",
      "is_default": false,
      "position": 1,
      "seo_title": "",
      "seo_description": "",
      "seo_keywords": "",
      "og_image": "",
      "og_type": "website",
      "canonical_url": "",
      "no_index": false,
      "custom_html_code": "",
      "created_at": "2026-07-12T16:29:12.505299Z",
      "containers": [
        {
          "id": 11056,
          "page_id": 2930,
          "position": "content",
          "sort_order": 0,
          "uses_default": false,
          "rows": [
            {
              "id": 8029,
              "container_id": 11056,
              "sort_order": 0,
              "full_width": false,
              "spacing": "normal",
              "display_mode": "normal",
              "visibility": {
                "desktop": true,
                "tablet": true,
                "mobile": true
              },
              "columns": [
                {
                  "id": 8786,
                  "row_id": 8029,
                  "sort_order": 0,
                  "width_desktop": 12,
                  "width_tablet": 12,
                  "width_mobile": 12,
                  "visibility": {
                    "desktop": true,
                    "tablet": true,
                    "mobile": true
                  },
                  "blocks": [
                    {
                      "id": 11081,
                      "column_id": 8786,
                      "block_type": "banner_slider",
                      "sort_order": 0,
                      "name": "Main Banner",
                      "config": {
                        "autoplay": true,
                        "interval": 5000,
                        "show_arrows": true
                      },
                      "content": {},
                      "visibility": {
                        "desktop": true,
                        "tablet": true,
                        "mobile": true
                      },
                      "status": "A",
                      "cache_ttl": 300,
                      "updated_at": "2026-07-12T16:29:12.505299Z"
                    }
                  ]
                }
              ]
            }
          ]
        }
      ]
    }
  ],
  "created_at": "2026-07-12T16:29:12.505299Z",
  "updated_at": "2026-07-12T16:29:12.505299Z"
}

Campos da resposta

idinteger
Id do layout.
namestring
Nome do layout.
theme_variantstring
Variante visual do tema (default, machic...). É só um rótulo para o editor.
is_defaultboolean
true no layout que a vitrine está servindo. Só um por loja (e por tema).
pagesarray
Páginas do layout. Em GET por id cada página traz containers, com linhas, colunas e blocos aninhados.
created_atstring
Criação (RFC 3339).
updated_atstring
Última alteração (RFC 3339).

Erros

StatusQuandoCorpo de exemplo
400Corpo JSON inválido.{"error":"invalid request body","detail":"unexpected EOF"}
400name vazio.{"error":"name is required"}
401Sem token, token inválido ou expirado.{"error":"invalid or expired token"}
403Seu usuário não tem o privilégio manage_layouts.{"error":"insufficient privileges","required":"manage_layouts"}
500Falha ao gravar ou ler no banco, ou id inexistente onde a rota não trata 404.{"error":"failed to create layout","detail":"..."}
Layout vazio quase nunca é o que você quer

Uma vitrine sem cabeçalho, rodapé e corpo de página é inútil. Prefira a cópia do padrão e depois altere, ou use predefinições para montar seções.

Atualizar layout

Altera o nome, a variante ou o flag de padrão. Todos os campos são opcionais e só os enviados mudam. Enviar is_default: true rebaixa o layout padrão anterior na mesma transação, então a loja nunca fica com dois padrões.

PUT/api/v1/admin/advanced-layouts/{id}Admin

Atualizar nome, variante ou padrão

Requer o privilégio manage_layouts.

Parâmetros de caminho

idintegerobrigatório
Id numérico do layout (inteiro, não UUID).

Corpo da requisição

namestring
Novo nome.
theme_variantstring
Nova variante.
is_defaultboolean
true promove a padrão.

Exemplo de requisição

bash
curl -X PUT "$BASE_URL/api/v1/admin/advanced-layouts/135" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Layout da Black Friday 2026"
  }'

Resposta

200Layout atualizado
json
{
  "id": 135,
  "name": "Novo Layout Avançado",
  "theme_variant": "default",
  "is_default": false,
  "created_at": "2026-07-12T16:29:12.505299Z",
  "updated_at": "2026-07-12T16:29:12.505299Z"
}

Campos da resposta

idinteger
Id do layout.
namestring
Nome do layout.
theme_variantstring
Variante visual do tema (default, machic...). É só um rótulo para o editor.
is_defaultboolean
true no layout que a vitrine está servindo. Só um por loja (e por tema).
created_atstring
Criação (RFC 3339).
updated_atstring
Última alteração (RFC 3339).

Erros

StatusQuandoCorpo de exemplo
400O id de layout no caminho não é um inteiro.{"error":"invalid layout id","detail":"id must be an integer"}
400Corpo JSON inválido.{"error":"invalid request body","detail":"unexpected EOF"}
401Sem token, token inválido ou expirado.{"error":"invalid or expired token"}
403Seu usuário não tem o privilégio manage_layouts.{"error":"insufficient privileges","required":"manage_layouts"}
500Falha ao gravar ou ler no banco, ou id inexistente onde a rota não trata 404.{"error":"failed to update layout","detail":"..."}

Excluir layout

Exclui o layout e toda a sua árvore (páginas, contêineres, linhas, colunas, blocos). Não dá para excluir o layout padrão: promova outro antes.

DELETE/api/v1/admin/advanced-layouts/{id}Admin

Excluir um layout

Requer o privilégio manage_layouts.

Parâmetros de caminho

idintegerobrigatório
Id numérico do layout (inteiro, não UUID).

Exemplo de requisição

bash
curl -X DELETE "$BASE_URL/api/v1/admin/advanced-layouts/135" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Excluído
json
{
  "message": "layout deleted"
}

Erros

StatusQuandoCorpo de exemplo
400O id de layout no caminho não é um inteiro.{"error":"invalid layout id","detail":"id must be an integer"}
401Sem token, token inválido ou expirado.{"error":"invalid or expired token"}
403Seu usuário não tem o privilégio manage_layouts.{"error":"insufficient privileges","required":"manage_layouts"}
404Layout não existe.{"error":"layout not found","detail":"135"}
409É o layout padrão.{"error":"cannot delete default layout","detail":"promote another layout to default before deleting this one"}
500Falha ao gravar ou ler no banco, ou id inexistente onde a rota não trata 404.{"error":"failed to delete layout","detail":"..."}
Não há lixeira

A exclusão é definitiva. Se existe qualquer dúvida, duplique antes de excluir.

Duplicar layout

Copia o layout inteiro (páginas, contêineres, linhas, colunas e blocos) para um layout novo, não padrão, e devolve a árvore da cópia. Se name vier vazio, o nome é <original> (copy). O corpo é opcional.

POST/api/v1/admin/advanced-layouts/{id}/cloneAdmin

Duplicar um layout

Requer o privilégio manage_layouts.

Parâmetros de caminho

idintegerobrigatório
Id numérico do layout (inteiro, não UUID).

Corpo da requisição

namestring
Nome da cópia.

Exemplo de requisição

bash
curl -X POST "$BASE_URL/api/v1/admin/advanced-layouts/135/clone" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Teste de rodapé"
  }'

Resposta

201Cópia criada
json
{
  "id": 136,
  "name": "Teste de rodapé",
  "theme_variant": "default",
  "is_default": false,
  "pages": [
    {
      "id": 2930,
      "layout_id": 135,
      "dispatch": "index.index",
      "name": "Homepage",
      "is_default": false,
      "position": 1,
      "seo_title": "",
      "seo_description": "",
      "seo_keywords": "",
      "og_image": "",
      "og_type": "website",
      "canonical_url": "",
      "no_index": false,
      "custom_html_code": "",
      "created_at": "2026-07-12T16:29:12.505299Z",
      "containers": [
        {
          "id": 11056,
          "page_id": 2930,
          "position": "content",
          "sort_order": 0,
          "uses_default": false,
          "rows": [
            {
              "id": 8029,
              "container_id": 11056,
              "sort_order": 0,
              "full_width": false,
              "spacing": "normal",
              "display_mode": "normal",
              "visibility": {
                "desktop": true,
                "tablet": true,
                "mobile": true
              },
              "columns": [
                {
                  "id": 8786,
                  "row_id": 8029,
                  "sort_order": 0,
                  "width_desktop": 12,
                  "width_tablet": 12,
                  "width_mobile": 12,
                  "visibility": {
                    "desktop": true,
                    "tablet": true,
                    "mobile": true
                  },
                  "blocks": [
                    {
                      "id": 11081,
                      "column_id": 8786,
                      "block_type": "banner_slider",
                      "sort_order": 0,
                      "name": "Main Banner",
                      "config": {
                        "autoplay": true,
                        "interval": 5000,
                        "show_arrows": true
                      },
                      "content": {},
                      "visibility": {
                        "desktop": true,
                        "tablet": true,
                        "mobile": true
                      },
                      "status": "A",
                      "cache_ttl": 300,
                      "updated_at": "2026-07-12T16:29:12.505299Z"
                    }
                  ]
                }
              ]
            }
          ]
        }
      ]
    }
  ],
  "created_at": "2026-07-12T16:29:12.505299Z",
  "updated_at": "2026-07-12T16:29:12.505299Z"
}

Campos da resposta

idinteger
Id do layout.
namestring
Nome do layout.
theme_variantstring
Variante visual do tema (default, machic...). É só um rótulo para o editor.
is_defaultboolean
true no layout que a vitrine está servindo. Só um por loja (e por tema).
pagesarray
Páginas do layout. Em GET por id cada página traz containers, com linhas, colunas e blocos aninhados.
created_atstring
Criação (RFC 3339).
updated_atstring
Última alteração (RFC 3339).

Erros

StatusQuandoCorpo de exemplo
400O id de layout no caminho não é um inteiro.{"error":"invalid layout id","detail":"id must be an integer"}
401Sem token, token inválido ou expirado.{"error":"invalid or expired token"}
403Seu usuário não tem o privilégio manage_layouts.{"error":"insufficient privileges","required":"manage_layouts"}
404O layout de origem não existe.{"error":"layout not found","detail":"135"}
500Falha ao gravar ou ler no banco, ou id inexistente onde a rota não trata 404.{"error":"failed to clone layout","detail":"..."}

Definir layout padrão

Torna o layout o único padrão da loja: o flag é removido de todos os outros na mesma transação. A vitrine passa a servir esse layout na próxima requisição de página. Não há corpo.

POST/api/v1/admin/advanced-layouts/{id}/set-defaultAdmin

Promover um layout a padrão

Requer o privilégio manage_layouts.

Parâmetros de caminho

idintegerobrigatório
Id numérico do layout (inteiro, não UUID).

Exemplo de requisição

bash
curl -X POST "$BASE_URL/api/v1/admin/advanced-layouts/135/set-default" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Layout agora é o padrão
json
{
  "id": 135,
  "name": "Novo Layout Avançado",
  "theme_variant": "default",
  "is_default": true,
  "created_at": "2026-07-12T16:29:12.505299Z",
  "updated_at": "2026-07-12T16:29:12.505299Z"
}

Campos da resposta

idinteger
Id do layout.
namestring
Nome do layout.
theme_variantstring
Variante visual do tema (default, machic...). É só um rótulo para o editor.
is_defaultboolean
true no layout que a vitrine está servindo. Só um por loja (e por tema).
created_atstring
Criação (RFC 3339).
updated_atstring
Última alteração (RFC 3339).

Erros

StatusQuandoCorpo de exemplo
400O id de layout no caminho não é um inteiro.{"error":"invalid layout id","detail":"id must be an integer"}
401Sem token, token inválido ou expirado.{"error":"invalid or expired token"}
403Seu usuário não tem o privilégio manage_layouts.{"error":"insufficient privileges","required":"manage_layouts"}
404Layout não existe.{"error":"layout not found","detail":"135"}
500Falha ao gravar ou ler no banco, ou id inexistente onde a rota não trata 404.{"error":"failed to set default layout","detail":"..."}

Veja também

  • Layouts avançados: visão geral
  • Rascunho e publicação
Anterior
Consultar layouts
Próxima
Páginas do layout
Nesta página
  • Criar layout
  • Exemplo de requisição
  • Resposta
  • Erros
  • Atualizar layout
  • Exemplo de requisição
  • Resposta
  • Erros
  • Excluir layout
  • Exemplo de requisição
  • Resposta
  • Erros
  • Duplicar layout
  • Exemplo de requisição
  • Resposta
  • Erros
  • Definir layout padrão
  • Exemplo de requisição
  • Resposta
  • Erros
  • Veja também