API atual/Referência completa/Layouts avançados

Biblioteca de blocos

Salva um bloco configurado na biblioteca e insere cópias dele em outras colunas.

A biblioteca guarda modelos de blocos para reutilizar. Inserir um item na coluna cria uma cópia independente: depois disso, editar a cópia não muda o modelo, nem o contrário. Quando você quer que uma mudança se propague para todos os lugares, use um bloco reutilizável.

Listar a biblioteca

Devolve todos os itens salvos, incluindo os modelos globais que vêm com a plataforma e os blocos reutilizáveis (eles são a mesma tabela).

GET/api/v1/admin/advanced-layouts/libraryAdmin

Listar itens da biblioteca

Requer o privilégio manage_layouts.

Exemplo de requisição

bash

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

Resposta

200Itens

json

{
  "library": [
    {
      "id": 12,
      "block_type": "categories_grid",
      "name": "Categorias em destaque",
      "config": {
        "columns": 4,
        "count": 8,
        "title": "Compre por Categoria"
      },
      "content": {},
      "is_global": false,
      "created_at": "2026-07-13T13:51:26.232664Z"
    }
  ]
}

Campos da resposta

libraryarray

Itens da biblioteca.

idinteger

Id do item da biblioteca.

block_typestring

Tipo do bloco.

namestring

Nome do item.

configobject

Opções salvas.

contentobject

Conteúdo salvo.

designobject

Estilo salvo, quando houver.

is_globalboolean

Item marcado como global.

created_atstring

Criação (RFC 3339).

Erros

Status	Quando	Corpo de exemplo
401	Sem token, token inválido ou expirado.	`{"error":"invalid or expired token"}`
403	Seu usuário não tem o privilégio `manage_layouts`.	`{"error":"insufficient privileges","required":"manage_layouts"}`
500	Falha ao gravar ou ler no banco, ou id inexistente onde a rota não trata 404.	`{"error":"failed to list block library","detail":"..."}`

Salvar na biblioteca

Grava uma configuração de bloco como modelo. Você envia a configuração; a rota não lê um bloco existente. Para guardar um bloco que já está numa página, leia-o e reenvie block_type, config, content e design.

POST/api/v1/admin/advanced-layouts/libraryAdmin

Salvar um bloco na biblioteca

Requer o privilégio manage_layouts.

Corpo da requisição

block_typestringobrigatório

Tipo do bloco.

namestringobrigatório

Nome do item.

configobjectpadrão: {}

Opções.

contentobjectpadrão: {}

Conteúdo.

designobject

Camada de estilo universal (fundo, espaçamento, borda, sombra, tipografia, tamanho, efeitos), com sobrescritas por breakpoint em base, tablet e mobile. O formato dos campos vem de Esquema de design. Opcional.

is_globalbooleanpadrão: false

Marca como global.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/admin/advanced-layouts/library" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "block_type": "categories_grid",
    "name": "Categorias em destaque",
    "config": {
      "columns": 4,
      "count": 8,
      "title": "Compre por Categoria"
    }
  }'

Resposta

201Item criado

json

{
  "id": 12,
  "block_type": "categories_grid",
  "name": "Categorias em destaque",
  "config": {
    "columns": 4,
    "count": 8,
    "title": "Compre por Categoria"
  },
  "content": {},
  "is_global": false,
  "created_at": "2026-07-13T13:51:26.232664Z"
}

Campos da resposta

idinteger

Id do item da biblioteca.

block_typestring

Tipo do bloco.

namestring

Nome do item.

configobject

Opções salvas.

contentobject

Conteúdo salvo.

designobject

Estilo salvo, quando houver.

is_globalboolean

Item marcado como global.

created_atstring

Criação (RFC 3339).

Erros

Status	Quando	Corpo de exemplo
400	Corpo JSON inválido.	`{"error":"invalid request body","detail":"unexpected EOF"}`
400	`block_type` vazio.	`{"error":"block_type is required"}`
400	`name` vazio.	`{"error":"name is required"}`
401	Sem token, token inválido ou expirado.	`{"error":"invalid or expired token"}`
403	Seu usuário não tem o privilégio `manage_layouts`.	`{"error":"insufficient privileges","required":"manage_layouts"}`
500	Falha ao gravar ou ler no banco, ou id inexistente onde a rota não trata 404.	`{"error":"failed to save to library","detail":"..."}`

Inserir da biblioteca

Cria na coluna um bloco novo (cópia) com o tipo, a configuração, o conteúdo e o design do item.

POST/api/v1/admin/advanced-layouts/library/{id}/addAdmin

Inserir um item da biblioteca numa coluna

Requer o privilégio manage_layouts.

Parâmetros de caminho

idintegerobrigatório

Id numérico do item da biblioteca.

Corpo da requisição

column_idintegerobrigatório

Coluna onde o bloco será criado.

sort_orderintegerpadrão: 0

Posição na coluna.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/admin/advanced-layouts/library/12/add" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "column_id": 8786,
    "sort_order": 1
  }'

Resposta

201Bloco criado

json

{
  "id": 11130,
  "column_id": 8786,
  "block_type": "categories_grid",
  "sort_order": 1,
  "name": "Categorias em destaque",
  "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"
}

Campos da resposta

idinteger

Id do bloco.

column_idinteger

Id da coluna onde o bloco está.

block_typestring

Tipo do bloco, por exemplo banner_slider. A lista completa vem de Catálogo de blocos.

sort_orderinteger

Posição do bloco na coluna.

namestring

Nome de exibição no editor.

configobject

Configurações do tipo de bloco (as chaves de settings do catálogo).

contentobject

Conteúdo livre do bloco.

visibilityobject

Visibilidade por dispositivo.

usergroup_idsstring[]

Grupos de compradores que veem o bloco. Ausente quando vazio.

statusstring

Status em letra: A (ativo) ou D (inativo).

cache_ttlinteger

Tempo de cache do bloco, em segundos.

custom_classstring

Classe CSS extra do bloco.

custom_cssstring

CSS livre do bloco.

wrapperstring

Moldura do título: vazio, h1_main, h2_important, h3_ordinary, footer, onclick_dropdown, filter_wrapper ou card.

designobject

Camada de estilo universal.

reusable_block_idinteger

Presente quando o bloco é uma instância vinculada de um bloco reutilizável.

created_atstring

Criação (RFC 3339).

updated_atstring

Última alteração (RFC 3339).

Erros

Status	Quando	Corpo de exemplo
400	O id de library no caminho não é um inteiro.	`{"error":"invalid library id","detail":"id must be an integer"}`
400	Corpo JSON inválido.	`{"error":"invalid request body","detail":"unexpected EOF"}`
400	`column_id` ausente ou zero.	`{"error":"column_id is required"}`
401	Sem token, token inválido ou expirado.	`{"error":"invalid or expired token"}`
403	Seu usuário não tem o privilégio `manage_layouts`.	`{"error":"insufficient privileges","required":"manage_layouts"}`
500	Item da biblioteca ou coluna inexistente, ou tipo que já atingiu o limite por página.	`{"error":"failed to add from library","detail":"..."}`

Veja também

API atual/Referência completa/Layouts avançados

Biblioteca de blocos

Salva um bloco configurado na biblioteca e insere cópias dele em outras colunas.

Listar a biblioteca

Devolve todos os itens salvos, incluindo os modelos globais que vêm com a plataforma e os blocos reutilizáveis (eles são a mesma tabela).

GET/api/v1/admin/advanced-layouts/libraryAdmin

Listar itens da biblioteca

Requer o privilégio manage_layouts.

Exemplo de requisição

bash

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

Resposta

200Itens

json

{
  "library": [
    {
      "id": 12,
      "block_type": "categories_grid",
      "name": "Categorias em destaque",
      "config": {
        "columns": 4,
        "count": 8,
        "title": "Compre por Categoria"
      },
      "content": {},
      "is_global": false,
      "created_at": "2026-07-13T13:51:26.232664Z"
    }
  ]
}

Campos da resposta

libraryarray

Itens da biblioteca.

idinteger

Id do item da biblioteca.

block_typestring

Tipo do bloco.

namestring

Nome do item.

configobject

Opções salvas.

contentobject

Conteúdo salvo.

designobject

Estilo salvo, quando houver.

is_globalboolean

Item marcado como global.

created_atstring

Criação (RFC 3339).

Erros

Status	Quando	Corpo de exemplo
401	Sem token, token inválido ou expirado.	`{"error":"invalid or expired token"}`
403	Seu usuário não tem o privilégio `manage_layouts`.	`{"error":"insufficient privileges","required":"manage_layouts"}`
500	Falha ao gravar ou ler no banco, ou id inexistente onde a rota não trata 404.	`{"error":"failed to list block library","detail":"..."}`

Salvar na biblioteca

POST/api/v1/admin/advanced-layouts/libraryAdmin

Salvar um bloco na biblioteca

Requer o privilégio manage_layouts.

Corpo da requisição

block_typestringobrigatório

Tipo do bloco.

namestringobrigatório

Nome do item.

configobjectpadrão: {}

Opções.

contentobjectpadrão: {}

Conteúdo.

designobject

is_globalbooleanpadrão: false

Marca como global.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/admin/advanced-layouts/library" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "block_type": "categories_grid",
    "name": "Categorias em destaque",
    "config": {
      "columns": 4,
      "count": 8,
      "title": "Compre por Categoria"
    }
  }'

Resposta

201Item criado

json

{
  "id": 12,
  "block_type": "categories_grid",
  "name": "Categorias em destaque",
  "config": {
    "columns": 4,
    "count": 8,
    "title": "Compre por Categoria"
  },
  "content": {},
  "is_global": false,
  "created_at": "2026-07-13T13:51:26.232664Z"
}

Campos da resposta

idinteger

Id do item da biblioteca.

block_typestring

Tipo do bloco.

namestring

Nome do item.

configobject

Opções salvas.

contentobject

Conteúdo salvo.

designobject

Estilo salvo, quando houver.

is_globalboolean

Item marcado como global.

created_atstring

Criação (RFC 3339).

Erros

Status	Quando	Corpo de exemplo
400	Corpo JSON inválido.	`{"error":"invalid request body","detail":"unexpected EOF"}`
400	`block_type` vazio.	`{"error":"block_type is required"}`
400	`name` vazio.	`{"error":"name is required"}`
401	Sem token, token inválido ou expirado.	`{"error":"invalid or expired token"}`
403	Seu usuário não tem o privilégio `manage_layouts`.	`{"error":"insufficient privileges","required":"manage_layouts"}`
500	Falha ao gravar ou ler no banco, ou id inexistente onde a rota não trata 404.	`{"error":"failed to save to library","detail":"..."}`

Inserir da biblioteca

Cria na coluna um bloco novo (cópia) com o tipo, a configuração, o conteúdo e o design do item.

POST/api/v1/admin/advanced-layouts/library/{id}/addAdmin

Inserir um item da biblioteca numa coluna

Requer o privilégio manage_layouts.

Parâmetros de caminho

idintegerobrigatório

Id numérico do item da biblioteca.

Corpo da requisição

column_idintegerobrigatório

Coluna onde o bloco será criado.

sort_orderintegerpadrão: 0

Posição na coluna.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/admin/advanced-layouts/library/12/add" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "column_id": 8786,
    "sort_order": 1
  }'

Resposta

201Bloco criado

json

{
  "id": 11130,
  "column_id": 8786,
  "block_type": "categories_grid",
  "sort_order": 1,
  "name": "Categorias em destaque",
  "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"
}

Campos da resposta

idinteger

Id do bloco.

column_idinteger

Id da coluna onde o bloco está.

block_typestring

Tipo do bloco, por exemplo banner_slider. A lista completa vem de Catálogo de blocos.

sort_orderinteger

Posição do bloco na coluna.

namestring

Nome de exibição no editor.

configobject

Configurações do tipo de bloco (as chaves de settings do catálogo).

contentobject

Conteúdo livre do bloco.

visibilityobject

Visibilidade por dispositivo.

usergroup_idsstring[]

Grupos de compradores que veem o bloco. Ausente quando vazio.

statusstring

Status em letra: A (ativo) ou D (inativo).

cache_ttlinteger

Tempo de cache do bloco, em segundos.

custom_classstring

Classe CSS extra do bloco.

custom_cssstring

CSS livre do bloco.

wrapperstring

Moldura do título: vazio, h1_main, h2_important, h3_ordinary, footer, onclick_dropdown, filter_wrapper ou card.

designobject

Camada de estilo universal.

reusable_block_idinteger

Presente quando o bloco é uma instância vinculada de um bloco reutilizável.

created_atstring

Criação (RFC 3339).

updated_atstring

Última alteração (RFC 3339).

Erros

Status	Quando	Corpo de exemplo
400	O id de library no caminho não é um inteiro.	`{"error":"invalid library id","detail":"id must be an integer"}`
400	Corpo JSON inválido.	`{"error":"invalid request body","detail":"unexpected EOF"}`
400	`column_id` ausente ou zero.	`{"error":"column_id is required"}`
401	Sem token, token inválido ou expirado.	`{"error":"invalid or expired token"}`
403	Seu usuário não tem o privilégio `manage_layouts`.	`{"error":"insufficient privileges","required":"manage_layouts"}`
500	Item da biblioteca ou coluna inexistente, ou tipo que já atingiu o limite por página.	`{"error":"failed to add from library","detail":"..."}`