API atual/Referência completa/Temas da vitrine

Estilos

Lista, cria, altera, exclui e ativa os estilos (cores, fontes e CSS) de um tema.

Um estilo é uma variação visual do tema: cores, tipografia, geometria, CSS próprio e tokens avançados. Um tema pode ter muitos estilos, mas só um ativo, e é ele que a vitrine usa. Todas as rotas exigem o privilégio manage_theme.

Listar estilos

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

Lista os estilos de um tema

Sem paginação. Em temas com muitos estilos a resposta pode ser grande.

Parâmetros de caminho

iduuidobrigatório

Id do tema.

200Estilos retornados

json

{
  "styles": [
    {
      "id": "cd9e5a33-508e-4c69-8e85-85e20f3ad712",
      "theme_id": "a650691c-22f3-4508-9a83-9418c04976a6",
      "name": "Runner",
      "is_active": true,
      "primary_color": "#2563eb",
      "secondary_color": "#2563eb",
      "accent_color": "#f59e0b",
      "bg_color": "#ffffff",
      "text_color": "#1f2937",
      "header_bg_color": "#ffffff",
      "footer_bg_color": "#2563eb",
      "link_color": "#2563eb",
      "link_hover_color": "#1f54c8",
      "heading_color": "#1f2937",
      "muted_text_color": "#797f87",
      "border_color": "#e5e7eb",
      "button_text_color": "#ffffff",
      "font_family": "Inter, sans-serif",
      "heading_font": "Inter, sans-serif",
      "border_radius": "8px",
      "max_width": "1280px",
      "custom_css": "",
      "extended_config": {},
      "created_at": "2026-08-02T04:49:40.245408Z",
      "updated_at": "2026-08-02T04:49:40.263163Z"
    }
  ],
  "total": 1
}

Campos de um estilo

iduuid

Identificador do estilo.

theme_iduuid

Tema dono.

namestring

Nome do estilo.

is_activeboolean

Se é o estilo em uso no tema.

primary_colorstring

Cor principal (botões, destaques). Hexadecimal, por exemplo #2563eb.

secondary_colorstring

Cor secundária.

accent_colorstring

Cor de destaque.

bg_colorstring

Cor de fundo da página.

text_colorstring

Cor do texto.

header_bg_colorstring

Fundo do cabeçalho.

footer_bg_colorstring

Fundo do rodapé.

link_colorstring

Cor dos links.

link_hover_colorstring

Cor dos links ao passar o mouse.

heading_colorstring

Cor dos títulos.

muted_text_colorstring

Texto secundário.

border_colorstring

Cor das bordas.

button_text_colorstring

Texto dos botões.

font_familystring

Fonte do texto (valor de font-family do CSS).

heading_fontstring

Fonte dos títulos.

border_radiusstring

Raio das bordas (8px).

max_widthstring

Largura máxima do conteúdo (1280px).

custom_cssstring

CSS próprio, aplicado à vitrine.

extended_configobject

Tokens avançados de componentes (mais de 110). Sempre um objeto, {} quando vazio.

created_atstring

Criação (RFC 3339, UTC).

updated_atstring

Última alteração (RFC 3339, UTC).

Criar estilo

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

Adiciona um estilo a um tema

Os campos que você não enviar recebem os valores padrão. O estilo nasce inativo, exceto quando o tema ainda não tem nenhum estilo ativo.

Parâmetros de caminho

iduuidobrigatório

Id do tema.

Corpo da requisição

namestringpadrão: New Style

Nome do estilo.

primary_colorstringpadrão: #2563eb

Cor principal.

secondary_colorstringpadrão: #1e40af

Cor secundária.

accent_colorstringpadrão: #f59e0b

Cor de destaque.

bg_colorstringpadrão: #ffffff

Fundo da página.

text_colorstringpadrão: #1f2937

Cor do texto.

header_bg_colorstringpadrão: #ffffff

Fundo do cabeçalho.

footer_bg_colorstringpadrão: #1f2937

Fundo do rodapé.

link_colorstringpadrão: #2563eb

Cor dos links.

link_hover_colorstringpadrão: #1d4ed8

Links ao passar o mouse.

heading_colorstringpadrão: #111827

Cor dos títulos.

muted_text_colorstringpadrão: #6b7280

Texto secundário.

border_colorstringpadrão: #e5e7eb

Cor das bordas.

button_text_colorstringpadrão: #ffffff

Texto dos botões.

font_familystringpadrão: Inter, sans-serif

Fonte do texto.

heading_fontstringpadrão: Inter, sans-serif

Fonte dos títulos.

border_radiusstringpadrão: 8px

Raio das bordas.

max_widthstringpadrão: 1280px

Largura máxima.

custom_cssstring

CSS próprio. Vazio por padrão.

extended_configobject

Tokens avançados. Vazio vira {}.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/admin/storefront-themes/$THEME_ID/styles" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"Vermelho Natal","primary_color":"#dc2626","footer_bg_color":"#7f1d1d"}'

A resposta 201 é o estilo criado, no formato de "Campos de um estilo".

Alterar estilo

PUT/api/v1/admin/storefront-themes/styles/{styleId}Admin

Sobrescreve os campos de um estilo

Não é parcial. Todos os campos de cor, fonte, geometria, custom_css e extended_config são reescritos: o que você não enviar volta ao valor padrão da tabela acima (e custom_css fica vazio). Só o name é preservado quando vem vazio. Antes de gravar, o estado anterior vai para o histórico.

Parâmetros de caminho

styleIduuidobrigatório

Id do estilo.

Corpo da requisição

namestring

Novo nome. Vazio mantém o atual.

primary_colorstring

Todos os demais campos são os mesmos de "Criar estilo".

A resposta 200 é o estilo atualizado.

Excluir estilo

DELETE/api/v1/admin/storefront-themes/styles/{styleId}Admin

Exclui um estilo inativo

Não permite excluir o estilo ativo nem o último estilo do tema.

Parâmetros de caminho

styleIduuidobrigatório

Id do estilo.

200Estilo excluído

json

{ "message": "deleted" }

Ativar estilo

POST/api/v1/admin/storefront-themes/styles/{styleId}/activateAdmin

Torna o estilo o estilo em uso do seu tema

Desativa o estilo ativo do mesmo tema e ativa este. Se o tema é o ativo, a vitrine muda de cores na hora.

Parâmetros de caminho

styleIduuidobrigatório

Id do estilo.

200Estilo ativado

json

{ "message": "activated" }

Erros

Status	Quando	Corpo
400	Corpo JSON inválido	`{"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	Estilo inexistente (alterar, ativar)	`{"error":"not found","detail":"not found"}`
409	O estilo pertence a um patch aplicado	`{"error":"...","code":"patch_owned","how_to_proceed":"..."}`
500	Excluir o estilo ativo ou o único; `id` que não é UUID; falha interna	`{"error":"failed to delete style","detail":"cannot delete the active or only style"}`

Veja também

API atual/Referência completa/Temas da vitrine

Estilos

Lista, cria, altera, exclui e ativa os estilos (cores, fontes e CSS) de um tema.

Listar estilos

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

Lista os estilos de um tema

Sem paginação. Em temas com muitos estilos a resposta pode ser grande.

Parâmetros de caminho

iduuidobrigatório

Id do tema.

200Estilos retornados

json

{
  "styles": [
    {
      "id": "cd9e5a33-508e-4c69-8e85-85e20f3ad712",
      "theme_id": "a650691c-22f3-4508-9a83-9418c04976a6",
      "name": "Runner",
      "is_active": true,
      "primary_color": "#2563eb",
      "secondary_color": "#2563eb",
      "accent_color": "#f59e0b",
      "bg_color": "#ffffff",
      "text_color": "#1f2937",
      "header_bg_color": "#ffffff",
      "footer_bg_color": "#2563eb",
      "link_color": "#2563eb",
      "link_hover_color": "#1f54c8",
      "heading_color": "#1f2937",
      "muted_text_color": "#797f87",
      "border_color": "#e5e7eb",
      "button_text_color": "#ffffff",
      "font_family": "Inter, sans-serif",
      "heading_font": "Inter, sans-serif",
      "border_radius": "8px",
      "max_width": "1280px",
      "custom_css": "",
      "extended_config": {},
      "created_at": "2026-08-02T04:49:40.245408Z",
      "updated_at": "2026-08-02T04:49:40.263163Z"
    }
  ],
  "total": 1
}

Campos de um estilo

iduuid

Identificador do estilo.

theme_iduuid

Tema dono.

namestring

Nome do estilo.

is_activeboolean

Se é o estilo em uso no tema.

primary_colorstring

Cor principal (botões, destaques). Hexadecimal, por exemplo #2563eb.

secondary_colorstring

Cor secundária.

accent_colorstring

Cor de destaque.

bg_colorstring

Cor de fundo da página.

text_colorstring

Cor do texto.

header_bg_colorstring

Fundo do cabeçalho.

footer_bg_colorstring

Fundo do rodapé.

link_colorstring

Cor dos links.

link_hover_colorstring

Cor dos links ao passar o mouse.

heading_colorstring

Cor dos títulos.

muted_text_colorstring

Texto secundário.

border_colorstring

Cor das bordas.

button_text_colorstring

Texto dos botões.

font_familystring

Fonte do texto (valor de font-family do CSS).

heading_fontstring

Fonte dos títulos.

border_radiusstring

Raio das bordas (8px).

max_widthstring

Largura máxima do conteúdo (1280px).

custom_cssstring

CSS próprio, aplicado à vitrine.

extended_configobject

Tokens avançados de componentes (mais de 110). Sempre um objeto, {} quando vazio.

created_atstring

Criação (RFC 3339, UTC).

updated_atstring

Última alteração (RFC 3339, UTC).

Criar estilo

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

Adiciona um estilo a um tema

Os campos que você não enviar recebem os valores padrão. O estilo nasce inativo, exceto quando o tema ainda não tem nenhum estilo ativo.

Parâmetros de caminho

iduuidobrigatório

Id do tema.

Corpo da requisição

namestringpadrão: New Style

Nome do estilo.

primary_colorstringpadrão: #2563eb

Cor principal.

secondary_colorstringpadrão: #1e40af

Cor secundária.

accent_colorstringpadrão: #f59e0b

Cor de destaque.

bg_colorstringpadrão: #ffffff

Fundo da página.

text_colorstringpadrão: #1f2937

Cor do texto.

header_bg_colorstringpadrão: #ffffff

Fundo do cabeçalho.

footer_bg_colorstringpadrão: #1f2937

Fundo do rodapé.

link_colorstringpadrão: #2563eb

Cor dos links.

link_hover_colorstringpadrão: #1d4ed8

Links ao passar o mouse.

heading_colorstringpadrão: #111827

Cor dos títulos.

muted_text_colorstringpadrão: #6b7280

Texto secundário.

border_colorstringpadrão: #e5e7eb

Cor das bordas.

button_text_colorstringpadrão: #ffffff

Texto dos botões.

font_familystringpadrão: Inter, sans-serif

Fonte do texto.

heading_fontstringpadrão: Inter, sans-serif

Fonte dos títulos.

border_radiusstringpadrão: 8px

Raio das bordas.

max_widthstringpadrão: 1280px

Largura máxima.

custom_cssstring

CSS próprio. Vazio por padrão.

extended_configobject

Tokens avançados. Vazio vira {}.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/admin/storefront-themes/$THEME_ID/styles" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"Vermelho Natal","primary_color":"#dc2626","footer_bg_color":"#7f1d1d"}'

A resposta 201 é o estilo criado, no formato de "Campos de um estilo".

Alterar estilo

PUT/api/v1/admin/storefront-themes/styles/{styleId}Admin

Sobrescreve os campos de um estilo

Parâmetros de caminho

styleIduuidobrigatório

Id do estilo.

Corpo da requisição

namestring

Novo nome. Vazio mantém o atual.

primary_colorstring

Todos os demais campos são os mesmos de "Criar estilo".

A resposta 200 é o estilo atualizado.

Excluir estilo

DELETE/api/v1/admin/storefront-themes/styles/{styleId}Admin

Exclui um estilo inativo

Não permite excluir o estilo ativo nem o último estilo do tema.

Parâmetros de caminho

styleIduuidobrigatório

Id do estilo.

200Estilo excluído

json

{ "message": "deleted" }

Ativar estilo

POST/api/v1/admin/storefront-themes/styles/{styleId}/activateAdmin

Torna o estilo o estilo em uso do seu tema

Desativa o estilo ativo do mesmo tema e ativa este. Se o tema é o ativo, a vitrine muda de cores na hora.

Parâmetros de caminho

styleIduuidobrigatório

Id do estilo.

200Estilo ativado

json

{ "message": "activated" }

Erros

Status	Quando	Corpo
400	Corpo JSON inválido	`{"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	Estilo inexistente (alterar, ativar)	`{"error":"not found","detail":"not found"}`
409	O estilo pertence a um patch aplicado	`{"error":"...","code":"patch_owned","how_to_proceed":"..."}`
500	Excluir o estilo ativo ou o único; `id` que não é UUID; falha interna	`{"error":"failed to delete style","detail":"cannot delete the active or only style"}`