Temas da vitrine

Um tema da vitrine é um pacote de aparência: ele possui os seus próprios layouts (a estrutura das páginas) e um ou mais estilos (cores, fontes, bordas e CSS próprio). A loja tem vários temas cadastrados, mas exatamente um está ativo e, dentro dele, exatamente um estilo está ativo. É o estilo ativo que define o visual que o cliente vê. Esta seção documenta como criar, copiar, ativar, exportar e importar temas e como gerenciar seus estilos. Todas as rotas exigem token de administrador com o privilégio manage_theme.

Como funciona

1. Crie ou copie um tema
   POST /storefront-themes cria um tema vazio com um estilo Default; POST /storefront-themes/{id}/duplicate copia um tema inteiro (estilos e layouts); POST /storefront-themes/import cria a partir de um arquivo exportado.
2. Ajuste os estilos
   Crie estilos novos e altere as cores e fontes de cada um com as rotas de estilos. Um tema pode ter vários estilos (variações de cor), mas só um ativo.
3. Ative
   POST /storefront-themes/{id}/activate publica o tema. Se ele ainda não tiver layout padrão, o layout editado mais recentemente passa a ser o padrão.

Conceitos-chave

Tema, estilo e layout

Tokens de um estilo

Cores (todas em texto, normalmente hexadecimal como #2563eb): primary_color, secondary_color, accent_color, bg_color, text_color, header_bg_color, footer_bg_color, link_color, link_hover_color, heading_color, muted_text_color, border_color, button_text_color. Tipografia e geometria: font_family, heading_font, border_radius, max_width. Extras: custom_css (CSS livre) e extended_config (objeto JSON com mais de 110 tokens de componentes). Campo não enviado volta ao padrão: #2563eb, #1e40af, #f59e0b, #ffffff, #1f2937 e assim por diante, fonte Inter, sans-serif, raio 8px, largura 1280px.

Slug

O slug é gerado do nome (minúsculas, hífens no lugar de espaços e símbolos). A vitrine o usa para escolher componentes específicos de um tema. Renomear um tema não muda o slug.

Proteção por patches

Alguns estilos podem pertencer a um patch aplicado (uma alteração controlada, aplicada pela equipe da plataforma). Alterar o CSS de um desses estilos retorna 409 com code: "patch_owned".

Endpoints

Erros comuns

• Tentar excluir o tema ativo. Retorna 409. Ative outro tema antes.
• Enviar só uma cor no PUT do estilo. As outras voltam ao padrão. Leia o estilo, altere o campo e reenvie o objeto completo.
• Excluir o estilo ativo ou o único estilo do tema. Retorna 500 cannot delete the active or only style. Ative outro estilo primeiro.
• Mandar id que não é UUID. Algumas rotas respondem 500 com a descrição do problema em detail, em português, em vez de 400.
• Esperar que a ativação do tema mude a marca. O logo, o nome da loja e o favicon vêm da configuração de marca, não do tema.
• Esperar contagem de estilos em todo lugar. style_count só vem preenchido na listagem; na consulta de um tema use o array styles.

Próximos passos