API atual/Referência completa/Marca e configuração do tema

Ler e alterar a configuração

Lê e altera a configuração visual global da loja e consulta as variáveis CSS que ela gera.

Três rotas sobre a configuração global: ler tudo, alterar campos e ver o CSS gerado. Leia antes a visão geral para entender como o estilo ativo do tema se sobrepõe a estas cores. Exigem o privilégio manage_theme.

Ler a configuração

GET/api/v1/admin/themeAdmin

Lê a configuração visual global da loja

Devolve a configuração tal como está gravada, sem a sobreposição do estilo ativo (essa mescla só acontece na rota pública da vitrine).

Exemplo de requisição

bash

curl "$BASE_URL/api/v1/admin/theme" \
  -H "Authorization: Bearer $TOKEN"

200Configuração retornada

json

{
  "id": "20299fa2-f761-434f-aa54-811e242f65a3",
  "logo_url": "/uploads/dfe2555e-bfd0-41a8-9fa1-9586999f3798/theme/logo/logo.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",
  "pwa_enabled": true,
  "pwa_short_name": "",
  "updated_at": "2026-09-06T05:23:00.918969Z"
}

Campos da resposta

iduuid

Identificador da configuração (única por loja).

logo_urlstring

Logo do cabeçalho. Caminho /uploads/... ou URL.

favicon_urlstring

Ícone da aba do navegador. Vazio quando não definido.

store_namestring

Nome da loja.

primary_colorstring

Cor principal. Todas as cores seguem o formato hexadecimal.

secondary_colorstring

Cor secundária.

accent_colorstring

Cor de destaque.

bg_colorstring

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

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.

heading_fontstring

Fonte dos títulos.

border_radiusstring

Raio das bordas (8px).

max_widthstring

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

custom_cssstring

CSS extra aplicado à vitrine.

custom_head_htmlstring

HTML inserido no head de todas as páginas (por exemplo, tags de analytics).

font_size_basestring

Tamanho base da fonte (16px).

font_size_lgstring

Fonte grande.

font_size_smstring

Fonte pequena.

line_height_basestring

Altura de linha (1.6).

heading_weightstring

Peso da fonte dos títulos (700, 800).

header_layoutstring

leftcentered

Alinhamento do cabeçalho.

footer_columnsinteger

234

Colunas do rodapé.

sidebar_positionstring

leftrightnone

Posição da barra lateral nas listagens.

extended_configobject

Tokens avançados de componentes. Ausente quando vazio.

pwa_enabledboolean

Se o app instalável (PWA) está ligado.

pwa_short_namestring

Nome curto sob o ícone do app, no máximo 12 caracteres.

updated_atstring

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

Alterar a configuração

PUT/api/v1/admin/themeAdmin

Altera campos da configuração visual global

Alteração parcial: só os campos enviados mudam. Use "" para limpar um texto. Valores de cor precisam ser hexadecimais (#rgb, #rrggbb ou #rrggbbaa) ou transparent, inherit, currentColor, ou vazio. header_layout, footer_columns e sidebar_position não são checados pelo servidor: envie só os valores documentados. A resposta é a configuração inteira, como no GET.

Corpo da requisição

logo_urlstring

Logo. Só imagens: caminho /uploads/..., URL http(s) ou data: de imagem. Outro esquema (javascript:) é recusado.

favicon_urlstring

Favicon, com a mesma regra do logo.

store_namestring

Nome da loja.

primary_colorstring

Cor principal.

secondary_colorstring

Cor secundária.

accent_colorstring

Cor de destaque.

bg_colorstring

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

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.

heading_fontstring

Fonte dos títulos.

border_radiusstring

Raio das bordas.

max_widthstring

Largura máxima.

custom_cssstring

CSS extra.

custom_head_htmlstring

HTML do head.

font_size_basestring

Tamanho base da fonte.

font_size_lgstring

Fonte grande.

font_size_smstring

Fonte pequena.

line_height_basestring

Altura de linha.

heading_weightstring

Peso dos títulos.

header_layoutstring

leftcentered

Alinhamento do cabeçalho.

footer_columnsinteger

234

Colunas do rodapé.

sidebar_positionstring

leftrightnone

Posição da barra lateral.

extended_configobject

Tokens avançados. Precisa ser JSON válido; {} ou ausente não altera.

pwa_enabledboolean

Liga ou desliga o PWA.

pwa_short_namestring

Nome curto do app. Acima de 12 caracteres é cortado.

Exemplo de requisição

bash

curl -X PUT "$BASE_URL/api/v1/admin/theme" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"store_name":"Loja do João","primary_color":"#dc2626"}'

Variáveis CSS geradas

GET/api/v1/admin/theme/cssAdmin

Mostra as variáveis CSS geradas pela configuração global

Devolve o mapa de variáveis CSS e o bloco :root pronto, calculados apenas da configuração global (e dos tokens do extended_config que têm variável própria), sem o estilo ativo. Serve para pré-visualizar o que esta configuração produz.

200Variáveis geradas

json

{
  "variables": {
    "--color-primary": "#2563eb",
    "--color-accent": "#f59e0b",
    "--color-bg": "#ffffff",
    "--font-family": "Inter, sans-serif",
    "--border-radius": "8px",
    "--max-width": "1280px"
  },
  "css": ":root {\n  --color-primary: #2563eb;\n  --color-accent: #f59e0b;\n  --color-bg: #ffffff;\n  --font-family: Inter, sans-serif;\n  --border-radius: 8px;\n  --max-width: 1280px;\n}"
}

Campos da resposta

variablesobject

Mapa nome da variável para valor. Hoje inclui cores (--color-*), fontes (--font-*), --border-radius, --max-width, --line-height-base e --heading-weight (22 variáveis na loja de teste). O exemplo mostra só algumas.

cssstring

Bloco :root { ... } pronto para inserir numa página.

Erros

Status	Quando	Corpo
400	Corpo JSON inválido; cor fora do formato; `logo_url` ou `favicon_url` inválido; nenhum campo enviado	`{"error":"invalid color","detail":"color must be a valid hex value like #1a2b3c (primary_color=\"red\")"}`, `{"error":"invalid logo_url","detail":"invalid_image_url: unsupported scheme \"javascript\""}` ou `{"error":"no fields to update"}`
401	Sem token ou token expirado	`{"error":"missing authorization header"}`
403	Sem o privilégio `manage_theme`	`{"error":"insufficient privileges","required":"manage_theme"}`
500	`extended_config` que não é JSON válido; campo protegido por um patch aplicado; falha interna	`{"error":"failed to update theme","detail":"..."}`

Veja também

Ler e alterar a configuração

Lê e altera a configuração visual global da loja e consulta as variáveis CSS que ela gera.

Ler a configuração

GET/api/v1/admin/themeAdmin

Lê a configuração visual global da loja

Devolve a configuração tal como está gravada, sem a sobreposição do estilo ativo (essa mescla só acontece na rota pública da vitrine).

Exemplo de requisição

bash

curl "$BASE_URL/api/v1/admin/theme" \
  -H "Authorization: Bearer $TOKEN"

200Configuração retornada

json

{
  "id": "20299fa2-f761-434f-aa54-811e242f65a3",
  "logo_url": "/uploads/dfe2555e-bfd0-41a8-9fa1-9586999f3798/theme/logo/logo.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",
  "pwa_enabled": true,
  "pwa_short_name": "",
  "updated_at": "2026-09-06T05:23:00.918969Z"
}

Campos da resposta

iduuid

Identificador da configuração (única por loja).

logo_urlstring

Logo do cabeçalho. Caminho /uploads/... ou URL.

favicon_urlstring

Ícone da aba do navegador. Vazio quando não definido.

store_namestring

Nome da loja.

primary_colorstring

Cor principal. Todas as cores seguem o formato hexadecimal.

secondary_colorstring

Cor secundária.

accent_colorstring

Cor de destaque.

bg_colorstring

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

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.

heading_fontstring

Fonte dos títulos.

border_radiusstring

Raio das bordas (8px).

max_widthstring

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

custom_cssstring

CSS extra aplicado à vitrine.

custom_head_htmlstring

HTML inserido no head de todas as páginas (por exemplo, tags de analytics).

font_size_basestring

Tamanho base da fonte (16px).

font_size_lgstring

Fonte grande.

font_size_smstring

Fonte pequena.

line_height_basestring

Altura de linha (1.6).

heading_weightstring

Peso da fonte dos títulos (700, 800).

header_layoutstring

leftcentered

Alinhamento do cabeçalho.

footer_columnsinteger

234

Colunas do rodapé.

sidebar_positionstring

leftrightnone

Posição da barra lateral nas listagens.

extended_configobject

Tokens avançados de componentes. Ausente quando vazio.

pwa_enabledboolean

Se o app instalável (PWA) está ligado.

pwa_short_namestring

Nome curto sob o ícone do app, no máximo 12 caracteres.

updated_atstring

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

Alterar a configuração

PUT/api/v1/admin/themeAdmin

Altera campos da configuração visual global

Corpo da requisição

logo_urlstring

Logo. Só imagens: caminho /uploads/..., URL http(s) ou data: de imagem. Outro esquema (javascript:) é recusado.

favicon_urlstring

Favicon, com a mesma regra do logo.

store_namestring

Nome da loja.

primary_colorstring

Cor principal.

secondary_colorstring

Cor secundária.

accent_colorstring

Cor de destaque.

bg_colorstring

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

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.

heading_fontstring

Fonte dos títulos.

border_radiusstring

Raio das bordas.

max_widthstring

Largura máxima.

custom_cssstring

CSS extra.

custom_head_htmlstring

HTML do head.

font_size_basestring

Tamanho base da fonte.

font_size_lgstring

Fonte grande.

font_size_smstring

Fonte pequena.

line_height_basestring

Altura de linha.

heading_weightstring

Peso dos títulos.

header_layoutstring

leftcentered

Alinhamento do cabeçalho.

footer_columnsinteger

234

Colunas do rodapé.

sidebar_positionstring

leftrightnone

Posição da barra lateral.

extended_configobject

Tokens avançados. Precisa ser JSON válido; {} ou ausente não altera.

pwa_enabledboolean

Liga ou desliga o PWA.

pwa_short_namestring

Nome curto do app. Acima de 12 caracteres é cortado.

Exemplo de requisição

bash

curl -X PUT "$BASE_URL/api/v1/admin/theme" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"store_name":"Loja do João","primary_color":"#dc2626"}'

Variáveis CSS geradas

GET/api/v1/admin/theme/cssAdmin

Mostra as variáveis CSS geradas pela configuração global

200Variáveis geradas

json

{
  "variables": {
    "--color-primary": "#2563eb",
    "--color-accent": "#f59e0b",
    "--color-bg": "#ffffff",
    "--font-family": "Inter, sans-serif",
    "--border-radius": "8px",
    "--max-width": "1280px"
  },
  "css": ":root {\n  --color-primary: #2563eb;\n  --color-accent: #f59e0b;\n  --color-bg: #ffffff;\n  --font-family: Inter, sans-serif;\n  --border-radius: 8px;\n  --max-width: 1280px;\n}"
}

Campos da resposta

variablesobject

cssstring

Bloco :root { ... } pronto para inserir numa página.

Erros

Status	Quando	Corpo
400	Corpo JSON inválido; cor fora do formato; `logo_url` ou `favicon_url` inválido; nenhum campo enviado	`{"error":"invalid color","detail":"color must be a valid hex value like #1a2b3c (primary_color=\"red\")"}`, `{"error":"invalid logo_url","detail":"invalid_image_url: unsupported scheme \"javascript\""}` ou `{"error":"no fields to update"}`
401	Sem token ou token expirado	`{"error":"missing authorization header"}`
403	Sem o privilégio `manage_theme`	`{"error":"insufficient privileges","required":"manage_theme"}`
500	`extended_config` que não é JSON válido; campo protegido por um patch aplicado; falha interna	`{"error":"failed to update theme","detail":"..."}`