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

Marca e configuração do tema

A configuração visual global da loja (logo, nome, cores base, tipografia), presets, histórico e como ela se relaciona com os temas da vitrine.

Toda loja tem uma configuração visual global: o logo, o favicon, o nome da loja, as cores base, a tipografia, o CSS extra e as opções do PWA (o app instalável da loja). Esta seção documenta as rotas /api/v1/admin/theme, que leem e gravam essa configuração, aplicam presets prontos, mantêm um histórico e exportam ou importam tudo. Todas exigem token de administrador com o privilégio manage_theme.

Cores aqui não são, sozinhas, as cores da vitrine

A vitrine monta o visual assim: pega esta configuração global e sobrepõe as cores, fontes e CSS do estilo ativo do tema ativo (veja Temas da vitrine). Por isso PUT /admin/theme com uma cor nova só muda a vitrine se a loja não tiver um estilo ativo. Já o logo, o favicon, o nome da loja e o PWA vêm sempre desta configuração. Aplicar um preset ou restaurar do histórico também grava o resultado no estilo ativo, e por isso muda a vitrine; o PUT simples, não.

Pontos-chave
  • Existe uma única configuração por loja: não há id para escolher, as rotas atuam sobre ela.
  • O PUT é parcial: só os campos enviados mudam. Cores são validadas como hexadecimal.
  • Preset, restauração e importação gravam o conjunto completo de campos, inclusive logo, favicon e nome da loja (veja os avisos de cada página).
  • Antes de aplicar um preset, restaurar ou importar, a plataforma guarda a configuração atual no histórico.
  • logo_url e favicon_url só aceitam imagens: caminho /uploads/..., URL http(s) ou data: de imagem.

Como funciona

Configuração global→Estilo ativo do tema→Vitrine

A vitrine lê GET /api/v1/storefront/theme, que devolve esta configuração já mesclada com o estilo ativo do tema ativo, e transforma o resultado em variáveis CSS. Para ver o CSS que a configuração global gera sozinha, use CSS da configuração.

Conceitos-chave

Campos da configuração

GrupoCampos
Marcalogo_url, favicon_url, store_name
Coresprimary_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 geometriafont_family, heading_font, border_radius, max_width, font_size_base, font_size_lg, font_size_sm, line_height_base, heading_weight
Estruturaheader_layout (left ou centered), footer_columns (2, 3 ou 4), sidebar_position (left, right ou none)
Códigocustom_css, custom_head_html, extended_config (objeto JSON de tokens de componentes)
PWApwa_enabled, pwa_short_name

Presets

A plataforma traz 4 presets prontos (modern, classic, minimal, bold). Cada um é uma configuração completa de cores e tipografia, aplicada com um clique.

Histórico

Cada preset aplicado, restauração ou importação grava antes um retrato da configuração atual, com uma nota. Dá para voltar a qualquer um desses pontos.

Endpoints

MétodoCaminhoPara que serveAuth
GET/api/v1/admin/themeLer a configuraçãoadmin
PUT/api/v1/admin/themeAlterar a configuraçãoadmin
GET/api/v1/admin/theme/cssVariáveis CSS geradasadmin
GET/api/v1/admin/theme/presetsListar presetsadmin
POST/api/v1/admin/theme/presets/{id}/applyAplicar presetadmin
GET/api/v1/admin/theme/historyListar históricoadmin
POST/api/v1/admin/theme/history/{id}/restoreRestaurar do históricoadmin
GET/api/v1/admin/theme/exportExportaradmin
POST/api/v1/admin/theme/importImportaradmin

Erros comuns

  • Mudar a cor com PUT /theme e não ver efeito. Se a loja tem estilo ativo, ele sobrepõe a cor. Altere o estilo (rotas de estilos) ou aplique um preset.
  • Enviar cor em formato CSS não hexadecimal (red, rgb(...)). Retorna 400. Use #rgb, #rrggbb ou #rrggbbaa; também são aceitos transparent, inherit e currentColor.
  • PUT vazio. Retorna 400 no fields to update.
  • Aplicar um preset e perder logo e nome. O preset reescreve todos os campos; confira logo_url, favicon_url e store_name depois.
  • Importar um arquivo sem version. Retorna 400.
  • Passar um id de histórico ou de preset inexistente. Retorna 500, não 404.

Próximos passos

Ler e alterar
Configuração global e variáveis CSS.
Presets e histórico
Aplicar um visual pronto e voltar atrás.
Temas da vitrine
Estilos ativos que sobrepõem estas cores.
Anterior
Cancelar alerta de preço
Próxima
Ler e alterar a configuração
Nesta página
  • Como funciona
  • Conceitos-chave
  • Campos da configuração
  • Presets
  • Histórico
  • Endpoints
  • Erros comuns
  • Próximos passos