1. Temas
Veploy API
  • Visão geral
  • Autenticação
  • Limites de requisição
  • Imóveis
    • Listar imóveis
    • Consultar imóvel
    • Cadastrar imóvel
    • Alterar imóvel
    • Excluir imóvel
    • Restaurar imóvel
    • Enviar foto do imóvel (Beta)
    • Remover foto do imóvel (Beta)
    • Listar tipos de imóvel
  • Proprietários
    • Listar proprietários
    • Consultar proprietário
    • Cadastrar proprietário
    • Alterar proprietário
    • Excluir proprietário
  • Leads
    • Listar leads
    • Consultar lead
    • Criar lead
    • Alterar responsável
    • Atualizar lead
    • Consultar linha do tempo do lead
  • Visitas
    • Listar visitas
    • Consultar visita
    • Agendar visita
    • Alterar visita
  • Propostas
    • Listar propostas
    • Consultar proposta
    • Registrar proposta
    • Alterar proposta
  • Portais
    • Listar portais
    • Consultar portal
    • Listar imóveis do XML
  • Usuários
    • Listar usuários
    • Consultar usuário
    • Consultar permissões do usuário
    • Convidar usuário
    • Alterar ficha do usuário
    • Desativar usuário
    • Reativar usuário
    • Remover usuário
  • Perfis de acesso
    • Listar perfis de acesso
  • Artigos
    • Listar artigos
    • Criar artigo
    • Consultar artigo
    • Alterar artigo
    • Enviar capa do artigo (Beta)
  • Temas
    • Tema do site
  1. Temas

Tema do site

O tema define a aparência e o conteúdo do site da imobiliária: páginas, seções,
componentes, estilos e scripts. Você edita esses arquivos na sua máquina, no editor que
preferir, e acompanha o resultado numa pré-visualização que só você enxerga. O site no ar só
muda quando você publica.
Há dois caminhos para o mesmo contrato:
a ferramenta de linha de comando @veploy/cli, recomendada para o dia a dia;
os recursos desta pasta, para quem prefere integrar direto.
Esta parte da documentação é independente da API de integração: a credencial é outra, e uma
chave da API não edita o tema.

Antes de começar#

Node.js 18.17 ou mais novo na sua máquina.
Um usuário ativo na imobiliária, com a permissão Editor de interface.
Um plano que inclua a edição do tema. Sem ele, a resposta é 403 com o código
PLAN_FEATURE_REQUIRED.

Instalar e conectar#

O comando mostra um código de 8 caracteres e abre o painel da Veploy no navegador, já com o
código preenchido. Você entra com o seu usuário de sempre, confere que o pedido veio da sua
máquina e aprova, escolhendo a imobiliária. A partir daí a ferramenta tem acesso apenas para
editar o tema daquela imobiliária, em seu nome.
Não existe chave para copiar nem para guardar num arquivo do projeto. A credencial fica em
~/.veploy/credentials.json, é renovada sozinha e para de funcionar assim que o seu acesso à
imobiliária for removido no painel.
Para integrar direto, sem a ferramenta, envie essa mesma credencial no header Authorization:
Publicar exige, além da permissão de edição no seu usuário, que a conexão tenha sido aprovada
com a opção de publicar.

Trazer o tema para a sua máquina#

Numa pasta vazia:
Os arquivos do tema publicado são gravados em src/. Coloque a pasta sob controle de versão:
daí em diante o repositório é a fonte do tema, e a ferramenta envia o que está no seu disco.

O ciclo de trabalho#

A ferramenta compila os estilos e os scripts, envia os arquivos para um rascunho e imprime o
endereço da pré-visualização. Cada arquivo salvo em src/ vai para o rascunho e a página
recarrega sozinha. O site no ar não muda.

Publicar#

Os arquivos do rascunho passam a valer no site, por cima do que está publicado. Nada é
removido do que já estava lá. No primeiro envio de uma imobiliária que ainda usa o tema
padrão, o tema padrão inteiro é copiado antes, para nada faltar.
Publicar exige a permissão de edição no seu usuário e que a conexão desta máquina tenha sido
aprovada com a opção de publicar. Sem isso o rascunho continua sendo enviado normalmente e a
publicação é feita pelo painel.
Ao publicar, altere também o campo version em src/config/config.json: é ele que renova o
endereço dos arquivos no navegador de quem visita o site.

Configurações do tema#

Os valores que a imobiliária escolhe no painel (cores, contatos, imagens das seções) vivem em
src/config/settings_data.json:
{ "base_version": "3f9a1c2b7d4e5f60", "current": { "colors": { "primary": "#003367" } } }
veploy pull traz o arquivo com os valores reais do site. Não altere base_version.
Edite current para experimentar: a pré-visualização já renderiza com os seus valores.
veploy publish leva somente o código. Para levar os valores também, use
veploy publish --with-settings: a ferramenta mostra o que muda, chave a chave, e pede
confirmação. Se alguém alterou algo pelo painel depois do seu pull, ela recusa e pede um
pull novo, sem publicar nada.

O que pode ser enviado#

Apenas o conteúdo de src/, nestas pastas: layout, pages, sections, components,
partials, snippets, config, assets.
RegraValor
Tamanho de cada arquivoaté 5 MB
Tamanho do caminhoaté 200 caracteres
Arquivos no rascunhoaté 1500
Tamanho total do rascunhoaté 100 MB
Extensões aceitas: ploy, json, css, js, mjs, map, imagens (svg, png, jpg,
jpeg, gif, webp, avif, ico), fontes (woff, woff2, ttf, otf, eot), txt,
xml, webmanifest e md.
Arquivos e pastas ocultos não são enviados, e caminhos com . ou .. são recusados. Um item
inválido recusa o lote inteiro, com 400 e a lista do que foi reprovado: nada é gravado.
O arquivo src/config/schemas.json é gerado pela Veploy a partir dos blocos {% schema %}
das seções. Não o edite à mão; a ferramenta não o envia. Erros de {% schema %} aparecem no
terminal, não impedem o rascunho e impedem a publicação.

Limites de requisição#

As rotas de tema têm limites próprios, por minuto:
RotaRequisições por minuto
Leitura de arquivo300
Estado, manifesto, configurações e histórico120
Envio de lote (PATCH /v1/themes/draft/files)60
Descarte do rascunho30
Publicação10

Respostas de erro#

StatusQuando acontece
401Conexão inválida, expirada ou encerrada. Rode veploy login de novo.
403Chave da API no lugar da conexão; usuário sem a permissão de edição; plano sem a edição de tema; ou conexão sem autorização para publicar.
400Arquivo com caminho, extensão, tamanho ou codificação inválida.
409Rascunho vazio, ou configurações alteradas no painel depois do seu pull.
413O rascunho ultrapassaria o limite de arquivos ou de bytes.
422Erro de {% schema %} nos templates.

Comandos#

ComandoO que faz
veploy login [--name=X] [--no-open]Conecta esta máquina a uma imobiliária.
veploy logoutDesconecta esta máquina.
veploy whoamiMostra a conexão em uso.
veploy dev [--open]Compila, sincroniza e acompanha as alterações com pré-visualização.
veploy pushCompila e sincroniza uma vez.
veploy pull [--live] [--yes]Traz o rascunho, ou o tema no ar, para a pasta local.
veploy statusEstado do rascunho, do tema publicado e endereço da pré-visualização.
veploy publish [--yes] [--with-settings]Coloca o rascunho no ar.
veploy discard [--yes]Apaga o rascunho.
Fora login, logout e whoami, os comandos rodam de dentro da pasta do tema.
Modificado em 2026-09-16 19:04:30
Página anterior
Enviar capa do artigo (Beta)
Built with