VenddorDocumentação API
API atualAPI legada
Guia rápidoReferência completa
Carregando índice…
API atual/Referência completa/Vitrine: layout, menus e temas

Galeria de temas

Lista os temas prontos da plataforma, lê e pré-visualiza um tema e instala um tema na loja, trocando cores e fontes.

A galeria de temas reúne conjuntos prontos de cores, fontes e medidas ("Azul Corporativo", "Minimalista", "Laranja Energia"...). Instalar um tema aplica esse conjunto à loja inteira numa chamada, sem editar cor por cor. A loja também pode ajustar o tema à mão (rotas /theme), e cada instalação guarda o tema anterior no histórico, de onde dá para restaurar.

Todas exigem o privilégio manage_theme.

Listar os temas

GET/api/v1/admin/themes/marketplaceAdmin

Listar os temas da galeria

Devolve os temas ativos, opcionalmente de uma categoria.

Parâmetros de consulta

categorystring
Filtra por categoria (business, modern, colorful...). Uma categoria sem temas devolve lista vazia.
bash
curl "$BASE_URL/api/v1/admin/themes/marketplace?category=business" \
  -H "Authorization: Bearer $TOKEN"
200Temas
json
{
  "templates": [
    {
      "id": "1ba884c2-fe61-4876-b3e2-6a8676b969c8",
      "name": "Azul Corporativo",
      "slug": "azul-corporativo",
      "description": "Azul profissional com tipografia limpa. Perfeito para B2B, corporativo e serviços empresariais.",
      "category": "business",
      "thumbnail_url": "",
      "preview_url": "",
      "css_variables": {
        "primary_color": "#1e40af",
        "secondary_color": "#1e3a8a",
        "accent_color": "#0891b2",
        "bg_color": "#ffffff",
        "text_color": "#1e293b",
        "border_radius": "6px",
        "max_width": "1280px",
        "header_bg_color": "#1e3a8a",
        "footer_bg_color": "#0f172a"
      },
      "font_family_heading": "Inter, sans-serif",
      "font_family_body": "Inter, sans-serif",
      "is_premium": false,
      "is_active": true,
      "author": "Venddor",
      "installs": 2,
      "created_at": "2026-04-29T09:19:50.522393Z"
    }
  ],
  "total": 1
}

Campos da resposta

templates[].iduuid
Id do tema.
templates[].namestring
Nome.
templates[].slugstring
Identificador curto, usado nas rotas de leitura, pré-visualização e instalação.
templates[].descriptionstring
Descrição.
templates[].categorystring
Categoria (business, modern, colorful...).
templates[].thumbnail_urlstring
Miniatura. Pode ser vazio.
templates[].preview_urlstring
Endereço de uma pré-visualização externa. Pode ser vazio.
templates[].css_variablesobject
Mapa de variáveis visuais (cores, raio de borda, largura, tamanhos). Valores são strings.
templates[].font_family_headingstring
Fonte dos títulos.
templates[].font_family_bodystring
Fonte do texto.
templates[].is_premiumboolean
Se o tema é premium.
templates[].is_activeboolean
Se o tema está disponível na galeria.
templates[].authorstring
Autor.
templates[].installsinteger
Quantas instalações o tema já teve.
templates[].created_atstring
RFC 3339, UTC.
totalinteger
Quantidade de temas devolvidos.

Ler e pré-visualizar um tema

GET/api/v1/admin/themes/marketplace/{slug}Admin

Ler um tema pelo slug

Devolve um tema, no formato de cada item da lista.

Parâmetros de caminho

slugstringobrigatório
Slug do tema, por exemplo azul-corporativo.
GET/api/v1/admin/themes/marketplace/{slug}/previewAdmin

Pré-visualizar um tema

Hoje devolve os mesmos dados da leitura do tema (variáveis e fontes). Serve para o painel aplicar as variáveis numa pré-visualização local antes de instalar. Não muda nada na loja.

Parâmetros de caminho

slugstringobrigatório
Slug do tema.
bash
curl "$BASE_URL/api/v1/admin/themes/marketplace/azul-corporativo/preview" \
  -H "Authorization: Bearer $TOKEN"

Instalar um tema

POST/api/v1/admin/themes/marketplace/{slug}/installAdmin

Aplicar um tema da galeria à loja

Troca na hora o visual da loja: cores, fontes, bordas e medidas passam a ser as do tema. Antes de aplicar, a plataforma guarda o tema atual no histórico (para restaurar), remove as cores personalizadas que ficariam por cima e contabiliza uma instalação. O tema instalado também vira o tema ativo da vitrine (é criado com o nome do modelo se ainda não existir). Devolve a configuração de tema resultante. Sem corpo.

Parâmetros de caminho

slugstringobrigatório
Slug do tema.
bash
curl -X POST "$BASE_URL/api/v1/admin/themes/marketplace/azul-corporativo/install" \
  -H "Authorization: Bearer $TOKEN"
200Tema instalado
json
{
  "id": "20299fa2-f761-434f-aa54-811e242f65a3",
  "store_name": "Loja Exemplo",
  "primary_color": "#1e40af",
  "secondary_color": "#1e3a8a",
  "accent_color": "#0891b2",
  "bg_color": "#ffffff",
  "text_color": "#1e293b",
  "header_bg_color": "#1e3a8a",
  "footer_bg_color": "#0f172a",
  "font_family": "Inter, sans-serif",
  "heading_font": "Inter, sans-serif",
  "border_radius": "6px",
  "max_width": "1280px",
  "footer_columns": 4,
  "updated_at": "2026-10-11T22:00:00Z"
}

Campos da resposta

iduuid
Id da configuração de tema da loja.
store_namestring
Nome exibido da loja.
primary_colorstring
Cor principal, hexadecimal.
secondary_colorstring
Cor secundária.
accent_colorstring
Cor de destaque.
bg_colorstring
Cor de fundo.
text_colorstring
Cor do texto.
header_bg_colorstring
Fundo do cabeçalho.
footer_bg_colorstring
Fundo do rodapé.
font_familystring
Fonte do texto.
heading_fontstring
Fonte dos títulos.
border_radiusstring
Raio das bordas, com unidade.
max_widthstring
Largura máxima do conteúdo, com unidade.
footer_columnsinteger
Colunas do rodapé.
updated_atstring
RFC 3339, UTC. A configuração traz ainda os demais campos de tema (tamanhos de fonte, links, favicon, CSS próprio).

Erros

StatusQuandoCorpo de exemplo
401Sem token ou token expirado.{"error":"invalid or expired token"}
403Sem manage_theme.{"error":"insufficient privileges","required":"manage_theme"}
404Slug que não existe.{"error":"theme template not found","detail":"theme template not found: nope"}
500Falha ao aplicar.{"error":"failed to install theme","detail":"..."}
A instalação vale para a loja inteira e é imediata

Não existe rascunho: a vitrine passa a usar as cores novas na próxima visita. Pré-visualize antes e saiba que o tema anterior pode ser recuperado pelo histórico de temas (GET /api/v1/admin/theme/history).

Cores personalizadas são removidas

Para o tema valer de verdade, a instalação limpa as cores que você tinha personalizado à mão. Só as cores do tema instalado ficam.

Veja também

  • Preferências de exibição
  • Aparência da vitrine
Anterior
Menus de navegação
Próxima
Preferências de exibição
Nesta página
  • Listar os temas
  • Ler e pré-visualizar um tema
  • Instalar um tema
  • Erros
  • Veja também