API atual/Referência completa/Temas da vitrine

Ativar, copiar e importar

Ativa um tema, duplica, cria o tema padrão, exporta para arquivo e importa de um arquivo exportado.

Ações sobre temas inteiros. Todas exigem o privilégio manage_theme.

Ativar tema

POST/api/v1/admin/storefront-themes/{id}/activateAdmin

Torna o tema o tema em uso da vitrine

Desativa o tema atual e ativa este, de forma atômica. Se o tema não tiver nenhum layout padrão, o layout editado mais recentemente (que não seja rascunho) vira o padrão dele, para a ativação ter efeito visível. A vitrine passa a usar os layouts e o estilo ativo deste tema.

Parâmetros de caminho

iduuidobrigatório

Id do tema.

200Tema ativado

json

{ "message": "activated" }

Duplicar tema

POST/api/v1/admin/storefront-themes/{id}/duplicateAdmin

Copia um tema com todos os estilos e layouts

Cria um novo tema chamado <nome> (Cópia) com todos os estilos (cores, fontes, CSS e tokens avançados, iguais ao original) e clona cada layout do tema de origem. A cópia não é ativada. Se um layout falhar ao clonar, os demais seguem e o erro só é registrado no log.

Parâmetros de caminho

iduuidobrigatório

Id do tema de origem.

A resposta 201 é o tema novo, com styles, no mesmo formato de Criar tema.

Semear o tema padrão

POST/api/v1/admin/storefront-themes/seedAdmin

Cria um tema novo com os valores padrão da plataforma

Sem corpo. Cria um tema chamado Tema Padrão (ou Tema Padrão 2, Tema Padrão 3... se já existirem) com um estilo padrão e um layout inicial. Útil para começar do zero sem preencher campos.

A resposta 201 é o tema criado, com styles.

Exportar tema

GET/api/v1/admin/storefront-themes/{id}/exportAdmin

Gera um arquivo JSON portátil do tema

Devolve o nome do tema e todos os estilos (cores, tipografia, CSS próprio e extended_config). Não exporta layouts nem ids: para copiar a estrutura das páginas use duplicar.

Parâmetros de caminho

iduuidobrigatório

Id do tema.

200Tema exportado

json

{
  "version": "1.0",
  "exported_at": "2026-10-11T16:10:00.000Z",
  "name": "Natal 2026",
  "styles": [
    {
      "name": "Default",
      "primary_color": "#dc2626",
      "secondary_color": "#991b1b",
      "accent_color": "#f59e0b",
      "bg_color": "#ffffff",
      "text_color": "#1f2937",
      "font_family": "Inter, sans-serif",
      "heading_font": "Inter, sans-serif",
      "border_radius": "8px",
      "max_width": "1280px",
      "custom_css": ""
    }
  ]
}

Campos da resposta

versionstring

Versão do formato, hoje 1.0.

exported_atstring

Momento da exportação (RFC 3339, UTC).

namestring

Nome do tema.

stylesarray

Estilos, com os mesmos campos de Criar estilo (o exemplo mostra só alguns).

Importar tema

POST/api/v1/admin/storefront-themes/importAdmin

Cria um tema novo a partir de um arquivo exportado

Cria um tema chamado <nome> (Importado), inativo, e aplica os estilos do arquivo. O primeiro estilo substitui o Default que a criação gera; os demais viram estilos adicionais. O tema importado nasce sem layouts (só estilos): crie um layout para ele antes de ativar. Funciona entre lojas diferentes.

Corpo da requisição

versionstring

Versão do formato. Não é validada.

namestring

Nome base do tema. Vazio vira Imported Theme.

stylesarray

Estilos a criar, no formato do export. Se vier vazio, o tema fica só com o estilo Default.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/admin/storefront-themes/import" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"version":"1.0","name":"Natal 2026","styles":[{"name":"Default","primary_color":"#dc2626"}]}'

A resposta 201 é o tema criado. Campos de cor ou fonte ausentes em um estilo recebem o valor padrão.

Erros

Status	Quando	Corpo
400	Corpo JSON inválido (importar)	`{"error":"invalid request body","detail":"..."}`
401	Sem token ou token expirado	`{"error":"missing authorization header"}`
403	Sem o privilégio `manage_theme`	`{"error":"insufficient privileges","required":"manage_theme"}`
404	Tema inexistente (ativar, duplicar, exportar)	`{"error":"not found","detail":"not found"}`
500	`id` que não é UUID; falha ao criar o tema ou algum estilo	`{"error":"failed to activate theme","detail":"..."}`

Veja também

API atual/Referência completa/Temas da vitrine

Ativar, copiar e importar

Ativa um tema, duplica, cria o tema padrão, exporta para arquivo e importa de um arquivo exportado.

Ações sobre temas inteiros. Todas exigem o privilégio manage_theme.

Ativar tema

POST/api/v1/admin/storefront-themes/{id}/activateAdmin

Torna o tema o tema em uso da vitrine

Parâmetros de caminho

iduuidobrigatório

Id do tema.

200Tema ativado

json

{ "message": "activated" }

Duplicar tema

POST/api/v1/admin/storefront-themes/{id}/duplicateAdmin

Copia um tema com todos os estilos e layouts

Parâmetros de caminho

iduuidobrigatório

Id do tema de origem.

A resposta 201 é o tema novo, com styles, no mesmo formato de Criar tema.

Semear o tema padrão

POST/api/v1/admin/storefront-themes/seedAdmin

Cria um tema novo com os valores padrão da plataforma

Sem corpo. Cria um tema chamado Tema Padrão (ou Tema Padrão 2, Tema Padrão 3... se já existirem) com um estilo padrão e um layout inicial. Útil para começar do zero sem preencher campos.

A resposta 201 é o tema criado, com styles.

Exportar tema

GET/api/v1/admin/storefront-themes/{id}/exportAdmin

Gera um arquivo JSON portátil do tema

Devolve o nome do tema e todos os estilos (cores, tipografia, CSS próprio e extended_config). Não exporta layouts nem ids: para copiar a estrutura das páginas use duplicar.

Parâmetros de caminho

iduuidobrigatório

Id do tema.

200Tema exportado

json

{
  "version": "1.0",
  "exported_at": "2026-10-11T16:10:00.000Z",
  "name": "Natal 2026",
  "styles": [
    {
      "name": "Default",
      "primary_color": "#dc2626",
      "secondary_color": "#991b1b",
      "accent_color": "#f59e0b",
      "bg_color": "#ffffff",
      "text_color": "#1f2937",
      "font_family": "Inter, sans-serif",
      "heading_font": "Inter, sans-serif",
      "border_radius": "8px",
      "max_width": "1280px",
      "custom_css": ""
    }
  ]
}

Campos da resposta

versionstring

Versão do formato, hoje 1.0.

exported_atstring

Momento da exportação (RFC 3339, UTC).

namestring

Nome do tema.

stylesarray

Estilos, com os mesmos campos de Criar estilo (o exemplo mostra só alguns).

Importar tema

POST/api/v1/admin/storefront-themes/importAdmin

Cria um tema novo a partir de um arquivo exportado

Corpo da requisição

versionstring

Versão do formato. Não é validada.

namestring

Nome base do tema. Vazio vira Imported Theme.

stylesarray

Estilos a criar, no formato do export. Se vier vazio, o tema fica só com o estilo Default.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/admin/storefront-themes/import" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"version":"1.0","name":"Natal 2026","styles":[{"name":"Default","primary_color":"#dc2626"}]}'

A resposta 201 é o tema criado. Campos de cor ou fonte ausentes em um estilo recebem o valor padrão.

Erros

Status	Quando	Corpo
400	Corpo JSON inválido (importar)	`{"error":"invalid request body","detail":"..."}`
401	Sem token ou token expirado	`{"error":"missing authorization header"}`
403	Sem o privilégio `manage_theme`	`{"error":"insufficient privileges","required":"manage_theme"}`
404	Tema inexistente (ativar, duplicar, exportar)	`{"error":"not found","detail":"not found"}`
500	`id` que não é UUID; falha ao criar o tema ou algum estilo	`{"error":"failed to activate theme","detail":"..."}`