API atual/Referência completa/Theme Builder

Seções do modelo

Lista, insere, altera os valores e remove seções de um modelo de página ou de um grupo.

Uma seção é uma instância de uma definição colocada num modelo ou num grupo, com seus valores (settings_values). Todas as seções de uma tela, de cima para baixo, formam a página. A seção pertence a exatamente um: um template_id ou um section_group_id.

Listar seções

Devolve as seções em ordem, já com o esquema da definição de cada uma. Informe template_id ou group_id.

GET/api/v1/admin/theme-builder/template-sectionsAdmin

Listar as seções de um modelo ou grupo

Requer o privilégio manage_theme.

Parâmetros de consulta

template_iduuid

Lista as seções deste modelo.

group_iduuid

Lista as seções deste grupo.

Exemplo de requisição

bash

curl -X GET "$BASE_URL/api/v1/admin/theme-builder/template-sections?template_id=30a0a88f-2eba-4a7a-bdea-ab73b761ab99" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Seções

json

{
  "sections": [
    {
      "id": "3d4dfa54-1a77-403d-b447-19d10718fe56",
      "template_id": "30a0a88f-2eba-4a7a-bdea-ab73b761ab99",
      "section_definition_id": "d25ab1c1-03ad-426a-94bb-e0d313a9ecdd",
      "name": "hero-banner",
      "settings_values": {
        "layout": "carousel",
        "autoplay": true,
        "min_height": "600px"
      },
      "sort_order": 0,
      "visible": true,
      "custom_css": "",
      "created_at": "2026-05-14T13:55:40.071821Z",
      "updated_at": "2026-05-14T13:55:40.071821Z",
      "definition_slug": "hero-banner",
      "definition_name": "Hero Banner"
    }
  ]
}

Campos da resposta

sectionsarray

Seções.

iduuid

Id da seção inserida.

template_iduuid

Modelo dono. Ausente se a seção é de um grupo.

section_group_iduuid

Grupo dono. Ausente se a seção é de um modelo.

section_definition_iduuid

Definição usada.

namestring

Nome da instância.

settings_valuesobject

Valores dos campos, por key.

sort_orderinteger

Posição (a partir de 0).

visibleboolean

false esconde a seção da vitrine sem excluir.

custom_cssstring

CSS livre.

definition_slugstring

Só em listagens: slug da definição.

definition_namestring

Só em listagens: nome da definição.

settings_schemaobject[]

Só em listagens: esquema de campos da definição.

block_definitionsobject[]

Só em listagens: blocos aceitos.

created_atstring

Criação (RFC 3339).

updated_atstring

Última alteração (RFC 3339).

Erros

Status	Quando	Corpo de exemplo
400	Nenhum dos dois parâmetros informado.	`{"error":"template_id or group_id query param 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 list template sections","detail":"..."}`

Inserir seção

Cria a instância de uma definição num modelo ou grupo. A seção nasce visível.

POST/api/v1/admin/theme-builder/template-sectionsAdmin

Inserir uma seção

Requer o privilégio manage_theme.

Corpo da requisição

template_iduuid

Modelo de destino. Informe este ou section_group_id.

section_group_iduuid

Grupo de destino.

section_definition_iduuidobrigatório

Definição a instanciar.

namestring

Nome da instância.

settings_valuesobjectpadrão: {}

Valores iniciais.

sort_orderintegerpadrão: 0

Posição. Ajuste depois com reordenar.

custom_cssstring

CSS livre.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/admin/theme-builder/template-sections" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "template_id": "30a0a88f-2eba-4a7a-bdea-ab73b761ab99",
    "section_definition_id": "49ee1ac9-b950-4526-8ffd-571caae96a45",
    "name": "Novidades",
    "settings_values": {
      "heading": "Novidades da semana"
    },
    "sort_order": 3
  }'

Resposta

201Seção criada

json

{
  "id": "f5f5f5f5-0000-4000-8000-000000000005",
  "template_id": "30a0a88f-2eba-4a7a-bdea-ab73b761ab99",
  "section_definition_id": "49ee1ac9-b950-4526-8ffd-571caae96a45",
  "name": "Novidades",
  "settings_values": {
    "heading": "Novidades da semana"
  },
  "sort_order": 3,
  "visible": true,
  "custom_css": "",
  "created_at": "2026-05-14T13:55:40.071821Z",
  "updated_at": "2026-05-14T13:55:40.071821Z",
  "definition_slug": "hero-banner",
  "definition_name": "Hero Banner"
}

Campos da resposta

iduuid

Id da seção inserida.

template_iduuid

Modelo dono. Ausente se a seção é de um grupo.

section_group_iduuid

Grupo dono. Ausente se a seção é de um modelo.

section_definition_iduuid

Definição usada.

namestring

Nome da instância.

settings_valuesobject

Valores dos campos, por key.

sort_orderinteger

Posição (a partir de 0).

visibleboolean

false esconde a seção da vitrine sem excluir.

custom_cssstring

CSS livre.

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	`section_definition_id` vazio.	`{"error":"section_definition_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_theme`.	`{"error":"insufficient privileges","required":"manage_theme"}`
500	Nem `template_id` nem `section_group_id`, ou ids inexistentes.	`{"error":"failed to add section","detail":"template_id or section_group_id is required"}`

Atualizar valores

Substitui os settings_values da seção. É a única coisa que esta rota altera: nome, CSS e visibilidade têm outras formas (veja visibilidade e salvar todas as seções). O objeto é substituído por inteiro.

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

Atualizar os valores 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

settings_valuesobjectobrigatório

Novos valores, por key do esquema da definição.

Exemplo de requisição

bash

curl -X PUT "$BASE_URL/api/v1/admin/theme-builder/template-sections/3d4dfa54-1a77-403d-b447-19d10718fe56" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "settings_values": {
      "layout": "carousel",
      "autoplay": false,
      "min_height": "500px"
    }
  }'

Resposta

200Seção atualizada

json

{
  "message": "section 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	Seção não existe.	`{"error":"template section not found","detail":"not found: ..."}`
500	Falha de banco de dados ou dado inválido para a coluna.	`{"error":"failed to update section settings","detail":"..."}`

Remover seção

Remove a seção e os blocos dela.

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

Remover 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 DELETE "$BASE_URL/api/v1/admin/theme-builder/template-sections/3d4dfa54-1a77-403d-b447-19d10718fe56" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Removida

json

{
  "message": "section 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	Seção não existe.	`{"error":"template section not found","detail":"not found: ..."}`
500	Falha de banco de dados ou dado inválido para a coluna.	`{"error":"failed to remove section","detail":"..."}`

Veja também

API atual/Referência completa/Theme Builder

Seções do modelo

Lista, insere, altera os valores e remove seções de um modelo de página ou de um grupo.

Listar seções

Devolve as seções em ordem, já com o esquema da definição de cada uma. Informe template_id ou group_id.

GET/api/v1/admin/theme-builder/template-sectionsAdmin

Listar as seções de um modelo ou grupo

Requer o privilégio manage_theme.

Parâmetros de consulta

template_iduuid

Lista as seções deste modelo.

group_iduuid

Lista as seções deste grupo.

Exemplo de requisição

bash

curl -X GET "$BASE_URL/api/v1/admin/theme-builder/template-sections?template_id=30a0a88f-2eba-4a7a-bdea-ab73b761ab99" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Seções

json

{
  "sections": [
    {
      "id": "3d4dfa54-1a77-403d-b447-19d10718fe56",
      "template_id": "30a0a88f-2eba-4a7a-bdea-ab73b761ab99",
      "section_definition_id": "d25ab1c1-03ad-426a-94bb-e0d313a9ecdd",
      "name": "hero-banner",
      "settings_values": {
        "layout": "carousel",
        "autoplay": true,
        "min_height": "600px"
      },
      "sort_order": 0,
      "visible": true,
      "custom_css": "",
      "created_at": "2026-05-14T13:55:40.071821Z",
      "updated_at": "2026-05-14T13:55:40.071821Z",
      "definition_slug": "hero-banner",
      "definition_name": "Hero Banner"
    }
  ]
}

Campos da resposta

sectionsarray

Seções.

iduuid

Id da seção inserida.

template_iduuid

Modelo dono. Ausente se a seção é de um grupo.

section_group_iduuid

Grupo dono. Ausente se a seção é de um modelo.

section_definition_iduuid

Definição usada.

namestring

Nome da instância.

settings_valuesobject

Valores dos campos, por key.

sort_orderinteger

Posição (a partir de 0).

visibleboolean

false esconde a seção da vitrine sem excluir.

custom_cssstring

CSS livre.

definition_slugstring

Só em listagens: slug da definição.

definition_namestring

Só em listagens: nome da definição.

settings_schemaobject[]

Só em listagens: esquema de campos da definição.

block_definitionsobject[]

Só em listagens: blocos aceitos.

created_atstring

Criação (RFC 3339).

updated_atstring

Última alteração (RFC 3339).

Erros

Status	Quando	Corpo de exemplo
400	Nenhum dos dois parâmetros informado.	`{"error":"template_id or group_id query param 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 list template sections","detail":"..."}`

Inserir seção

Cria a instância de uma definição num modelo ou grupo. A seção nasce visível.

POST/api/v1/admin/theme-builder/template-sectionsAdmin

Inserir uma seção

Requer o privilégio manage_theme.

Corpo da requisição

template_iduuid

Modelo de destino. Informe este ou section_group_id.

section_group_iduuid

Grupo de destino.

section_definition_iduuidobrigatório

Definição a instanciar.

namestring

Nome da instância.

settings_valuesobjectpadrão: {}

Valores iniciais.

sort_orderintegerpadrão: 0

Posição. Ajuste depois com reordenar.

custom_cssstring

CSS livre.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/admin/theme-builder/template-sections" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "template_id": "30a0a88f-2eba-4a7a-bdea-ab73b761ab99",
    "section_definition_id": "49ee1ac9-b950-4526-8ffd-571caae96a45",
    "name": "Novidades",
    "settings_values": {
      "heading": "Novidades da semana"
    },
    "sort_order": 3
  }'

Resposta

201Seção criada

json

{
  "id": "f5f5f5f5-0000-4000-8000-000000000005",
  "template_id": "30a0a88f-2eba-4a7a-bdea-ab73b761ab99",
  "section_definition_id": "49ee1ac9-b950-4526-8ffd-571caae96a45",
  "name": "Novidades",
  "settings_values": {
    "heading": "Novidades da semana"
  },
  "sort_order": 3,
  "visible": true,
  "custom_css": "",
  "created_at": "2026-05-14T13:55:40.071821Z",
  "updated_at": "2026-05-14T13:55:40.071821Z",
  "definition_slug": "hero-banner",
  "definition_name": "Hero Banner"
}

Campos da resposta

iduuid

Id da seção inserida.

template_iduuid

Modelo dono. Ausente se a seção é de um grupo.

section_group_iduuid

Grupo dono. Ausente se a seção é de um modelo.

section_definition_iduuid

Definição usada.

namestring

Nome da instância.

settings_valuesobject

Valores dos campos, por key.

sort_orderinteger

Posição (a partir de 0).

visibleboolean

false esconde a seção da vitrine sem excluir.

custom_cssstring

CSS livre.

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	`section_definition_id` vazio.	`{"error":"section_definition_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_theme`.	`{"error":"insufficient privileges","required":"manage_theme"}`
500	Nem `template_id` nem `section_group_id`, ou ids inexistentes.	`{"error":"failed to add section","detail":"template_id or section_group_id is required"}`

Atualizar valores

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

Atualizar os valores 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

settings_valuesobjectobrigatório

Novos valores, por key do esquema da definição.

Exemplo de requisição

bash

curl -X PUT "$BASE_URL/api/v1/admin/theme-builder/template-sections/3d4dfa54-1a77-403d-b447-19d10718fe56" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "settings_values": {
      "layout": "carousel",
      "autoplay": false,
      "min_height": "500px"
    }
  }'

Resposta

200Seção atualizada

json

{
  "message": "section 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	Seção não existe.	`{"error":"template section not found","detail":"not found: ..."}`
500	Falha de banco de dados ou dado inválido para a coluna.	`{"error":"failed to update section settings","detail":"..."}`

Remover seção

Remove a seção e os blocos dela.

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

Remover 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 DELETE "$BASE_URL/api/v1/admin/theme-builder/template-sections/3d4dfa54-1a77-403d-b447-19d10718fe56" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Removida

json

{
  "message": "section 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	Seção não existe.	`{"error":"template section not found","detail":"not found: ..."}`
500	Falha de banco de dados ou dado inválido para a coluna.	`{"error":"failed to remove section","detail":"..."}`