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

Ciclo de vida do tema

Duplica, publica e coloca um tema ao vivo, e cria o tema inicial padrão.

"Publicar" e "colocar ao vivo" são passos diferentes. Publicar muda o estado do tema para A (publicado): ele fica apto a ir ao ar, mas a vitrine ainda não o usa. Definir como ao vivo liga o tema à vitrine e desliga o anterior; só temas publicados podem ir ao vivo.

Sequência para trocar de tema

Duplicar (ou criar), editar o rascunho, publicar o rascunho, publicar o tema e só então definir como ao vivo.

Duplicar tema

Copia o tema inteiro (definições de seção, modelos, grupos, seções e blocos) para um tema novo em rascunho, nomeado <nome> (Copy), com slug <slug>-copy-<timestamp>. Sem corpo.

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

Duplicar um tema

Requer o privilégio manage_theme.

Parâmetros de caminho

iduuidobrigatório
Id do tema de origem.

Exemplo de requisição

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

Resposta

201Cópia criada
json
{
  "id": "a0c1d2e3-1111-4222-8333-444455556666",
  "name": "Default (Copy)",
  "slug": "default-copy-1791800000",
  "description": "Starter theme",
  "thumbnail_url": "",
  "author": "Venddor",
  "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
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"}
500Tema de origem inexistente ou falha na cópia.{"error":"failed to duplicate theme","detail":"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 duplicate 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 inicial

Cria o tema "Default" (slug default) com cerca de 20 definições de seção, um modelo de home e os grupos de cabeçalho e rodapé já preenchidos. É idempotente: se já existe um tema com slug default, devolve esse. Sem corpo.

POST/api/v1/admin/theme-builder/themes/seedAdmin

Criar o tema inicial padrão

Requer o privilégio manage_theme.

Exemplo de requisição

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

Resposta

201Tema inicial
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"}
500Falha de banco de dados ou dado inválido para a coluna.{"error":"failed to seed default theme","detail":"..."}
Sempre 201

Mesmo quando o tema já existia e nada foi criado, o status é 201.

Publicar tema

Muda o estado do tema para A (publicado). Antes, uma verificação de orçamento de desempenho pesa os arquivos do rascunho do tema (imagens, scripts): se algum estourar o limite, a rota responde 422 com a lista de violações e não publica.

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

Publicar o tema

Requer o privilégio manage_theme.

Parâmetros de caminho

iduuidobrigatório
Id do tema.

Parâmetros de consulta

forceboolean
true ignora o orçamento de desempenho e publica assim mesmo.
optimizeboolean
true recomprime automaticamente as imagens que estouram o limite (o original é preservado) e segue com a publicação; se nada puder ser otimizado, cai no 422.

Exemplo de requisição

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

Resposta

200Tema publicado
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"
}
422Orçamento de desempenho estourado
json
{
  "violations": [
    {
      "rule": "image_size",
      "severity": "error",
      "asset_url": "/uploads/banner.png",
      "actual_bytes": 4200000,
      "limit_bytes": 400000,
      "fix": "auto"
    }
  ]
}

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).
violations[]object[]
Só no 422: rule, severity (error bloqueia, warning não), asset_url, actual_bytes, limit_bytes e fix (auto se optimize resolve, manual, none).

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 ..."}
422Há violações de severidade error no rascunho.{"violations":[{"rule":"...","severity":"error"}]}
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 publish 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."}

Definir tema ao vivo

Liga o tema à vitrine e desliga o tema ao vivo anterior, na mesma transação. O tema precisa estar publicado (status: A). Sem corpo.

POST/api/v1/admin/theme-builder/themes/{id}/set-liveAdmin

Colocar o tema ao vivo

Requer o privilégio manage_theme.

Parâmetros de caminho

iduuidobrigatório
Id do tema.

Exemplo de requisição

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

Resposta

200Tema ao vivo
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","detail":"not found: theme ..."}
500O tema não está publicado (only published themes can be set as live).{"error":"failed to set live theme","detail":"only published themes can be set as live"}
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 set live 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."}
A troca é imediata

Os clientes passam a ver o novo tema na próxima página aberta. Confira o tema antes e mantenha o anterior para poder voltar.

Veja também

  • Theme Builder: visão geral
  • Temas
Anterior
Temas
Próxima
Importar e exportar tema
Nesta página
  • Duplicar tema
  • Exemplo de requisição
  • Resposta
  • Erros
  • Criar tema inicial
  • Exemplo de requisição
  • Resposta
  • Erros
  • Publicar tema
  • Exemplo de requisição
  • Resposta
  • Erros
  • Definir tema ao vivo
  • Exemplo de requisição
  • Resposta
  • Erros
  • Veja também