API atual/Referência completa/Theme Builder

Blocos da seção

Lista, adiciona, altera, remove e reordena os blocos filhos de uma seção.

Algumas seções têm filhos repetíveis: os slides de um carrossel, as colunas de uma lista de diferenciais, os itens de um menu. Cada filho é um bloco. Os tipos aceitos e o limite de cada um vêm de block_definitions na definição da seção. Atenção: não confunda com os blocos dos layouts avançados, que são outro sistema.

Listar blocos

Devolve os blocos em ordem. Seção sem blocos devolve lista vazia.

GET/api/v1/admin/theme-builder/template-sections/{id}/blocksAdmin

Listar os blocos de uma seção

Requer o privilégio manage_theme.

Parâmetros de caminho

iduuidobrigatório

Id da seção inserida.

Exemplo de requisição

bash

curl -X GET "$BASE_URL/api/v1/admin/theme-builder/template-sections/3d4dfa54-1a77-403d-b447-19d10718fe56/blocks" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Blocos

json

{
  "blocks": [
    {
      "id": "6b1f7f0e-3c55-4c2a-9a0a-5f7a1c2d9e10",
      "template_section_id": "3d4dfa54-1a77-403d-b447-19d10718fe56",
      "block_type": "column",
      "name": "Frete grátis",
      "settings_values": {
        "heading": "Frete grátis",
        "text": "Acima de R$ 199"
      },
      "sort_order": 0,
      "visible": true,
      "created_at": "2026-10-11T12:00:00Z",
      "updated_at": "2026-10-11T12:00:00Z"
    }
  ]
}

200Seção sem blocos

json

{
  "blocks": []
}

Campos da resposta

blocksarray

Blocos.

iduuid

Id do bloco.

template_section_iduuid

Seção dona.

block_typestring

Tipo do bloco, de block_definitions da definição (por exemplo column).

namestring

Nome.

settings_valuesobject

Valores dos campos do bloco.

sort_orderinteger

Posição na seção.

visibleboolean

Visível na vitrine.

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_theme`.	`{"error":"insufficient privileges","required":"manage_theme"}`
500	O id do caminho não é um UUID. Esta rota não valida antes e devolve `500` com a mensagem do banco em português.	`{"error":"failed to list blocks","detail":"o valor \"xx\" não é um uuid válido. Envie o identificador completo, com os 36 caracteres e os hífens. Corrija o campo e reenvie."}`
500	Falha de banco de dados ou dado inválido para a coluna.	`{"error":"failed to list blocks","detail":"..."}`

Adicionar bloco

Cria um bloco na seção, com a posição sort_order informada.

POST/api/v1/admin/theme-builder/template-sections/{id}/blocksAdmin

Adicionar um bloco a uma seção

Requer o privilégio manage_theme.

Parâmetros de caminho

iduuidobrigatório

Id da seção inserida.

Corpo da requisição

block_typestringobrigatório

Tipo do bloco. Obrigatório. O servidor não confere com block_definitions.

namestring

Nome.

settings_valuesobject

Valores dos campos.

sort_orderintegerpadrão: 0

Posição.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/admin/theme-builder/template-sections/3d4dfa54-1a77-403d-b447-19d10718fe56/blocks" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "block_type": "column",
    "name": "Frete grátis",
    "settings_values": {
      "heading": "Frete grátis",
      "text": "Acima de R$ 199"
    }
  }'

Resposta

201Bloco criado

json

{
  "id": "6b1f7f0e-3c55-4c2a-9a0a-5f7a1c2d9e10",
  "template_section_id": "3d4dfa54-1a77-403d-b447-19d10718fe56",
  "block_type": "column",
  "name": "Frete grátis",
  "settings_values": {
    "heading": "Frete grátis",
    "text": "Acima de R$ 199"
  },
  "sort_order": 0,
  "visible": true,
  "created_at": "2026-10-11T12:00:00Z",
  "updated_at": "2026-10-11T12:00:00Z"
}

Campos da resposta

iduuid

Id do bloco.

template_section_iduuid

Seção dona.

block_typestring

Tipo do bloco, de block_definitions da definição (por exemplo column).

namestring

Nome.

settings_valuesobject

Valores dos campos do bloco.

sort_orderinteger

Posição na seção.

visibleboolean

Visível na vitrine.

created_atstring

Criação (RFC 3339).

updated_atstring

Última alteraçã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"}`
401	Sem token, token inválido ou expirado.	`{"error":"invalid or expired token"}`
403	Seu usuário não tem o privilégio `manage_theme`.	`{"error":"insufficient privileges","required":"manage_theme"}`
500	Falha de banco de dados ou dado inválido para a coluna.	`{"error":"failed to add block","detail":"..."}`

Atualizar bloco

Substitui os settings_values do bloco por inteiro.

PUT/api/v1/admin/theme-builder/blocks/{id}Admin

Atualizar os valores de um bloco

Requer o privilégio manage_theme.

Parâmetros de caminho

iduuidobrigatório

Id do bloco.

Corpo da requisição

settings_valuesobjectobrigatório

Novos valores.

Exemplo de requisição

bash

curl -X PUT "$BASE_URL/api/v1/admin/theme-builder/blocks/6b1f7f0e-3c55-4c2a-9a0a-5f7a1c2d9e10" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "settings_values": {
      "heading": "Frete grátis",
      "text": "Acima de R$ 249"
    }
  }'

Resposta

200Bloco atualizado

json

{
  "message": "block settings updated"
}

Erros

Status	Quando	Corpo de exemplo
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_theme`.	`{"error":"insufficient privileges","required":"manage_theme"}`
404	Bloco não existe.	`{"error":"block not found","detail":"not found: ..."}`
500	Falha de banco de dados ou dado inválido para a coluna.	`{"error":"failed to update block settings","detail":"..."}`

Remover bloco

Remove o bloco da seção.

DELETE/api/v1/admin/theme-builder/blocks/{id}Admin

Remover um bloco

Requer o privilégio manage_theme.

Parâmetros de caminho

iduuidobrigatório

Id do bloco.

Exemplo de requisição

bash

curl -X DELETE "$BASE_URL/api/v1/admin/theme-builder/blocks/6b1f7f0e-3c55-4c2a-9a0a-5f7a1c2d9e10" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Removido

json

{
  "message": "block removed"
}

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_theme`.	`{"error":"insufficient privileges","required":"manage_theme"}`
404	Bloco não existe.	`{"error":"block not found","detail":"not found: ..."}`
500	Falha de banco de dados ou dado inválido para a coluna.	`{"error":"failed to remove block","detail":"..."}`

Reordenar blocos

O bloco na posição 0 do array vira o primeiro, e assim por diante. Ids que não são da seção são ignorados em silêncio.

PUT/api/v1/admin/theme-builder/template-sections/{id}/blocks/reorderAdmin

Reordenar os blocos de uma seção

Requer o privilégio manage_theme.

Parâmetros de caminho

iduuidobrigatório

Id da seção inserida.

Corpo da requisição

idsuuid[]obrigatório

Ids dos blocos na ordem desejada. Não pode ser vazio.

Exemplo de requisição

bash

curl -X PUT "$BASE_URL/api/v1/admin/theme-builder/template-sections/3d4dfa54-1a77-403d-b447-19d10718fe56/blocks/reorder" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "ids": [
      "6b1f7f0e-3c55-4c2a-9a0a-5f7a1c2d9e10"
    ]
  }'

Resposta

200Reordenados

json

{
  "message": "blocks reordered"
}

Erros

Status	Quando	Corpo de exemplo
400	Corpo JSON inválido.	`{"error":"invalid request body","detail":"unexpected EOF"}`
400	`ids` vazio.	`{"error":"ids array 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_theme`.	`{"error":"insufficient privileges","required":"manage_theme"}`
500	Falha de banco de dados ou dado inválido para a coluna.	`{"error":"failed to reorder blocks","detail":"..."}`

Veja também

API atual/Referência completa/Theme Builder

Blocos da seção

Lista, adiciona, altera, remove e reordena os blocos filhos de uma seção.

Listar blocos

Devolve os blocos em ordem. Seção sem blocos devolve lista vazia.

GET/api/v1/admin/theme-builder/template-sections/{id}/blocksAdmin

Listar os blocos de uma seção

Requer o privilégio manage_theme.

Parâmetros de caminho

iduuidobrigatório

Id da seção inserida.

Exemplo de requisição

bash

curl -X GET "$BASE_URL/api/v1/admin/theme-builder/template-sections/3d4dfa54-1a77-403d-b447-19d10718fe56/blocks" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Blocos

json

{
  "blocks": [
    {
      "id": "6b1f7f0e-3c55-4c2a-9a0a-5f7a1c2d9e10",
      "template_section_id": "3d4dfa54-1a77-403d-b447-19d10718fe56",
      "block_type": "column",
      "name": "Frete grátis",
      "settings_values": {
        "heading": "Frete grátis",
        "text": "Acima de R$ 199"
      },
      "sort_order": 0,
      "visible": true,
      "created_at": "2026-10-11T12:00:00Z",
      "updated_at": "2026-10-11T12:00:00Z"
    }
  ]
}

200Seção sem blocos

json

{
  "blocks": []
}

Campos da resposta

blocksarray

Blocos.

iduuid

Id do bloco.

template_section_iduuid

Seção dona.

block_typestring

Tipo do bloco, de block_definitions da definição (por exemplo column).

namestring

Nome.

settings_valuesobject

Valores dos campos do bloco.

sort_orderinteger

Posição na seção.

visibleboolean

Visível na vitrine.

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_theme`.	`{"error":"insufficient privileges","required":"manage_theme"}`
500	O id do caminho não é um UUID. Esta rota não valida antes e devolve `500` com a mensagem do banco em português.	`{"error":"failed to list blocks","detail":"o valor \"xx\" não é um uuid válido. Envie o identificador completo, com os 36 caracteres e os hífens. Corrija o campo e reenvie."}`
500	Falha de banco de dados ou dado inválido para a coluna.	`{"error":"failed to list blocks","detail":"..."}`

Adicionar bloco

Cria um bloco na seção, com a posição sort_order informada.

POST/api/v1/admin/theme-builder/template-sections/{id}/blocksAdmin

Adicionar um bloco a uma seção

Requer o privilégio manage_theme.

Parâmetros de caminho

iduuidobrigatório

Id da seção inserida.

Corpo da requisição

block_typestringobrigatório

Tipo do bloco. Obrigatório. O servidor não confere com block_definitions.

namestring

Nome.

settings_valuesobject

Valores dos campos.

sort_orderintegerpadrão: 0

Posição.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/admin/theme-builder/template-sections/3d4dfa54-1a77-403d-b447-19d10718fe56/blocks" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "block_type": "column",
    "name": "Frete grátis",
    "settings_values": {
      "heading": "Frete grátis",
      "text": "Acima de R$ 199"
    }
  }'

Resposta

201Bloco criado

json

{
  "id": "6b1f7f0e-3c55-4c2a-9a0a-5f7a1c2d9e10",
  "template_section_id": "3d4dfa54-1a77-403d-b447-19d10718fe56",
  "block_type": "column",
  "name": "Frete grátis",
  "settings_values": {
    "heading": "Frete grátis",
    "text": "Acima de R$ 199"
  },
  "sort_order": 0,
  "visible": true,
  "created_at": "2026-10-11T12:00:00Z",
  "updated_at": "2026-10-11T12:00:00Z"
}

Campos da resposta

iduuid

Id do bloco.

template_section_iduuid

Seção dona.

block_typestring

Tipo do bloco, de block_definitions da definição (por exemplo column).

namestring

Nome.

settings_valuesobject

Valores dos campos do bloco.

sort_orderinteger

Posição na seção.

visibleboolean

Visível na vitrine.

created_atstring

Criação (RFC 3339).

updated_atstring

Última alteraçã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"}`
401	Sem token, token inválido ou expirado.	`{"error":"invalid or expired token"}`
403	Seu usuário não tem o privilégio `manage_theme`.	`{"error":"insufficient privileges","required":"manage_theme"}`
500	Falha de banco de dados ou dado inválido para a coluna.	`{"error":"failed to add block","detail":"..."}`

Atualizar bloco

Substitui os settings_values do bloco por inteiro.

PUT/api/v1/admin/theme-builder/blocks/{id}Admin

Atualizar os valores de um bloco

Requer o privilégio manage_theme.

Parâmetros de caminho

iduuidobrigatório

Id do bloco.

Corpo da requisição

settings_valuesobjectobrigatório

Novos valores.

Exemplo de requisição

bash

curl -X PUT "$BASE_URL/api/v1/admin/theme-builder/blocks/6b1f7f0e-3c55-4c2a-9a0a-5f7a1c2d9e10" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "settings_values": {
      "heading": "Frete grátis",
      "text": "Acima de R$ 249"
    }
  }'

Resposta

200Bloco atualizado

json

{
  "message": "block settings updated"
}

Erros

Status	Quando	Corpo de exemplo
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_theme`.	`{"error":"insufficient privileges","required":"manage_theme"}`
404	Bloco não existe.	`{"error":"block not found","detail":"not found: ..."}`
500	Falha de banco de dados ou dado inválido para a coluna.	`{"error":"failed to update block settings","detail":"..."}`

Remover bloco

Remove o bloco da seção.

DELETE/api/v1/admin/theme-builder/blocks/{id}Admin

Remover um bloco

Requer o privilégio manage_theme.

Parâmetros de caminho

iduuidobrigatório

Id do bloco.

Exemplo de requisição

bash

curl -X DELETE "$BASE_URL/api/v1/admin/theme-builder/blocks/6b1f7f0e-3c55-4c2a-9a0a-5f7a1c2d9e10" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Removido

json

{
  "message": "block removed"
}

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_theme`.	`{"error":"insufficient privileges","required":"manage_theme"}`
404	Bloco não existe.	`{"error":"block not found","detail":"not found: ..."}`
500	Falha de banco de dados ou dado inválido para a coluna.	`{"error":"failed to remove block","detail":"..."}`

Reordenar blocos

O bloco na posição 0 do array vira o primeiro, e assim por diante. Ids que não são da seção são ignorados em silêncio.

PUT/api/v1/admin/theme-builder/template-sections/{id}/blocks/reorderAdmin

Reordenar os blocos de uma seção

Requer o privilégio manage_theme.

Parâmetros de caminho

iduuidobrigatório

Id da seção inserida.

Corpo da requisição

idsuuid[]obrigatório

Ids dos blocos na ordem desejada. Não pode ser vazio.

Exemplo de requisição

bash

curl -X PUT "$BASE_URL/api/v1/admin/theme-builder/template-sections/3d4dfa54-1a77-403d-b447-19d10718fe56/blocks/reorder" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "ids": [
      "6b1f7f0e-3c55-4c2a-9a0a-5f7a1c2d9e10"
    ]
  }'

Resposta

200Reordenados

json

{
  "message": "blocks reordered"
}

Erros

Status	Quando	Corpo de exemplo
400	Corpo JSON inválido.	`{"error":"invalid request body","detail":"unexpected EOF"}`
400	`ids` vazio.	`{"error":"ids array 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_theme`.	`{"error":"insufficient privileges","required":"manage_theme"}`
500	Falha de banco de dados ou dado inválido para a coluna.	`{"error":"failed to reorder blocks","detail":"..."}`