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

Definições de seção

Cadastra os tipos de seção que o tema oferece, com os campos que o lojista pode editar.

Uma definição de seção é o "molde" de um pedaço da página: um banner de destaque, uma grade de produtos, um bloco de texto. Ela descreve quais campos existem (settings_schema) e quais blocos filhos aceita (block_definitions). Para colocar uma seção numa página, você cria uma instância que aponta para a definição.

Listar definições

Devolve todas as definições do tema, inclusive as inativas. O tema inicial tem 22.

GET/api/v1/admin/theme-builder/themes/{id}/section-definitionsAdmin

Listar as definições de seção do tema

Requer o privilégio manage_theme.

Parâmetros de caminho

iduuidobrigatório
Id do tema.

Exemplo de requisição

bash
curl -X GET "$BASE_URL/api/v1/admin/theme-builder/themes/fb9134bb-7063-46a5-96f8-bad686d1c69b/section-definitions" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Definições
json
{
  "section_definitions": [
    {
      "id": "49ee1ac9-b950-4526-8ffd-571caae96a45",
      "theme_id": "fb9134bb-7063-46a5-96f8-bad686d1c69b",
      "name": "Rich Text",
      "slug": "rich-text",
      "description": "A section for rich text content.",
      "category": "content",
      "icon": "type",
      "thumbnail_url": "",
      "settings_schema": [
        {
          "key": "heading",
          "type": "text",
          "label": "Heading"
        },
        {
          "key": "content",
          "type": "richtext",
          "label": "Content"
        }
      ],
      "block_definitions": [],
      "presets": [],
      "max_blocks": 16,
      "sort_order": 0,
      "is_active": true,
      "created_at": "2026-04-07T02:46:02.491306Z",
      "updated_at": "2026-04-07T02:46:02.491306Z"
    }
  ]
}

Campos da resposta

section_definitionsarray

Definições.

iduuid
Id da definição.
theme_iduuid
Tema dono.
namestring
Nome.
slugstring
Identificador da seção, por exemplo hero-banner.
descriptionstring
Descrição.
categorystring
Categoria no seletor: header, hero, products, content, social_proof, marketing, footer, utility ou custom (padrão ao criar).
iconstring
Nome do ícone.
thumbnail_urlstring
Miniatura.
settings_schemaobject[]
Campos que o lojista edita na seção (key, type, label, default...). Mesmos tipos de campo dos ajustes globais do tema.
block_definitionsobject[]
Tipos de bloco aceitos dentro da seção: type, name, limit e settings_schema.
presetsobject[]
Configurações prontas oferecidas ao inserir a seção.
max_blocksinteger
Máximo de blocos na seção.
sort_orderinteger
Ordem no seletor.
is_activeboolean
Se aparece no seletor.
created_atstring
Criação (RFC 3339).
updated_atstring
Última alteração (RFC 3339).

Erros

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

Criar definição

Cadastra um novo tipo de seção no tema.

POST/api/v1/admin/theme-builder/themes/{id}/section-definitionsAdmin

Criar uma definição de seção

Requer o privilégio manage_theme.

Parâmetros de caminho

iduuidobrigatório
Id do tema.

Corpo da requisição

namestringobrigatório
Nome.
slugstringobrigatório
Identificador único da seção no tema. Obrigatório de fato: sem ele a rota falha com 500.
descriptionstring
Descrição.
categorystringpadrão: custom
Categoria.
iconstring
Ícone.
thumbnail_urlstring
Miniatura.
settings_schemaobject[]padrão: []
Campos editáveis da seção.
block_definitionsobject[]padrão: []
Blocos aceitos.
presetsobject[]padrão: []
Predefinições.
max_blocksintegerpadrão: 16
Máximo de blocos.
sort_orderintegerpadrão: 0
Ordem no seletor.

Exemplo de requisição

bash
curl -X POST "$BASE_URL/api/v1/admin/theme-builder/themes/fb9134bb-7063-46a5-96f8-bad686d1c69b/section-definitions" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Selo de confiança",
    "slug": "trust-badges",
    "category": "marketing",
    "settings_schema": [
      {
        "key": "title",
        "type": "text",
        "label": "Título",
        "default": "Compra segura"
      }
    ]
  }'

Resposta

201Definição criada
json
{
  "id": "c3c3c3c3-0000-4000-8000-000000000003",
  "theme_id": "fb9134bb-7063-46a5-96f8-bad686d1c69b",
  "name": "Selo de confiança",
  "slug": "trust-badges",
  "description": "A section for rich text content.",
  "category": "marketing",
  "icon": "type",
  "thumbnail_url": "",
  "settings_schema": [
    {
      "key": "heading",
      "type": "text",
      "label": "Heading"
    },
    {
      "key": "content",
      "type": "richtext",
      "label": "Content"
    }
  ],
  "block_definitions": [],
  "presets": [],
  "max_blocks": 16,
  "sort_order": 0,
  "is_active": true,
  "created_at": "2026-04-07T02:46:02.491306Z",
  "updated_at": "2026-04-07T02:46:02.491306Z"
}

Campos da resposta

iduuid
Id da definição.
theme_iduuid
Tema dono.
namestring
Nome.
slugstring
Identificador da seção, por exemplo hero-banner.
descriptionstring
Descrição.
categorystring
Categoria no seletor: header, hero, products, content, social_proof, marketing, footer, utility ou custom (padrão ao criar).
iconstring
Nome do ícone.
thumbnail_urlstring
Miniatura.
settings_schemaobject[]
Campos que o lojista edita na seção (key, type, label, default...). Mesmos tipos de campo dos ajustes globais do tema.
block_definitionsobject[]
Tipos de bloco aceitos dentro da seção: type, name, limit e settings_schema.
presetsobject[]
Configurações prontas oferecidas ao inserir a seção.
max_blocksinteger
Máximo de blocos na seção.
sort_orderinteger
Ordem no seletor.
is_activeboolean
Se aparece no seletor.
created_atstring
Criação (RFC 3339).
updated_atstring
Última alteração (RFC 3339).

Erros

StatusQuandoCorpo de exemplo
400Corpo JSON inválido.{"error":"invalid request body","detail":"unexpected EOF"}
400name vazio.{"error":"name is required"}
401Sem token, token inválido ou expirado.{"error":"invalid or expired token"}
403Seu usuário não tem o privilégio manage_theme.{"error":"insufficient privileges","required":"manage_theme"}
500slug vazio, ou slug já usado no tema, ou tema inexistente.{"error":"failed to create section definition","detail":"section slug is required"}

Atualizar definição

Altera os campos enviados. As seções já inseridas nas páginas continuam apontando para a definição e passam a usar o novo esquema; valores em settings_values de chaves que deixaram de existir ficam guardados, mas sem efeito.

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

Atualizar uma definição de seção

Requer o privilégio manage_theme.

Parâmetros de caminho

iduuidobrigatório
Id da definição.

Corpo da requisição

namestring
Nome.
slugstring
Identificador único da seção no tema. Obrigatório de fato: sem ele a rota falha com 500.
descriptionstring
Descrição.
categorystring
Categoria.
iconstring
Ícone.
thumbnail_urlstring
Miniatura.
settings_schemaobject[]
Campos editáveis da seção.
block_definitionsobject[]
Blocos aceitos.
presetsobject[]
Predefinições.
max_blocksinteger
Máximo de blocos.
sort_orderinteger
Ordem no seletor.
is_activeboolean
false esconde a definição do seletor.

Exemplo de requisição

bash
curl -X PUT "$BASE_URL/api/v1/admin/theme-builder/section-definitions/49ee1ac9-b950-4526-8ffd-571caae96a45" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "is_active": false
  }'

Resposta

200Definição atualizada
json
{
  "message": "section definition updated"
}

Erros

StatusQuandoCorpo de exemplo
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_theme.{"error":"insufficient privileges","required":"manage_theme"}
404Definição não existe.{"error":"section definition not found","detail":"not found: ..."}
500Falha de banco de dados ou dado inválido para a coluna.{"error":"failed to update section definition","detail":"..."}

Excluir definição

Remove a definição. Se houver seções inseridas nas páginas que dependem dela, o banco pode recusar ou apagá-las em cascata; confira antes com listar seções.

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

Excluir uma definição de seção

Requer o privilégio manage_theme.

Parâmetros de caminho

iduuidobrigatório
Id da definição.

Exemplo de requisição

bash
curl -X DELETE "$BASE_URL/api/v1/admin/theme-builder/section-definitions/49ee1ac9-b950-4526-8ffd-571caae96a45" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Excluída
json
{
  "message": "section definition deleted"
}

Erros

StatusQuandoCorpo de exemplo
401Sem token, token inválido ou expirado.{"error":"invalid or expired token"}
403Seu usuário não tem o privilégio manage_theme.{"error":"insufficient privileges","required":"manage_theme"}
404Definição não existe.{"error":"section definition not found","detail":"not found: ..."}
500Falha de banco de dados ou dado inválido para a coluna.{"error":"failed to delete section definition","detail":"..."}

Veja também

  • Theme Builder: visão geral
  • Seções
Anterior
Rascunho do tema
Próxima
Modelos de página
Nesta página
  • Listar definições
  • Exemplo de requisição
  • Resposta
  • Erros
  • Criar definição
  • Exemplo de requisição
  • Resposta
  • Erros
  • Atualizar definição
  • Exemplo de requisição
  • Resposta
  • Erros
  • Excluir definição
  • Exemplo de requisição
  • Resposta
  • Erros
  • Veja também