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

Consultar layouts

Lista os layouts da loja, abre a árvore completa de um layout e consulta seu histórico de alterações.

Estas três rotas só leem. Use a lista para descobrir qual layout está no ar (is_default: true), o GET por id para obter a árvore inteira (páginas, contêineres, linhas, colunas e blocos) e o histórico para saber quem mudou o quê.

Listar layouts

Retorna os layouts do tema ativo da loja (ou do tema pedido em theme_id), com as páginas de cada um, sem a árvore de blocos. Layouts de rascunho do editor ao vivo e cópias antigas com nome repetido são escondidos da lista, mas continuam acessíveis pelo id.

GET/api/v1/admin/advanced-layoutsAdmin

Listar layouts

Requer o privilégio manage_layouts.

Parâmetros de consulta

theme_iduuid
Id do tema da vitrine para filtrar. Se omitido, usa o tema ativo; sem tema ativo, devolve todos os layouts.

Exemplo de requisição

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

Resposta

200Layouts retornados
json
{
  "layouts": [
    {
      "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"
        }
      ],
      "created_at": "2026-07-12T16:29:12.505299Z",
      "updated_at": "2026-07-12T16:29:12.505299Z"
    }
  ]
}

Campos da resposta

layoutsarray

Lista de layouts.

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
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 list layouts","detail":"..."}
As páginas vêm na lista

Apesar de ser um resumo, cada layout traz o array pages (sem contêineres). A árvore de blocos só vem em GET /advanced-layouts/{id}.

Obter um layout

Retorna o layout com todas as páginas e, dentro de cada página, os quatro contêineres (top_panel, header, content, footer) com suas linhas, colunas e blocos. É a resposta que um editor visual precisa para desenhar a tela. As visibilidades por grupo de comprador não são filtradas aqui: o administrador vê tudo.

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

Obter a árvore de 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 GET "$BASE_URL/api/v1/admin/advanced-layouts/135" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Árvore do layout
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).
pages[].containersarray
Contêineres da página. Cada um tem id, page_id, position, sort_order, uses_default (veja a visão geral) e rows.

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"}
500Falha ao gravar ou ler no banco, ou id inexistente onde a rota não trata 404.{"error":"failed to get layout","detail":"..."}

Histórico do layout

Retorna o log de alterações do layout, da mais nova para a mais antiga: criação, edição, exclusão e reordenação de páginas, linhas, colunas e blocos, com quem fez (id e e-mail do administrador).

GET/api/v1/admin/advanced-layouts/{id}/historyAdmin

Histórico de alterações de um layout

Requer o privilégio manage_layouts.

Parâmetros de caminho

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

Parâmetros de consulta

limitintegerpadrão: 50
Máximo de registros. Se omitido, zero ou negativo, usa 50.

Exemplo de requisição

bash
curl -X GET "$BASE_URL/api/v1/admin/advanced-layouts/135/history?limit=20" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Histórico
json
{
  "history": [
    {
      "id": 1029,
      "layout_id": 135,
      "entity_type": "layout",
      "entity_id": 135,
      "action": "create_from_default",
      "changes": "{\"new_name\": \"Novo Layout Avançado\", \"source_id\": 122}",
      "changed_by": "67bf291c-0846-4053-9528-8cfd5ab0ebf1",
      "changed_by_email": "admin@minhaloja.com.br",
      "created_at": "2026-07-12 16:29:12.936594+00"
    }
  ],
  "total": 1
}

Campos da resposta

historyarray

Registros, do mais novo ao mais antigo.

idinteger
Id do registro.
layout_idinteger
Layout afetado.
page_idinteger
Página afetada, quando houver.
entity_typestring
O que mudou: layout, page, container, row, column ou block.
entity_idinteger
Id da entidade alterada.
actionstring
Ação registrada, por exemplo create, update, delete, reorder.
changesstring
Detalhes da alteração como texto contendo JSON (é preciso fazer JSON.parse).
changed_bystring
UUID do administrador.
changed_by_emailstring
E-mail do administrador.
created_atstring
Data e hora no formato do banco (2026-07-12 16:29:12.936594+00), não RFC 3339.
totalinteger
Quantidade de registros devolvidos (não o total existente).

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"}
500Falha ao gravar ou ler no banco, ou id inexistente onde a rota não trata 404.{"error":"failed to get layout history","detail":"..."}
Sem layout inexistente aqui

Um id que não existe devolve 200 com history: [], não 404.

Veja também

  • Layouts avançados: visão geral
  • Criar e gerenciar layouts
Anterior
Layouts avançados
Próxima
Criar e gerenciar layouts
Nesta página
  • Listar layouts
  • Exemplo de requisição
  • Resposta
  • Erros
  • Obter um layout
  • Exemplo de requisição
  • Resposta
  • Erros
  • Histórico do layout
  • Exemplo de requisição
  • Resposta
  • Erros
  • Veja também