Blocos do layout
Adiciona, altera, remove e reordena os blocos de um layout simples.
Um bloco é uma peça do layout (logo, busca, texto, produtos recentes...). Estas rotas mexem num bloco por vez, sem reenviar a lista inteira. Cada uma devolve o layout completo já atualizado. Exigem o privilégio manage_layouts. O {id} é o do layout simples (inteiro) e o {blockId} é o UUID do bloco, devolvido em blocks[].id.
Adicionar bloco
/api/v1/admin/layouts/{id}/blocksAdminAdiciona um bloco ao layout
O servidor gera o id do bloco. O bloco é anexado ao fim da lista e sua order é a que você enviar (a renumeração só ocorre ao remover ou reordenar).
Parâmetros de caminho
idintegerobrigatórioCorpo da requisição
typestringobrigatóriotext_html, hero_banner, featured_products, categories_grid, vendor_showcase, newsletter, recent_products, promotions, custom_html. Qualquer texto é aceito.positionstringobrigatórioheader, main_top, main, main_bottom, sidebar_left, sidebar_right ou footer. Qualquer texto é aceito.orderintegerpadrão: 0titlestringconfigobjectpadrão: {}type.visiblebooleanpadrão: trueExemplo de requisição
curl -X POST "$BASE_URL/api/v1/admin/layouts/14/blocks" \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{"type":"text_html","position":"footer","order":1,"title":"Sobre nós","config":{"html_content":"<p>Desde 2015</p>"}}'{
"id": 14,
"name": "Home de Natal",
"page_type": "homepage",
"is_default": false,
"blocks": [
{
"id": "d5a8c1d2-0f3e-4b44-9a11-7e5b3c2a9f10",
"type": "text_html",
"position": "footer",
"order": 1,
"title": "Sobre nós",
"config": { "html_content": "<p>Desde 2015</p>" },
"visible": true
}
],
"created_at": "2026-10-11T15:00:00.000Z",
"updated_at": "2026-10-11T15:05:00.000Z"
}Alterar bloco
/api/v1/admin/layouts/{id}/blocks/{blockId}AdminAltera um bloco do layout
Alteração parcial dos campos do bloco. O config, quando enviado, substitui o objeto inteiro: mande todas as opções, não só a que mudou.
Parâmetros de caminho
idintegerobrigatórioblockIdstringobrigatórioCorpo da requisição
typestringpositionstringorderintegertitlestringconfigobjectvisiblebooleanA resposta 200 é o layout completo atualizado.
Remover bloco
/api/v1/admin/layouts/{id}/blocks/{blockId}AdminRemove um bloco do layout
Remove o bloco e renumera a order dos blocos restantes de cada zona em sequência (0, 1, 2...).
Parâmetros de caminho
idintegerobrigatórioblockIdstringobrigatórioA resposta 200 é o layout completo atualizado.
Reordenar blocos
/api/v1/admin/layouts/{id}/blocks/reorderAdminMuda zona e ordem de vários blocos de uma vez
Para cada item da lista, atualiza a position e a order do bloco. Blocos que você não listar ficam como estão. Em seguida a ordem de cada zona é renumerada em sequência (0, 1, 2...). Ids de bloco desconhecidos são ignorados em silêncio.
Parâmetros de caminho
idintegerobrigatórioCorpo da requisição
block_ordersarrayobrigatórioLista não vazia. Cada item:
block_idstringobrigatóriopositionstringobrigatórioorderintegerobrigatórioA resposta 200 é o layout completo atualizado.
Erros
| Status | Quando | Corpo |
|---|---|---|
| 400 | id que não é inteiro; corpo inválido; type ou position ausente (adicionar); block_orders vazio (reordenar) | {"error":"block type is required"}, {"error":"block position is required"} ou {"error":"block_orders 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 | O id não é de um layout simples. A mensagem em português explica que o id é de layout avançado e indica a rota equivalente | {"error":"layout not found","detail":"o id 999999 não é de layout antigo ..."} |
| 500 | blockId que não existe no layout (alterar, remover); blocos acima de 1 MB | {"error":"failed to update block","detail":"block not found"} |