Guia de páginas

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

RotaPara que serve
GET /sites/startersOs modelos prontos por tecnologia.
POST /sites/projectsCria uma página a partir de um modelo.
GET /sites/projectsLista 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}/duplicateCria 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:

TecnologiaArquivos
htmlsite.json e theme.css (obrigatórios), pages/*.html, partials/*.html, scripts/*.js e knobs.json. Os nomes usam letras minúsculas, números, - e _.
reactsite.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" }
  ]
}
CampoRegra
nameDe 1 a 120 caracteres, sem espaços nas pontas.
langOpcional, no formato pt ou pt-BR.
routesAo 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" }
  ]
}
CampoRegra
nameDe 1 a 60 caracteres, único.
variableUma variável CSS como --espaco-topo, única e declarada num arquivo de estilo.
kindrange (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íliaOperações
Códigowrite_file, edit_file, delete_file, rename_file
Visuaisset_text, set_attr, set_classes, replace_image, move, duplicate, remove, insert_section
Temaset_token, set_knob
Atalhosdefine_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 formato arquivo#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 com node precisa dele; write_file de um arquivo existente, delete_file e rename_file também, e um arquivo que mudou depois da leitura responde file_stale.
  • ref dá um nome a um elemento criado (por duplicate, insert_section, insert_element ou insert_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.

CampoO que guarda
pagesSEO por rota: title (até 70 caracteres), description (até 320), og_media_id, canonical (https) e noindex.
integrationsIds de rastreamento: meta_pixel, ga4, gtm, google_ads, tiktok_pixel e clarity, cada um no formato do seu serviço.
formsPor id do formulário no código: name, funnel_id, stage_id, owner, workflow_id, follow_up, success e notify.
bookingsPor 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.
redirectsfrom (uma rota que não seja /), to (uma rota ou um endereço https) e status (301 ou 302).
consentAviso de cookies: banner, text (até 2.000 caracteres) e categories (analytics, marketing).
sitefavicon_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:

CampoRegra
ownerkind unassigned (sem id), user ou roulette (com id).
follow_upO 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_idUm fluxo cujo gatilho é este formulário (form_workflow_not_bound); veja GET /sites/projects/{id}/forms/{formId}/automations.
funnel_idAbre uma negociação no funil; precisa de um owner atribuído ou de um fluxo (form_deal_owner_required).
successO 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

RotaPara que serve
POST /sites/projects/{id}/deploymentsPublica 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}/deploymentsAs publicações, da mais nova para a mais antiga.
POST /sites/projects/{id}/deployments/{deploymentId}/activateVolta uma publicação anterior ao ar.
POST /sites/projects/{id}/unpublishTira a página do ar e desativa os formulários dela.
GET /sites/projects/{id}/hostnamesO subdomínio da plataforma e os domínios próprios, com o estado e os registros DNS.
POST /sites/projects/{id}/hostnameskind platform cria o subdomínio (com slug opcional); kind custom registra um domínio próprio em hostname.
POST /sites/projects/{id}/hostnames/{hostnameId}/verifyConfere o registro TXT de um domínio próprio.
DELETE /sites/projects/{id}/hostnames/{hostnameId}Remove um domínio.
GET /sites/domain-slotsQuantos domínios próprios o workspace usa e quantos pode manter no ar.
GET /sites/projects/{id}/analyticsVisitas, 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.

RotaPara que serve
POST /public/sites/forms/{formKey}/challengeEmite a prova de trabalho que o envio precisa.
POST /public/sites/forms/{formKey}/submissionsRecebe um envio. Repetir o mesmo idempotencyKey devolve o sucesso original sem criar nada.
GET /public/sites/forms/{formKey}/slotsOs horários livres de um bloco de agendamento, calculados com o Google Agenda do workspace.
POST /public/sites/forms/{formKey}/bookingsReserva 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.