API atual/Referência completa/Layouts simples

Layouts

Lista, consulta, cria, altera e exclui layouts simples, com filtros por tipo de página.

Operações de cadastro sobre o layout simples. Veja a visão geral para entender a diferença para o layout avançado. Todas exigem o privilégio manage_layouts.

Listar layouts

GET/api/v1/admin/layoutsAdmin

Lista layouts simples com paginação

Devolve os layouts com a lista completa de blocos de cada um.

Parâmetros de consulta

page_typestring

homepageproductcategoryvendorcustom

Filtra pelo tipo de página (igualdade exata). Um valor desconhecido simplesmente não encontra nada.

searchstring

Texto contido no nome, sem diferenciar maiúsculas.

pageintegerpadrão: 1

Página, a partir de 1.

per_pageintegerpadrão: 20

Itens por página, de 1 a 100. Fora disso volta a 20.

Exemplo de requisição

bash

curl "$BASE_URL/api/v1/admin/layouts?page_type=category" \
  -H "Authorization: Bearer $TOKEN"

200Layouts retornados

json

{
  "layouts": [
    {
      "id": 11,
      "name": "Standard Category Page",
      "page_type": "category",
      "is_default": true,
      "blocks": [
        {
          "id": "15055a16-fa48-4e96-a536-167209748c80",
          "type": "logo",
          "position": "header",
          "order": 0,
          "title": "Store Logo",
          "config": { "link_to_home": true, "max_height": 60 },
          "visible": true
        }
      ],
      "created_at": "2026-07-13T13:01:48.048186Z",
      "updated_at": "2026-07-13T13:01:48.048186Z"
    }
  ],
  "total": 1,
  "page": 1,
  "per_page": 20,
  "total_pages": 1
}

Campos da resposta

layoutsarray

Layouts da página. É null (não []) quando nada atende ao filtro.

layouts[].idinteger

Id do layout.

layouts[].namestring

Nome.

layouts[].page_typestring

Tipo de página.

layouts[].is_defaultboolean

Se é o layout padrão do tipo de página.

layouts[].blocksarray

Blocos, com id (UUID em texto), type, position, order, title, config e visible.

layouts[].created_atstring

Criação (RFC 3339, UTC).

layouts[].updated_atstring

Última alteração (RFC 3339, UTC).

totalinteger

Total de layouts que atendem ao filtro.

pageinteger

Página retornada.

per_pageinteger

Itens por página aplicados.

total_pagesinteger

Quantidade de páginas.

Consultar layout

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

Consulta um layout simples

Parâmetros de caminho

idintegerobrigatório

Id do layout.

A resposta 200 é um objeto no formato de layouts[].

Criar layout

POST/api/v1/admin/layoutsAdmin

Cria um layout simples

Blocos sem id recebem um UUID gerado pelo servidor. O layout nasce com is_default igual a false: use definir padrão depois.

Corpo da requisição

namestringobrigatório

Nome do layout.

page_typestringpadrão: homepage

homepageproductcategoryvendorcustom

Tipo de página.

blocksarray

Blocos iniciais.

201Layout criado

json

{
  "id": 14,
  "name": "Home de Natal",
  "page_type": "homepage",
  "is_default": false,
  "blocks": [
    {
      "id": "6f1d3a9e-8b2c-4c57-9e7a-1c2d3e4f5a6b",
      "type": "text_html",
      "position": "main_top",
      "order": 0,
      "title": "Aviso",
      "config": { "html_content": "<p>Frete grátis</p>" },
      "visible": true
    }
  ],
  "created_at": "2026-10-11T15:00:00.000Z",
  "updated_at": "2026-10-11T15:00:00.000Z"
}

Alterar layout

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

Altera nome, tipo, padrão ou a lista de blocos

Alteração parcial dos campos do layout, mas blocks, quando enviado, substitui a lista inteira. Pelo menos um campo é obrigatório.

Parâmetros de caminho

idintegerobrigatório

Id do layout.

Corpo da requisição

namestring

Novo nome.

page_typestring

homepageproductcategoryvendorcustom

Novo tipo de página.

is_defaultboolean

Marca ou desmarca como padrão. Marcar aqui não desmarca o padrão anterior do mesmo tipo; para trocar o padrão use set-default.

blocksarray

Nova lista completa de blocos. Máximo de 1 MB de JSON.

A resposta 200 é o layout atualizado.

Excluir layout

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

Exclui definitivamente um layout simples

Exclusão definitiva, sem lixeira. Não há bloqueio para o layout padrão.

Parâmetros de caminho

idintegerobrigatório

Id do layout.

200Layout excluído

json

{ "message": "layout deleted" }

Erros

Status	Quando	Corpo
400	`id` que não é inteiro; corpo inválido; `name` ausente na criação	`{"error":"invalid layout id","detail":"id must be an integer"}` ou `{"error":"name is required"}`
401	Sem token ou token expirado	`{"error":"missing authorization header"}`
403	Sem o privilégio `manage_layouts`	`{"error":"insufficient privileges","required":"manage_layouts"}`
404	Layout inexistente (consultar)	`{"error":"layout not found"}`
500	`page_type` inválido; `PUT` sem campos; layout inexistente em alterar ou excluir; blocos acima de 1 MB	`{"error":"failed to create layout","detail":"invalid page type: promo"}`

Veja também

API atual/Referência completa/Layouts simples

Layouts

Lista, consulta, cria, altera e exclui layouts simples, com filtros por tipo de página.

Operações de cadastro sobre o layout simples. Veja a visão geral para entender a diferença para o layout avançado. Todas exigem o privilégio manage_layouts.

Listar layouts

GET/api/v1/admin/layoutsAdmin

Lista layouts simples com paginação

Devolve os layouts com a lista completa de blocos de cada um.

Parâmetros de consulta

page_typestring

homepageproductcategoryvendorcustom

Filtra pelo tipo de página (igualdade exata). Um valor desconhecido simplesmente não encontra nada.

searchstring

Texto contido no nome, sem diferenciar maiúsculas.

pageintegerpadrão: 1

Página, a partir de 1.

per_pageintegerpadrão: 20

Itens por página, de 1 a 100. Fora disso volta a 20.

Exemplo de requisição

bash

curl "$BASE_URL/api/v1/admin/layouts?page_type=category" \
  -H "Authorization: Bearer $TOKEN"

200Layouts retornados

json

{
  "layouts": [
    {
      "id": 11,
      "name": "Standard Category Page",
      "page_type": "category",
      "is_default": true,
      "blocks": [
        {
          "id": "15055a16-fa48-4e96-a536-167209748c80",
          "type": "logo",
          "position": "header",
          "order": 0,
          "title": "Store Logo",
          "config": { "link_to_home": true, "max_height": 60 },
          "visible": true
        }
      ],
      "created_at": "2026-07-13T13:01:48.048186Z",
      "updated_at": "2026-07-13T13:01:48.048186Z"
    }
  ],
  "total": 1,
  "page": 1,
  "per_page": 20,
  "total_pages": 1
}

Campos da resposta

layoutsarray

Layouts da página. É null (não []) quando nada atende ao filtro.

layouts[].idinteger

Id do layout.

layouts[].namestring

Nome.

layouts[].page_typestring

Tipo de página.

layouts[].is_defaultboolean

Se é o layout padrão do tipo de página.

layouts[].blocksarray

Blocos, com id (UUID em texto), type, position, order, title, config e visible.

layouts[].created_atstring

Criação (RFC 3339, UTC).

layouts[].updated_atstring

Última alteração (RFC 3339, UTC).

totalinteger

Total de layouts que atendem ao filtro.

pageinteger

Página retornada.

per_pageinteger

Itens por página aplicados.

total_pagesinteger

Quantidade de páginas.

Consultar layout

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

Consulta um layout simples

Parâmetros de caminho

idintegerobrigatório

Id do layout.

A resposta 200 é um objeto no formato de layouts[].

Criar layout

POST/api/v1/admin/layoutsAdmin

Cria um layout simples

Blocos sem id recebem um UUID gerado pelo servidor. O layout nasce com is_default igual a false: use definir padrão depois.

Corpo da requisição

namestringobrigatório

Nome do layout.

page_typestringpadrão: homepage

homepageproductcategoryvendorcustom

Tipo de página.

blocksarray

Blocos iniciais.

201Layout criado

json

{
  "id": 14,
  "name": "Home de Natal",
  "page_type": "homepage",
  "is_default": false,
  "blocks": [
    {
      "id": "6f1d3a9e-8b2c-4c57-9e7a-1c2d3e4f5a6b",
      "type": "text_html",
      "position": "main_top",
      "order": 0,
      "title": "Aviso",
      "config": { "html_content": "<p>Frete grátis</p>" },
      "visible": true
    }
  ],
  "created_at": "2026-10-11T15:00:00.000Z",
  "updated_at": "2026-10-11T15:00:00.000Z"
}

Alterar layout

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

Altera nome, tipo, padrão ou a lista de blocos

Alteração parcial dos campos do layout, mas blocks, quando enviado, substitui a lista inteira. Pelo menos um campo é obrigatório.

Parâmetros de caminho

idintegerobrigatório

Id do layout.

Corpo da requisição

namestring

Novo nome.

page_typestring

homepageproductcategoryvendorcustom

Novo tipo de página.

is_defaultboolean

Marca ou desmarca como padrão. Marcar aqui não desmarca o padrão anterior do mesmo tipo; para trocar o padrão use set-default.

blocksarray

Nova lista completa de blocos. Máximo de 1 MB de JSON.

A resposta 200 é o layout atualizado.

Excluir layout

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

Exclui definitivamente um layout simples

Exclusão definitiva, sem lixeira. Não há bloqueio para o layout padrão.

Parâmetros de caminho

idintegerobrigatório

Id do layout.

200Layout excluído

json

{ "message": "layout deleted" }

Erros

Status	Quando	Corpo
400	`id` que não é inteiro; corpo inválido; `name` ausente na criação	`{"error":"invalid layout id","detail":"id must be an integer"}` ou `{"error":"name is required"}`
401	Sem token ou token expirado	`{"error":"missing authorization header"}`
403	Sem o privilégio `manage_layouts`	`{"error":"insufficient privileges","required":"manage_layouts"}`
404	Layout inexistente (consultar)	`{"error":"layout not found"}`
500	`page_type` inválido; `PUT` sem campos; layout inexistente em alterar ou excluir; blocos acima de 1 MB	`{"error":"failed to create layout","detail":"invalid page type: promo"}`