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

Temas

Lista, consulta, cria, altera e exclui os temas da vitrine.

Um tema reúne a aparência de toda a vitrine: ajustes globais (cores, fontes, raio de borda), seções reutilizáveis, modelos de página e os grupos de cabeçalho e rodapé. A loja pode ter vários temas, mas só um está ao vivo (is_live: true). Estas rotas gerenciam o cadastro do tema; o conteúdo dele é editado nas demais páginas desta seção.

Listar temas

Devolve todos os temas da loja, sem paginação.

GET/api/v1/admin/theme-builder/themesAdmin

Listar os temas

Requer o privilégio manage_theme.

Exemplo de requisição

bash
curl -X GET "$BASE_URL/api/v1/admin/theme-builder/themes" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Temas
json
{
  "themes": [
    {
      "id": "fb9134bb-7063-46a5-96f8-bad686d1c69b",
      "name": "Default",
      "slug": "default",
      "description": "Starter theme",
      "thumbnail_url": "",
      "author": "Venddor",
      "version": "1.0.0",
      "status": "A",
      "is_live": true,
      "global_settings_schema": [
        {
          "key": "primary_color",
          "type": "color",
          "label": "Primary Color",
          "default": "#2563EB"
        }
      ],
      "global_settings_values": {
        "primary_color": "#2563EB",
        "font_body": "Inter",
        "border_radius": 8
      },
      "created_at": "2026-04-07T02:46:02.491306Z",
      "updated_at": "2026-04-07T02:46:02.491306Z"
    }
  ]
}

Campos da resposta

themesarray

Temas.

iduuid
Id do tema.
namestring
Nome.
slugstring
Identificador curto, único na loja.
descriptionstring
Descrição.
thumbnail_urlstring
Imagem de capa.
authorstring
Autor.
versionstring
Versão do tema, texto livre (1.0.0).
statusstring
Estado em letra: R rascunho, A publicado, L ao vivo, D arquivado. Tema "ao vivo" é indicado por is_live.
is_liveboolean
true no tema que a vitrine está usando. Só um por loja.
global_settings_schemaobject[]
Definição dos ajustes globais do tema (cores, fontes...): cada item tem key, type, label, default e, conforme o tipo, options, min, max, step, unit, placeholder, info. Tipos: text, textarea, richtext, url, image, color, range, number, checkbox, select, collection, product.
global_settings_valuesobject
Valores atuais dos ajustes globais, por key.
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"}
500Falha de banco de dados ou dado inválido para a coluna.{"error":"failed to list themes","detail":"..."}

Obter tema

Devolve o tema com seus ajustes globais. Seções, modelos e grupos têm rotas próprias.

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

Obter um tema

Requer o privilégio manage_theme.

Parâmetros de caminho

iduuidobrigatório
Id do tema (UUID).

Exemplo de requisição

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

Resposta

200Tema
json
{
  "id": "fb9134bb-7063-46a5-96f8-bad686d1c69b",
  "name": "Default",
  "slug": "default",
  "description": "Starter theme",
  "thumbnail_url": "",
  "author": "Venddor",
  "version": "1.0.0",
  "status": "A",
  "is_live": true,
  "global_settings_schema": [
    {
      "key": "primary_color",
      "type": "color",
      "label": "Primary Color",
      "default": "#2563EB"
    }
  ],
  "global_settings_values": {
    "primary_color": "#2563EB",
    "font_body": "Inter",
    "border_radius": 8
  },
  "created_at": "2026-04-07T02:46:02.491306Z",
  "updated_at": "2026-04-07T02:46:02.491306Z"
}

Campos da resposta

iduuid
Id do tema.
namestring
Nome.
slugstring
Identificador curto, único na loja.
descriptionstring
Descrição.
thumbnail_urlstring
Imagem de capa.
authorstring
Autor.
versionstring
Versão do tema, texto livre (1.0.0).
statusstring
Estado em letra: R rascunho, A publicado, L ao vivo, D arquivado. Tema "ao vivo" é indicado por is_live.
is_liveboolean
true no tema que a vitrine está usando. Só um por loja.
global_settings_schemaobject[]
Definição dos ajustes globais do tema (cores, fontes...): cada item tem key, type, label, default e, conforme o tipo, options, min, max, step, unit, placeholder, info. Tipos: text, textarea, richtext, url, image, color, range, number, checkbox, select, collection, product.
global_settings_valuesobject
Valores atuais dos ajustes globais, por key.
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"}
404Tema não existe.{"error":"theme not found"}
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 get theme","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."}

Criar tema

Cria um tema novo, por padrão em rascunho e sem seções. Para partir de algo pronto, prefira duplicar ou importar.

POST/api/v1/admin/theme-builder/themesAdmin

Criar um tema vazio

Requer o privilégio manage_theme.

Corpo da requisição

namestringobrigatório
Nome do tema.
slugstringobrigatório
Identificador curto e único, por exemplo outono-2026. Em branco falha com 500 (theme slug is required).
descriptionstring
Descrição.
thumbnail_urlstring
Imagem de capa.
authorstring
Autor.
versionstringpadrão: 1.0.0
Versão.
statusstringpadrão: draft
Estado inicial. Aceita draft, published, live, archived ou a letra (R, A, L, D).
global_settings_schemaobject[]padrão: []
Definição dos ajustes globais.
global_settings_valuesobjectpadrão: {}
Valores dos ajustes globais.

Exemplo de requisição

bash
curl -X POST "$BASE_URL/api/v1/admin/theme-builder/themes" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Outono 2026",
    "slug": "outono-2026",
    "author": "Equipe de marca"
  }'

Resposta

201Tema criado
json
{
  "id": "a0c1d2e3-1111-4222-8333-444455556666",
  "name": "Outono 2026",
  "slug": "outono-2026",
  "description": "Starter theme",
  "thumbnail_url": "",
  "author": "Equipe de marca",
  "version": "1.0.0",
  "status": "R",
  "is_live": false,
  "global_settings_schema": [
    {
      "key": "primary_color",
      "type": "color",
      "label": "Primary Color",
      "default": "#2563EB"
    }
  ],
  "global_settings_values": {
    "primary_color": "#2563EB",
    "font_body": "Inter",
    "border_radius": 8
  },
  "created_at": "2026-04-07T02:46:02.491306Z",
  "updated_at": "2026-04-07T02:46:02.491306Z"
}

Campos da resposta

iduuid
Id do tema.
namestring
Nome.
slugstring
Identificador curto, único na loja.
descriptionstring
Descrição.
thumbnail_urlstring
Imagem de capa.
authorstring
Autor.
versionstring
Versão do tema, texto livre (1.0.0).
statusstring
Estado em letra: R rascunho, A publicado, L ao vivo, D arquivado. Tema "ao vivo" é indicado por is_live.
is_liveboolean
true no tema que a vitrine está usando. Só um por loja.
global_settings_schemaobject[]
Definição dos ajustes globais do tema (cores, fontes...): cada item tem key, type, label, default e, conforme o tipo, options, min, max, step, unit, placeholder, info. Tipos: text, textarea, richtext, url, image, color, range, number, checkbox, select, collection, product.
global_settings_valuesobject
Valores atuais dos ajustes globais, por key.
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 ("theme slug is required") ou já usado por outro tema.{"error":"failed to create theme","detail":"theme slug is required"}

Atualizar tema

Altera só os campos enviados. Para ajustar cores e fontes, envie global_settings_values: o objeto é substituído por inteiro, então leia o atual e devolva completo. Esta rota não coloca o tema no ar; para isso use definir como ao vivo.

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

Atualizar dados do tema

Requer o privilégio manage_theme.

Parâmetros de caminho

iduuidobrigatório
Id do tema (UUID).

Corpo da requisição

namestring
Nome do tema.
slugstring
Identificador curto e único, por exemplo outono-2026.
descriptionstring
Descrição.
thumbnail_urlstring
Imagem de capa.
authorstring
Autor.
versionstring
Versão.
statusstring
Estado inicial. Aceita draft, published, live, archived ou a letra (R, A, L, D).
global_settings_schemaobject[]
Definição dos ajustes globais.
global_settings_valuesobject
Valores dos ajustes globais.

Exemplo de requisição

bash
curl -X PUT "$BASE_URL/api/v1/admin/theme-builder/themes/fb9134bb-7063-46a5-96f8-bad686d1c69b" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "global_settings_values": {
      "primary_color": "#B45309",
      "font_body": "Inter",
      "border_radius": 8
    }
  }'

Resposta

200Tema atualizado
json
{
  "id": "fb9134bb-7063-46a5-96f8-bad686d1c69b",
  "name": "Default",
  "slug": "default",
  "description": "Starter theme",
  "thumbnail_url": "",
  "author": "Venddor",
  "version": "1.0.0",
  "status": "A",
  "is_live": true,
  "global_settings_schema": [
    {
      "key": "primary_color",
      "type": "color",
      "label": "Primary Color",
      "default": "#2563EB"
    }
  ],
  "global_settings_values": {
    "primary_color": "#2563EB",
    "font_body": "Inter",
    "border_radius": 8
  },
  "created_at": "2026-04-07T02:46:02.491306Z",
  "updated_at": "2026-04-07T02:46:02.491306Z"
}

Campos da resposta

iduuid
Id do tema.
namestring
Nome.
slugstring
Identificador curto, único na loja.
descriptionstring
Descrição.
thumbnail_urlstring
Imagem de capa.
authorstring
Autor.
versionstring
Versão do tema, texto livre (1.0.0).
statusstring
Estado em letra: R rascunho, A publicado, L ao vivo, D arquivado. Tema "ao vivo" é indicado por is_live.
is_liveboolean
true no tema que a vitrine está usando. Só um por loja.
global_settings_schemaobject[]
Definição dos ajustes globais do tema (cores, fontes...): cada item tem key, type, label, default e, conforme o tipo, options, min, max, step, unit, placeholder, info. Tipos: text, textarea, richtext, url, image, color, range, number, checkbox, select, collection, product.
global_settings_valuesobject
Valores atuais dos ajustes globais, por key.
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"}
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"}
404Tema não existe.{"error":"theme not found","detail":"theme fb9134bb-7063-46a5-96f8-bad686d1c69b"}
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 update theme","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."}

Excluir tema

Exclui o tema e tudo o que pertence a ele (seções, modelos, grupos, rascunho). Não é possível excluir o tema ao vivo.

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

Excluir um tema

Requer o privilégio manage_theme.

Parâmetros de caminho

iduuidobrigatório
Id do tema (UUID).

Exemplo de requisição

bash
curl -X DELETE "$BASE_URL/api/v1/admin/theme-builder/themes/a0c1d2e3-1111-4222-8333-444455556666" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Excluído
json
{
  "message": "theme 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"}
404Tema não existe.{"error":"theme not found","detail":"not found: theme ..."}
500O tema está ao vivo (cannot delete the live theme). Defina outro como ao vivo antes. Esta rota devolve 500 e não 409.{"error":"failed to delete theme","detail":"cannot delete the live 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 delete theme","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."}
Sem desfazer

A exclusão é definitiva. Exporte o tema antes se houver qualquer chance de precisar dele.

Veja também

  • Theme Builder: visão geral
  • Ciclo de vida do tema
Anterior
Theme Builder
Próxima
Ciclo de vida do tema
Nesta página
  • Listar temas
  • Exemplo de requisição
  • Resposta
  • Erros
  • Obter tema
  • Exemplo de requisição
  • Resposta
  • Erros
  • Criar tema
  • Exemplo de requisição
  • Resposta
  • Erros
  • Atualizar tema
  • Exemplo de requisição
  • Resposta
  • Erros
  • Excluir tema
  • Exemplo de requisição
  • Resposta
  • Erros
  • Veja também