Páginas e sites feitos de arquivos, o lote de operações de edição, as configurações, a publicação, os domínios e os formulários.
Uma página da Vozko é um projeto de arquivos (HTML ou React) que o servidor compila, valida e publica num endereço próprio. As rotas ficam nos grupos de páginas da Referência da API e exigem as permissões do recurso sites (os domínios usam site_domains e os envios de formulário, site_submissions).
Projeto
| Rota | Para que serve |
|---|---|
GET /sites/starters | Os modelos prontos por tecnologia. |
POST /sites/projects | Cria uma página a partir de um modelo. |
GET /sites/projects | Lista as páginas, filtradas por status e por nome (q). |
GET /sites/projects/{id} | A página com todos os arquivos, as configurações e a versão. |
PATCH /sites/projects/{id} | Renomeia, troca o endereço (slug) ou o sistema de design, arquiva ou desarquiva. |
POST /sites/projects/{id}/duplicate | Cria uma cópia em rascunho, sem domínios nem publicações. |
DELETE /sites/projects/{id} | Exclui uma página fora do ar. |
{
"name": "Clínica Sorriso",
"stack": "html",
"starter": "captura-de-leads"
}O status da página é draft, published, suspended ou archived. Uma página no ar não troca de endereço, não é arquivada e não é excluída (409 project_published).
Versão e If-Match
Toda escrita na página (PATCH, arquivos, edições, versões) leva no cabeçalho If-Match o número version lido por último. Sem ele a resposta é 428 version_required; com uma versão velha, 409 version_conflict, com o estado atual em current. As configurações têm a própria versão, devolvida por GET /sites/projects/{id}/settings.
Arquivos
A página é um conjunto de arquivos de texto, cada um com um rev que sobe a cada mudança. A tecnologia (stack) decide quais caminhos valem:
| Tecnologia | Arquivos |
|---|---|
html | site.json e theme.css (obrigatórios), pages/*.html, partials/*.html, scripts/*.js e knobs.json. Os nomes usam letras minúsculas, números, - e _. |
react | site.json e um ponto de entrada, src/main.jsx ou src/main.tsx (nunca os dois), mais arquivos .jsx, .tsx, .js, .ts e .css dentro de src/, e knobs.json. |
O projeto inteiro vai até 10 MB.
site.json
Diz o nome do site, o idioma e as rotas. Cada rota aponta para um arquivo de página: pages/*.html no html e um .jsx ou .tsx dentro de src/ no react.
{
"name": "Clínica Sorriso",
"lang": "pt-BR",
"routes": [
{ "path": "/", "page": "pages/index.html" },
{ "path": "/contato", "page": "pages/contato.html" }
]
}| Campo | Regra |
|---|---|
name | De 1 a 120 caracteres, sem espaços nas pontas. |
lang | Opcional, no formato pt ou pt-BR. |
routes | Ao menos a rota /. Cada path usa letras minúsculas, números e hífens, separados por /, até 200 caracteres, sem repetir. |
knobs.json
Os knobs são controles de ajuste fino (uma medida ou uma cor) ligados a variáveis CSS que os arquivos de estilo declaram. O arquivo é opcional.
{
"knobs": [
{ "name": "Espaço do topo", "variable": "--espaco-topo", "kind": "range", "min": 0, "max": 120, "step": 4, "unit": "px" },
{ "name": "Cor de destaque", "variable": "--cor-destaque", "kind": "color" }
]
}| Campo | Regra |
|---|---|
name | De 1 a 60 caracteres, único. |
variable | Uma variável CSS como --espaco-topo, única e declarada num arquivo de estilo. |
kind | range (precisa de min menor que max e step positivo, com unit opcional entre px, rem, em, %, vh, vw, deg, ms e s) ou color (sem min, max, step nem unit). |
Ler e salvar arquivos
GET /sites/projects/{id}/files devolve os arquivos com o rev de cada um. PUT /sites/projects/{id}/files grava o conteúdo inteiro dos arquivos em files e exclui os de deleted; uma regra quebrada que o envio cria (caminho, tamanho, site.json) responde 422, e problemas antigos em arquivos não tocados não bloqueiam. GET /sites/projects/{id}/export baixa o código num ZIP.
Edições por operações
POST /sites/projects/{id}/edits aplica um lote de operações, o mesmo contrato que o assistente do aplicativo usa. O corpo é {"operations": [...]}, com ao menos uma operação, e o cabeçalho If-Match leva a versão da página. Todas as operações, com os campos de cada uma, estão em Operações de edição de páginas.
As operações se dividem em famílias:
| Família | Operações |
|---|---|
| Código | write_file, edit_file, delete_file, rename_file |
| Visuais | set_text, set_attr, set_classes, replace_image, move, duplicate, remove, insert_section |
| Tema | set_token, set_knob |
| Atalhos | define_knob, rename_knob, remove_knob, set_whatsapp_link, clear_whatsapp_link, insert_element, set_form_field, insert_form_field |
Nodes, revs e refs
- As operações visuais apontam um elemento por
node, no formatoarquivo#posição, lido do mapa da página (GET /sites/projects/{id}/outline). revé o rev do arquivo no momento da leitura. Uma operação comnodeprecisa dele;write_filede um arquivo existente,delete_fileerename_filetambém, e um arquivo que mudou depois da leitura respondefile_stale.refdá um nome a um elemento criado (porduplicate,insert_section,insert_elementouinsert_form_field), e as operações seguintes do mesmo lote o apontam como@nome.
{
"operations": [
{ "op": "set_text", "node": "pages/index.html#212", "rev": 3, "text": "Sorrisos **sem pressa**" },
{ "op": "set_token", "name": "--cor-primaria", "value": "#0f766e" },
{ "op": "insert_section", "at": { "page": "pages/index.html" }, "rev": 3, "library_key": "faq", "ref": "perguntas" },
{ "op": "set_classes", "node": "@perguntas", "add": ["py-16"], "breakpoint": "md" }
]
}O lote é atômico
Se uma operação é recusada, nada é gravado: a resposta é 422 edit_refused, e details traz failures (o índice da operação, o code e o field), skipped (as operações que dependiam de uma recusada, com after apontando a recusada) e issues (problemas novos que o lote criaria). Os índices apontam para a operação enviada.
Com sucesso, a resposta traz o projeto, a versão nova, o novo rev de cada arquivo em revs, changes (os arquivos alterados com conteúdo e rev, os excluídos e os renomeados), facts (rotas, tokens do tema, knobs e breakpoints) e ignored (campos que uma operação não lê, descartados sem recusar o lote).
Configurações
GET /sites/projects/{id}/settings e PUT /sites/projects/{id}/settings leem e substituem o documento de configurações inteiro. Campos desconhecidos e valores fora das regras respondem 422.
| Campo | O que guarda |
|---|---|
pages | SEO por rota: title (até 70 caracteres), description (até 320), og_media_id, canonical (https) e noindex. |
integrations | Ids de rastreamento: meta_pixel, ga4, gtm, google_ads, tiktok_pixel e clarity, cada um no formato do seu serviço. |
forms | Por id do formulário no código: name, funnel_id, stage_id, owner, workflow_id, follow_up, success e notify. |
bookings | Por id do bloco de agendamento: duração, intervalo, antecedência, dias à frente, horário por dia da semana, título, Meet, campos extras e texto de consentimento. |
redirects | from (uma rota que não seja /), to (uma rota ou um endereço https) e status (301 ou 302). |
consent | Aviso de cookies: banner, text (até 2.000 caracteres) e categories (analytics, marketing). |
site | favicon_media_id, structured_data e webchat_widget (a chave ou o id de um chat do site do workspace, mostrado em todas as páginas). |
Regras dos formulários:
| Campo | Regra |
|---|---|
owner | kind unassigned (sem id), user ou roulette (com id). |
follow_up | O canal que continua a conversa: kind whatsapp, unofficial_whatsapp ou email, com o id do canal. Obrigatório quando há workflow_id (form_channel_required). |
workflow_id | Um fluxo cujo gatilho é este formulário (form_workflow_not_bound); veja GET /sites/projects/{id}/forms/{formId}/automations. |
funnel_id | Abre uma negociação no funil; precisa de um owner atribuído ou de um fluxo (form_deal_owner_required). |
success | O que o visitante vê depois de enviar: message (com message, até 500 caracteres), redirect (com route) ou whatsapp (com channel). |
{
"pages": {
"/": { "title": "Clínica Sorriso", "description": "Agende sua avaliação pelo WhatsApp." }
},
"integrations": { "ga4": "G-ABC123XYZ" },
"forms": {
"orcamento": {
"name": "Orçamento",
"owner": { "kind": "roulette", "id": "7c2d9a10-5b3e-4f61-8a9d-2e4f6b8c0d12" },
"success": { "kind": "message", "message": "Recebemos seu pedido. Falamos com você em breve." },
"notify": true
}
},
"redirects": [ { "from": "/promo", "to": "/", "status": 302 } ]
}Salvar as configurações reserva a chave pública de cada formulário e de cada bloco de agendamento, então eles já aparecem no gatilho dos fluxos antes da primeira publicação. GET /sites/projects/{id}/settings-changes lista o que muda no ar na próxima publicação.
Publicação e domínios
| Rota | Para que serve |
|---|---|
POST /sites/projects/{id}/deployments | Publica a versão atual: compila, valida o HTML final, verifica os links e troca o endereço para a nova publicação. Exige sites:publish e assinatura ativa. |
GET /sites/projects/{id}/deployments | As publicações, da mais nova para a mais antiga. |
POST /sites/projects/{id}/deployments/{deploymentId}/activate | Volta uma publicação anterior ao ar. |
POST /sites/projects/{id}/unpublish | Tira a página do ar e desativa os formulários dela. |
GET /sites/projects/{id}/hostnames | O subdomínio da plataforma e os domínios próprios, com o estado e os registros DNS. |
POST /sites/projects/{id}/hostnames | kind platform cria o subdomínio (com slug opcional); kind custom registra um domínio próprio em hostname. |
POST /sites/projects/{id}/hostnames/{hostnameId}/verify | Confere o registro TXT de um domínio próprio. |
DELETE /sites/projects/{id}/hostnames/{hostnameId} | Remove um domínio. |
GET /sites/domain-slots | Quantos domínios próprios o workspace usa e quantos pode manter no ar. |
GET /sites/projects/{id}/analytics | Visitas, cliques, envios e leads da página por dia, rota e variante. |
Um domínio próprio passa por pending_dns, pending_ssl e active; pode ficar em removing ou failed, e em suspended quando o TXT foi encontrado mas não há domínio contratado livre. Domínios sem verificação expiram em 72 horas.
Formulários e envios
Os formulários da página ganham uma chave pública (formKey). GET /sites/forms lista os formulários do workspace com a chave, GET /sites/forms/targets diz quais campos do lead cada campo de formulário pode preencher, e GET /sites/projects/{id}/submissions lista os envios recebidos (o IP nunca é guardado).
O runtime da página publicada usa as rotas públicas abaixo, sem token. Só uma origem que é um endereço publicado da página é aceita (403 submission_origin_refused nas outras), e os envios pedem uma prova de trabalho de uso único.
| Rota | Para que serve |
|---|---|
POST /public/sites/forms/{formKey}/challenge | Emite a prova de trabalho que o envio precisa. |
POST /public/sites/forms/{formKey}/submissions | Recebe um envio. Repetir o mesmo idempotencyKey devolve o sucesso original sem criar nada. |
GET /public/sites/forms/{formKey}/slots | Os horários livres de um bloco de agendamento, calculados com o Google Agenda do workspace. |
POST /public/sites/forms/{formKey}/bookings | Reserva um horário, com o mesmo corpo e a mesma prova de trabalho de um envio. |
O lead é gravado no momento do envio. Responsável, negociação, conversa, automação, aviso e evento de conversão rodam depois da resposta, com novas tentativas, e nunca atrasam o envio.