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

Blocos reutilizáveis

Transforma um bloco em reutilizável, insere instâncias vinculadas e propaga mudanças a todas elas.

Um bloco reutilizável é um bloco cuja configuração mora na biblioteca e é compartilhada por todos os lugares onde foi inserido. Ao editar o reutilizável, todas as instâncias passam a usar a nova configuração. É o recurso certo para uma faixa de aviso, um selo de segurança ou um rodapé que aparece em várias páginas. Diferente do item comum da biblioteca, que é cópia.

Listar reutilizáveis

Devolve os itens da biblioteca com a contagem de instâncias vinculadas.

GET/api/v1/admin/advanced-layouts/reusable-blocksAdmin

Listar blocos reutilizáveis

Requer o privilégio manage_layouts.

Exemplo de requisição

bash

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

Resposta

200Reutilizáveis

json

{
  "reusable_blocks": [
    {
      "id": 10,
      "name": "Faixa de frete grátis",
      "block_type": "categories_grid",
      "config": {
        "columns": 4,
        "count": 8
      },
      "content": {},
      "placement_count": 1,
      "created_at": "2026-07-13T13:51:26.232664Z",
      "updated_at": "2026-07-13T13:51:26.232664Z"
    }
  ]
}

Campos da resposta

reusable_blocksarray

Blocos reutilizáveis (lista vazia quando não há).

idinteger

Id do bloco reutilizável.

namestring

Nome.

block_typestring

Tipo do bloco.

configobject

Opções compartilhadas.

contentobject

Conteúdo.

designobject

Estilo, quando houver.

placement_countinteger

Em quantos lugares o bloco está vinculado. Use para avisar o editor antes de uma mudança em massa.

created_atstring

Criação (RFC 3339).

updated_atstring

Última alteraçã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 reusable blocks","detail":"..."}`

Salvar como reutilizável

Cria o reutilizável a partir da configuração do bloco e vincula o próprio bloco a ele. A partir daí, o bloco passa a refletir mudanças feitas no reutilizável.

POST/api/v1/admin/advanced-layouts/blocks/{id}/save-as-reusableAdmin

Transformar um bloco em reutilizável

Requer o privilégio manage_layouts.

Parâmetros de caminho

idintegerobrigatório

Id numérico do bloco de origem.

Corpo da requisição

namestringobrigatório

Nome do reutilizável.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/admin/advanced-layouts/blocks/11081/save-as-reusable" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Faixa de frete grátis"
  }'

Resposta

201Reutilizável criado

json

{
  "id": 10,
  "name": "Faixa de frete grátis",
  "block_type": "categories_grid",
  "config": {
    "columns": 4,
    "count": 8
  },
  "content": {},
  "placement_count": 1,
  "created_at": "2026-07-13T13:51:26.232664Z",
  "updated_at": "2026-07-13T13:51:26.232664Z"
}

Campos da resposta

idinteger

Id do bloco reutilizável.

namestring

Nome.

block_typestring

Tipo do bloco.

configobject

Opções compartilhadas.

contentobject

Conteúdo.

designobject

Estilo, quando houver.

placement_countinteger

Em quantos lugares o bloco está vinculado. Use para avisar o editor antes de uma mudança em massa.

created_atstring

Criação (RFC 3339).

updated_atstring

Última alteração (RFC 3339).

Erros

Status	Quando	Corpo de exemplo
400	O id de block no caminho não é um inteiro.	`{"error":"invalid block id","detail":"id must be an integer"}`
400	Corpo JSON inválido.	`{"error":"invalid request body","detail":"unexpected EOF"}`
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 block as reusable","detail":"..."}`

Atualizar reutilizável

Troca a configuração do reutilizável e a propaga para todas as instâncias vinculadas. Só config é alterado por esta rota.

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

Alterar um bloco reutilizável

Requer o privilégio manage_layouts.

Parâmetros de caminho

idintegerobrigatório

Id numérico do bloco reutilizável.

Corpo da requisição

configobject

Nova configuração (substitui a anterior).

Exemplo de requisição

bash

curl -X PUT "$BASE_URL/api/v1/admin/advanced-layouts/reusable-blocks/10" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "config": {
      "columns": 3,
      "count": 6
    }
  }'

Resposta

200Reutilizável atualizado

json

{
  "id": 10,
  "name": "Faixa de frete grátis",
  "block_type": "categories_grid",
  "config": {
    "columns": 3,
    "count": 6
  },
  "content": {},
  "placement_count": 1,
  "created_at": "2026-07-13T13:51:26.232664Z",
  "updated_at": "2026-07-13T13:51:26.232664Z"
}

Campos da resposta

idinteger

Id do bloco reutilizável.

namestring

Nome.

block_typestring

Tipo do bloco.

configobject

Opções compartilhadas.

contentobject

Conteúdo.

designobject

Estilo, quando houver.

placement_countinteger

Em quantos lugares o bloco está vinculado. Use para avisar o editor antes de uma mudança em massa.

created_atstring

Criação (RFC 3339).

updated_atstring

Última alteração (RFC 3339).

Erros

Status	Quando	Corpo de exemplo
400	O id de reusable block no caminho não é um inteiro.	`{"error":"invalid reusable block id","detail":"id must be an integer"}`
400	Corpo JSON inválido.	`{"error":"invalid request body","detail":"unexpected EOF"}`
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 update reusable block","detail":"..."}`

Inserir instância vinculada

Cria na coluna um bloco novo vinculado ao reutilizável. O bloco devolvido traz reusable_block_id.

POST/api/v1/admin/advanced-layouts/columns/{id}/blocks/from-reusableAdmin

Inserir uma instância vinculada numa coluna

Requer o privilégio manage_layouts.

Parâmetros de caminho

idintegerobrigatório

Id numérico da coluna de destino.

Corpo da requisição

reusable_block_idintegerobrigatório

Id do reutilizável.

sort_orderintegerpadrão: 0

Posição na coluna.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/admin/advanced-layouts/columns/8790/blocks/from-reusable" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "reusable_block_id": 10,
    "sort_order": 0
  }'

Resposta

201Instância criada

json

{
  "id": 11140,
  "column_id": 8790,
  "block_type": "categories_grid",
  "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",
  "reusable_block_id": 10
}

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 column no caminho não é um inteiro.	`{"error":"invalid column id","detail":"id must be an integer"}`
400	Corpo JSON inválido.	`{"error":"invalid request body","detail":"unexpected EOF"}`
400	`reusable_block_id` ausente ou zero.	`{"error":"reusable_block_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	Falha ao gravar ou ler no banco, ou id inexistente onde a rota não trata 404.	`{"error":"failed to add block from reusable","detail":"..."}`

Veja também

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

Blocos reutilizáveis

Transforma um bloco em reutilizável, insere instâncias vinculadas e propaga mudanças a todas elas.

Listar reutilizáveis

Devolve os itens da biblioteca com a contagem de instâncias vinculadas.

GET/api/v1/admin/advanced-layouts/reusable-blocksAdmin

Listar blocos reutilizáveis

Requer o privilégio manage_layouts.

Exemplo de requisição

bash

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

Resposta

200Reutilizáveis

json

{
  "reusable_blocks": [
    {
      "id": 10,
      "name": "Faixa de frete grátis",
      "block_type": "categories_grid",
      "config": {
        "columns": 4,
        "count": 8
      },
      "content": {},
      "placement_count": 1,
      "created_at": "2026-07-13T13:51:26.232664Z",
      "updated_at": "2026-07-13T13:51:26.232664Z"
    }
  ]
}

Campos da resposta

reusable_blocksarray

Blocos reutilizáveis (lista vazia quando não há).

idinteger

Id do bloco reutilizável.

namestring

Nome.

block_typestring

Tipo do bloco.

configobject

Opções compartilhadas.

contentobject

Conteúdo.

designobject

Estilo, quando houver.

placement_countinteger

Em quantos lugares o bloco está vinculado. Use para avisar o editor antes de uma mudança em massa.

created_atstring

Criação (RFC 3339).

updated_atstring

Última alteraçã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 reusable blocks","detail":"..."}`

Salvar como reutilizável

Cria o reutilizável a partir da configuração do bloco e vincula o próprio bloco a ele. A partir daí, o bloco passa a refletir mudanças feitas no reutilizável.

POST/api/v1/admin/advanced-layouts/blocks/{id}/save-as-reusableAdmin

Transformar um bloco em reutilizável

Requer o privilégio manage_layouts.

Parâmetros de caminho

idintegerobrigatório

Id numérico do bloco de origem.

Corpo da requisição

namestringobrigatório

Nome do reutilizável.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/admin/advanced-layouts/blocks/11081/save-as-reusable" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Faixa de frete grátis"
  }'

Resposta

201Reutilizável criado

json

{
  "id": 10,
  "name": "Faixa de frete grátis",
  "block_type": "categories_grid",
  "config": {
    "columns": 4,
    "count": 8
  },
  "content": {},
  "placement_count": 1,
  "created_at": "2026-07-13T13:51:26.232664Z",
  "updated_at": "2026-07-13T13:51:26.232664Z"
}

Campos da resposta

idinteger

Id do bloco reutilizável.

namestring

Nome.

block_typestring

Tipo do bloco.

configobject

Opções compartilhadas.

contentobject

Conteúdo.

designobject

Estilo, quando houver.

placement_countinteger

Em quantos lugares o bloco está vinculado. Use para avisar o editor antes de uma mudança em massa.

created_atstring

Criação (RFC 3339).

updated_atstring

Última alteração (RFC 3339).

Erros

Status	Quando	Corpo de exemplo
400	O id de block no caminho não é um inteiro.	`{"error":"invalid block id","detail":"id must be an integer"}`
400	Corpo JSON inválido.	`{"error":"invalid request body","detail":"unexpected EOF"}`
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 block as reusable","detail":"..."}`

Atualizar reutilizável

Troca a configuração do reutilizável e a propaga para todas as instâncias vinculadas. Só config é alterado por esta rota.

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

Alterar um bloco reutilizável

Requer o privilégio manage_layouts.

Parâmetros de caminho

idintegerobrigatório

Id numérico do bloco reutilizável.

Corpo da requisição

configobject

Nova configuração (substitui a anterior).

Exemplo de requisição

bash

curl -X PUT "$BASE_URL/api/v1/admin/advanced-layouts/reusable-blocks/10" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "config": {
      "columns": 3,
      "count": 6
    }
  }'

Resposta

200Reutilizável atualizado

json

{
  "id": 10,
  "name": "Faixa de frete grátis",
  "block_type": "categories_grid",
  "config": {
    "columns": 3,
    "count": 6
  },
  "content": {},
  "placement_count": 1,
  "created_at": "2026-07-13T13:51:26.232664Z",
  "updated_at": "2026-07-13T13:51:26.232664Z"
}

Campos da resposta

idinteger

Id do bloco reutilizável.

namestring

Nome.

block_typestring

Tipo do bloco.

configobject

Opções compartilhadas.

contentobject

Conteúdo.

designobject

Estilo, quando houver.

placement_countinteger

Em quantos lugares o bloco está vinculado. Use para avisar o editor antes de uma mudança em massa.

created_atstring

Criação (RFC 3339).

updated_atstring

Última alteração (RFC 3339).

Erros

Status	Quando	Corpo de exemplo
400	O id de reusable block no caminho não é um inteiro.	`{"error":"invalid reusable block id","detail":"id must be an integer"}`
400	Corpo JSON inválido.	`{"error":"invalid request body","detail":"unexpected EOF"}`
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 update reusable block","detail":"..."}`

Inserir instância vinculada

Cria na coluna um bloco novo vinculado ao reutilizável. O bloco devolvido traz reusable_block_id.

POST/api/v1/admin/advanced-layouts/columns/{id}/blocks/from-reusableAdmin

Inserir uma instância vinculada numa coluna

Requer o privilégio manage_layouts.

Parâmetros de caminho

idintegerobrigatório

Id numérico da coluna de destino.

Corpo da requisição

reusable_block_idintegerobrigatório

Id do reutilizável.

sort_orderintegerpadrão: 0

Posição na coluna.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/admin/advanced-layouts/columns/8790/blocks/from-reusable" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "reusable_block_id": 10,
    "sort_order": 0
  }'

Resposta

201Instância criada

json

{
  "id": 11140,
  "column_id": 8790,
  "block_type": "categories_grid",
  "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",
  "reusable_block_id": 10
}

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 column no caminho não é um inteiro.	`{"error":"invalid column id","detail":"id must be an integer"}`
400	Corpo JSON inválido.	`{"error":"invalid request body","detail":"unexpected EOF"}`
400	`reusable_block_id` ausente ou zero.	`{"error":"reusable_block_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	Falha ao gravar ou ler no banco, ou id inexistente onde a rota não trata 404.	`{"error":"failed to add block from reusable","detail":"..."}`