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

Blocos

Cria, altera, move e exclui os blocos de conteúdo dentro das colunas.

O bloco é a peça de conteúdo: um banner, uma grade de produtos, um menu, o botão de comprar. Cada bloco tem um block_type (veja o catálogo), uma config com as opções desse tipo, um content livre e uma camada design de estilo.

Blocos de patches ficam protegidos

Se o bloco foi criado ou ajustado por um patch aplicado na loja (IO, Patches), alterar, mover ou excluir devolve 409 com code: patch_owned. Reverta o patch dono, ou aplique sua mudança como um novo patch.

Criar bloco

Adiciona um bloco à coluna. Só block_type é obrigatório; name assume o próprio tipo, e config, content e visibility assumem valores vazios/visível em tudo.

POST/api/v1/admin/advanced-layouts/columns/{id}/blocksAdmin

Criar um bloco na coluna

Requer o privilégio manage_layouts.

Parâmetros de caminho

idintegerobrigatório
Id numérico da coluna.

Corpo da requisição

block_typestringobrigatório
Tipo do bloco (veja o catálogo).
sort_orderintegerpadrão: 0
Posição na coluna.
namestringpadrão: o próprio block_type
Nome de exibição.
configobjectpadrão: {}
Opções do tipo. Chaves vêm de settings no catálogo.
contentobjectpadrão: {}
Conteúdo livre.
visibilityobject
Visibilidade por dispositivo. Chaves desktop, tablet e mobile, valores booleanos. Se omitido na criação, vale true nos três.
usergroup_idsstring[]
Restringe a visibilidade a grupos de compradores. Vazio (padrão) mostra a todos. Aceita os atalhos guest (visitante anônimo) e registered (logado), além de UUIDs de grupos.
statusstringpadrão: active
A ou active (ativo), D ou inactive (inativo).
custom_classstring
Classe CSS extra.
custom_cssstring
CSS livre do bloco.
wrapperstring
h1_mainh2_importanth3_ordinaryfooteronclick_dropdownfilter_wrappercard
Moldura do título.
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.

Exemplo de requisição

bash
curl -X POST "$BASE_URL/api/v1/admin/advanced-layouts/columns/8786/blocks" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "block_type": "heading",
    "name": "Título da seção",
    "config": {
      "text": "Ofertas da semana",
      "tag": "h2"
    }
  }'

Resposta

201Bloco criado
json
{
  "id": 11120,
  "column_id": 8786,
  "block_type": "heading",
  "sort_order": 0,
  "name": "Título da seção",
  "config": {
    "text": "Ofertas da semana",
    "tag": "h2"
  },
  "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

StatusQuandoCorpo de exemplo
400O id de column no caminho não é um inteiro.{"error":"invalid column id","detail":"id must be an integer"}
400Corpo JSON inválido.{"error":"invalid request body","detail":"unexpected EOF"}
400block_type vazio.{"error":"block_type 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"}
500Tipo que só pode existir uma vez por página (como main_content) já presente, conteúdo acima de 1 MB, ou status com palavra não reconhecida (o campo é de 1 letra).{"error":"failed to create block","detail":"block type \"main_content\" already has the maximum of 1 on this page"}
`block_type` não é validado

O servidor aceita qualquer texto como tipo. Um tipo que não existe no catálogo é gravado, mas a vitrine não sabe desenhá-lo.

Atualizar bloco

Altera os campos enviados. config, content e design, quando enviados, substituem o objeto inteiro (não há mesclagem): leia o bloco, altere o que precisa e devolva o objeto completo.

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

Atualizar um bloco

Requer o privilégio manage_layouts.

Parâmetros de caminho

idintegerobrigatório
Id numérico do bloco.

Corpo da requisição

block_typestring
Troca o tipo do bloco.
sort_orderinteger
Posição na coluna.
namestring
Nome.
configobject
Novas opções (substitui tudo).
contentobject
Novo conteúdo (substitui tudo).
visibilityobject
Visibilidade por dispositivo. Chaves desktop, tablet e mobile, valores booleanos. Se omitido, o valor atual é mantido. Se enviado, substitui o objeto inteiro.
usergroup_idsstring[]
Restringe a visibilidade a grupos de compradores. Vazio (padrão) mostra a todos. Aceita os atalhos guest (visitante anônimo) e registered (logado), além de UUIDs de grupos.
statusstring
A/active ou D/inactive.
custom_classstring
Classe CSS extra.
custom_cssstring
CSS livre do bloco.
wrapperstring
Moldura do título.
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. Substitui o objeto inteiro quando enviado; envie {} para limpar.

Exemplo de requisição

bash
curl -X PUT "$BASE_URL/api/v1/admin/advanced-layouts/blocks/11081" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "config": {
      "autoplay": false,
      "interval": 5000,
      "show_arrows": true
    },
    "status": "inactive"
  }'

Resposta

200Bloco atualizado
json
{
  "id": 11081,
  "column_id": 8786,
  "block_type": "banner_slider",
  "sort_order": 0,
  "name": "Main Banner",
  "config": {
    "autoplay": false,
    "interval": 5000,
    "show_arrows": true
  },
  "content": {},
  "visibility": {
    "desktop": true,
    "tablet": true,
    "mobile": true
  },
  "status": "D",
  "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

StatusQuandoCorpo de exemplo
400O id de block no caminho não é um inteiro.{"error":"invalid block 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"}
409O bloco pertence a um patch aplicado na loja (Patches). A edição é recusada para o patch continuar reversível.{"error":"...","code":"patch_owned","how_to_proceed":"revert the owning patch, or apply your change as a new patch (IO → Patches) so it stays attributable and revertible"}
500Falha ao gravar ou ler no banco, ou id inexistente onde a rota não trata 404.{"error":"failed to update block","detail":"..."}

Excluir bloco

Remove o bloco da coluna. Se ele era uma instância vinculada de um bloco reutilizável, só a instância some; o reutilizável continua na biblioteca.

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

Excluir um bloco

Requer o privilégio manage_layouts.

Parâmetros de caminho

idintegerobrigatório
Id numérico do bloco.

Exemplo de requisição

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

Resposta

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

Erros

StatusQuandoCorpo de exemplo
400O id de block no caminho não é um inteiro.{"error":"invalid block 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"}
404Bloco não existe.{"error":"block not found","detail":"11120"}
409O bloco pertence a um patch aplicado na loja (Patches). A edição é recusada para o patch continuar reversível.{"error":"...","code":"patch_owned","how_to_proceed":"revert the owning patch, or apply your change as a new patch (IO → Patches) so it stays attributable and revertible"}
500Falha ao gravar ou ler no banco, ou id inexistente onde a rota não trata 404.{"error":"failed to delete block","detail":"..."}

Mover bloco

Troca a coluna do bloco e define a posição dele nela. A coluna de destino pode estar em qualquer linha.

POST/api/v1/admin/advanced-layouts/blocks/{id}/moveAdmin

Mover um bloco para outra coluna

Requer o privilégio manage_layouts.

Parâmetros de caminho

idintegerobrigatório
Id numérico do bloco.

Corpo da requisição

target_column_idintegerobrigatório
Coluna de destino.
sort_orderintegerpadrão: 0
Posição no destino.

Exemplo de requisição

bash
curl -X POST "$BASE_URL/api/v1/admin/advanced-layouts/blocks/11081/move" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "target_column_id": 8790,
    "sort_order": 0
  }'

Resposta

200Bloco movido
json
{
  "id": 11081,
  "column_id": 8790,
  "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"
}

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

StatusQuandoCorpo de exemplo
400O id de block no caminho não é um inteiro.{"error":"invalid block id","detail":"id must be an integer"}
400Corpo JSON inválido.{"error":"invalid request body","detail":"unexpected EOF"}
400target_column_id ausente ou zero.{"error":"target_column_id 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"}
409O bloco pertence a um patch aplicado na loja (Patches). A edição é recusada para o patch continuar reversível.{"error":"...","code":"patch_owned","how_to_proceed":"revert the owning patch, or apply your change as a new patch (IO → Patches) so it stays attributable and revertible"}
500Falha ao gravar ou ler no banco, ou id inexistente onde a rota não trata 404.{"error":"failed to move block","detail":"..."}
Outros blocos não são renumerados

A rota só grava a coluna e a posição do bloco movido. Se precisar de uma ordem exata, atualize o sort_order dos vizinhos com PUT /blocks/{id}.

Veja também

  • Layouts avançados: visão geral
  • Biblioteca de blocos
Anterior
Colunas da linha
Próxima
Catálogo de blocos
Nesta página
  • Criar bloco
  • Exemplo de requisição
  • Resposta
  • Erros
  • Atualizar bloco
  • Exemplo de requisição
  • Resposta
  • Erros
  • Excluir bloco
  • Exemplo de requisição
  • Resposta
  • Erros
  • Mover bloco
  • Exemplo de requisição
  • Resposta
  • Erros
  • Veja também