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

Tema, CSS e ícone do app

Lê as cores, fontes e medidas da loja, as mesmas como variáveis de CSS prontas, e o ícone PNG usado quando a loja é instalada como aplicativo.

O tema é a identidade visual da loja: paleta de cores, fontes, arredondamento, largura máxima, logotipo. Estas três rotas entregam esses dados de três jeitos: como objeto completo (theme), como variáveis de CSS prontas (theme/css) e como imagem do ícone do aplicativo (pwa/icon/{size}). As três são públicas e não exigem login.

Ler o tema

GET/api/v1/storefront/themePública

Consulta o tema da vitrine

Devolve o tema atual. Quando a loja tem um tema ativo, as cores, fontes, arredondamento, largura e CSS próprio vêm do estilo ativo daquele tema (e sobrepõem os valores gerais), e active_theme_slug identifica o tema. Resposta sem cache.

Exemplo de requisição

bash
curl "$BASE_URL/api/v1/storefront/theme"

Resposta

200Tema da loja
json
{
  "id": "20299fa2-f761-434f-aa54-811e242f65a3",
  "logo_url": "/uploads/dfe2555e/theme/logo/8034a261_logo-v1.png",
  "favicon_url": "",
  "store_name": "Loja de Demonstração Venddor",
  "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": "",
  "custom_head_html": "",
  "font_size_base": "16px",
  "font_size_lg": "20px",
  "font_size_sm": "14px",
  "line_height_base": "1.6",
  "heading_weight": "800",
  "header_layout": "left",
  "footer_columns": 4,
  "sidebar_position": "left",
  "extended_config": {},
  "pwa_enabled": true,
  "pwa_short_name": "",
  "active_theme_slug": "default",
  "updated_at": "2026-09-06T05:23:00.918969Z"
}

Campos da resposta

iduuid
Id do registro de tema.
logo_urlstring
Caminho ou endereço do logotipo. Caminhos começam com /uploads/ e são relativos ao domínio da loja.
favicon_urlstring
Caminho do favicon. Vazio quando não há.
store_namestring
Nome da loja.
primary_colorstring
Cor principal, hexadecimal (#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
Cor de texto secundário.
border_colorstring
Cor de bordas.
button_text_colorstring
Cor do texto dos botões.
font_familystring
Fonte do texto (valor de font-family).
heading_fontstring
Fonte dos títulos.
border_radiusstring
Arredondamento de cantos (8px).
max_widthstring
Largura máxima do conteúdo (1280px).
font_size_basestring
Tamanho base da fonte.
font_size_lgstring
Tamanho de fonte grande.
font_size_smstring
Tamanho de fonte pequeno.
line_height_basestring
Altura de linha base.
heading_weightstring
Peso da fonte dos títulos.
custom_cssstring
CSS próprio que o lojista acrescentou. Injete em uma tag style.
custom_head_htmlstring
HTML que o lojista pediu para entrar no head da página.
header_layoutstring
leftcentered
Alinhamento do logotipo no cabeçalho.
footer_columnsinteger
234
Colunas do rodapé.
sidebar_positionstring
leftrightnone
Lado da barra lateral nas listagens.
extended_configobject
Parâmetros adicionais de design (mais de cem), no formato definido pelo tema ativo. Trate como opaco.
pwa_enabledboolean
Se o manifesto de aplicativo instalável está ligado para este tema. O interruptor oficial do aplicativo está em Aparência.
pwa_short_namestring
Nome curto do aplicativo instalado.
active_theme_slugstring
Slug do tema ativo. Ausente quando não há tema ativo.
updated_atstring
Última alteração, RFC 3339.

Erros

StatusQuandoCorpo
404Loja não identificada{"error":"tenant not found","message":"could not resolve storefront from request"}
500Falha ao ler{"error":"failed to get theme","detail":"..."}
pwa_enabled aqui e em Aparência podem divergir

Na instalação de teste, theme.pwa_enabled veio true enquanto settings/appearance.pwa_enabled veio false. O segundo é o interruptor que o front-end deve obedecer para registrar ou remover o service worker. Trate o do tema só como dado do manifesto.

Ler as variáveis de CSS

GET/api/v1/storefront/theme/cssPública

Read the theme as CSS custom properties

Devolve o mesmo tema em forma de variáveis de CSS: um mapa pronto (variables) e um bloco de texto (css) com :root { ... } para colar numa tag style. É o jeito mais curto de aplicar a paleta, sem você montar os nomes.

Exemplo de requisição

bash
curl "$BASE_URL/api/v1/storefront/theme/css"

Resposta

200Variáveis de CSS
json
{
  "variables": {
    "--border-radius": "8px",
    "--color-accent": "#f59e0b",
    "--color-bg": "#ffffff",
    "--color-border": "#e5e7eb",
    "--color-button-text": "#ffffff",
    "--color-footer-bg": "#2563eb",
    "--color-header-bg": "#ffffff",
    "--color-heading": "#1f2937",
    "--color-link": "#2563eb",
    "--color-link-hover": "#1f54c8",
    "--color-muted-text": "#797f87",
    "--color-primary": "#2563eb",
    "--color-secondary": "#2563eb",
    "--color-text": "#1f2937",
    "--font-family": "Inter, sans-serif",
    "--font-heading": "Inter, sans-serif",
    "--font-size-base": "16px",
    "--font-size-lg": "20px",
    "--font-size-sm": "14px",
    "--heading-weight": "800",
    "--line-height-base": "1.6",
    "--max-width": "1280px"
  },
  "css": ":root {\n  --color-link: #2563eb;\n  --color-primary: #2563eb;\n  ...\n}"
}

Campos da resposta

variablesobject
Mapa nome da variável para valor. Os nomes começam com --.
cssstring
Bloco CSS pronto com todas as variáveis dentro de :root. O exemplo acima está abreviado.

Erros

StatusQuandoCorpo
500Falha ao calcular{"error":"failed to compute CSS vars","detail":"..."}
Este CSS vem do tema geral

theme/css é calculada a partir da configuração geral de tema da loja, enquanto GET /theme ainda aplica por cima o estilo do tema ativo. Na instalação de teste os valores coincidiram. Se na sua loja as cores divergirem, use as de GET /theme como fonte de verdade.

Ícone do aplicativo

GET/api/v1/storefront/pwa/icon/{size}Pública

Consulta o ícone do app em PNG

Gera o ícone usado quando a loja é instalada como aplicativo (PWA) ou fixada na tela inicial: o logotipo da loja centralizado sobre a cor de fundo do tema, com uma margem de segurança de 12% para ícones arredondados. Se a loja não tem logotipo utilizável, devolve um ícone padrão. A resposta é uma imagem PNG, não JSON, com cache público de 5 minutos.

Parâmetros de caminho

sizeintegerobrigatório
192512
Lado do quadrado em pixels. Só 192 e 512 existem; qualquer outro valor responde 404.

Exemplo de requisição

bash
curl "$BASE_URL/api/v1/storefront/pwa/icon/192" -o icon-192.png

Resposta

200Imagem PNG
http
HTTP/1.1 200 OK
Content-Type: image/png
Cache-Control: public, max-age=300

<bytes do PNG>

Erros

StatusQuandoCorpo
404size diferente de 192 ou 512404 page not found (texto simples)

Veja também

  • Aparência, filtros e busca
  • Layout da página
  • Visão geral de tema e layout
Anterior
Tema, layouts e navegação
Próxima
Layouts de página
Nesta página
  • Ler o tema
  • Exemplo de requisição
  • Resposta
  • Erros
  • Ler as variáveis de CSS
  • Exemplo de requisição
  • Resposta
  • Erros
  • Ícone do aplicativo
  • Exemplo de requisição
  • Resposta
  • Erros
  • Veja também