Páginas: o JSON do documento v2

Guia completo para criar, editar e publicar páginas por API (e por agentes de IA): modelo mental, todos os campos de todos os itens, validação e erros, mídia, fluxos seguros, receitas e prompt pronto.

Documento de página v2: guia completo para agentes

Este guia ensina uma pessoa ou um agente de IA a ler, criar, editar e publicar páginas e formulários do Asender Pages pela API pública, produzindo o JSON do documento v2 certo na primeira tentativa. As tabelas de campos, limites e tipos são geradas do JSON Schema do contrato (asender_docs/contratos/pages-documento-v2.schema.json), o mesmo que os validadores Go (autoridade, roda no servidor) e TypeScript (roda no editor) provam concordar; por isso elas não envelhecem. Tudo que aparece em JSON aqui foi validado nos três lados.

• Base da API: https://api.pages.asender.net (JSON, UTF-8).
• Referência de rotas: Pages API (operações geradas do código) e o guia Pages API: autenticação, erros, domínios. Este guia cobre o que elas não dizem: o conteúdo da página.
• Contexto inteiro para um agente: llms-full.txt inclui este guia.
• Schema: pages-documento-v2.schema.json (JSON Schema 2020-12), também publicado como DocumentoV2 e DocV2_* na OpenAPI de Páginas.

Regra de ouro para agentes: o servidor é a autoridade. Valide localmente contra o schema, envie, e se vier 422 leia codigo e caminho (seção 4), corrija só aquele nó e reenvie. Nunca invente campo: campo desconhecido é recusado.

1. Início rápido para agentes

1.1 Credenciais: o que cada uma alcança

Um agente externo trabalha com uma API key (sk_live_... / sk_test_...), criada pelo dono da conta em Desenvolvedores → Chaves de API com os escopos mínimos da tarefa. A conta é sempre a da chave (validada no servidor a cada chamada; chave revogada para na hora): nenhum header nem campo do corpo escolhe a conta, e um tenant_id no corpo é recusado. Página, rascunho, mídia ou domínio de outra conta responde 404, igual a um id que não existe.

Os escopos não se implicam: pages:write não lê (precisa de pages:read para listar) nem publica. Um agente que cria, confere e publica precisa dos três. Sem o escopo da rota, 403 ({"erro":"a chave não tem o escopo pages:publish"}); rota que não aceita chave, 401. A sessão OIDC de uma pessoa (Authorization: Bearer <token-de-sessão> + X-Asender-Tenant: <slug-da-conta>) continua alcançando tudo de autoria e é o que o painel usa; a chave não alcança editar slug/título (PATCH), testes A/B, roteamento, apagar mídia, SEO do site, redirects nem marca.

Regras que protegem o trabalho de pessoas (valem só para chave):

• Rascunho com ?base= obrigatório. PUT /v1/paginas/{id}/rascunho sem ?base= responde 428. Leia o rascunho (GET, devolve rascunho_em) e devolva esse valor em ?base=; sem rascunho anterior use ?base= vazio. Se uma pessoa (ou outro agente) gravou no meio, o servidor responde 409 RascunhoConflito com o rascunho dela e não grava nada: os dois lados ficam preservados; mescle e tente de novo com o rascunho_em novo.
• Publicar exige a versao. Com chave, POST .../publicar sem {"versao": N} responde 422: o agente publica a versão que ele identificou (o retorno do POST .../versoes, ou ultima_versao em GET /v1/paginas/{id}), nunca "a mais recente" às cegas, que pode ser uma edição de pessoa ainda não revisada. POST /v1/paginas/lote com publicar publica a última versão salva e pula a página com rascunho mais novo (política pular, padrão).
• Nada é sobrescrito. Cada POST .../versoes cria a versão seguinte; publicar move um ponteiro. Desfazer é publicar a versão anterior.
• Autoria visível. Versões e rascunhos feitos por chave levam apikey:<key_id> (coluna criado_por; o rascunho devolve rascunho_por), distinguindo agente de pessoa; as ferramentas de importação por CLI (--nova-versao) recusam sobrescrever a última versão feita por pessoa.
• Sem HTML cru. Conteúdo com bloco/item html exige um usuário com nível elevado; chave de API recebe 403 nesse caso.
• Ritmo por chave. Escritas: 60 por minuto por chave; publicar/despublicar: 20 por minuto; acima disso 429 com Retry-After. Leituras não contam. POST /v1/paginas/lote ainda tem o teto de 12 chamadas por minuto por conta.
• Tudo fica no log. Cada chamada com chave aparece em Desenvolvedores → Logs (servico: pages), com a rota, o status, a chave e o conteúdo redigido.

Os exemplos usam $KEY (a API key) e $API; o mesmo curl funciona com sessão trocando o header.

export API=https://api.pages.asender.net
export KEY='sk_live_...'        # escopos: pages:read pages:write pages:publish
H=(-H "Authorization: Bearer $KEY" -H 'Content-Type: application/json')
# Com sessão de pessoa: -H "Authorization: Bearer $TOKEN" -H "X-Asender-Tenant: $CONTA"

1.2 O documento mínimo válido

{ "versao": 2, "secoes": [ { "id": "a", "colunas": [ { "id": "ac", "itens": [] } ] } ] }

Uma seção, uma coluna, zero itens. Com um título:

{
  "versao": 2,
  "secoes": [
    { "id": "s1", "colunas": [
      { "id": "s1c1", "itens": [
        { "id": "s1c1i1", "tipo": "titulo", "props": { "texto": "Olá, mundo", "nivel": 1 } }
      ] }
    ] }
  ]
}

Todo item tem id, tipo e props (objeto, pode ser {}).

1.3 Criar, editar e publicar (o caminho feliz)

# 1) criar a página (nasce DESPUBLICADA, com a versão 1 = o template enviado)
curl -sS -X POST "$API/v1/paginas" "${H[@]}" -d '{
  "titulo": "Lançamento",
  "slug": "lancamento",
  "template": { "versao": 2, "secoes": [ { "id": "s1", "colunas": [ { "id": "s1c1", "itens": [
    { "id": "t1", "tipo": "titulo", "props": { "texto": "Olá, mundo", "nivel": 1 } } ] } ] } ] }
}'
# -> 201 { "id":"<pagina-id>", "slug":"lancamento", "dominio":"<conta>.apages.xyz", "titulo":"Lançamento",
#          "versao_publicada":0, "ultima_versao":1, "url_publica":"https://<conta>.apages.xyz/lancamento" }

# 2) salvar uma NOVA versão (cada POST cria a versão seguinte; nada é sobrescrito)
curl -sS -X POST "$API/v1/paginas/<pagina-id>/versoes" "${H[@]}" -d @corpo-versao.json   # {"template": {...}}
# -> 201 { "versao": 2 }     |  422 { "erro":"...", "codigo":"ErrPropInvalida", "caminho":"secoes[0]..." }

# 3) publicar UMA versão, pelo número (chave: escopo pages:publish e `versao` obrigatória)
curl -sS -X POST "$API/v1/paginas/<pagina-id>/publicar" "${H[@]}" -d '{ "versao": 2 }'
# -> 200 { "versao_publicada": 2 }

# Rascunho (auto-save, sem versão): leia o rascunho_em e devolva em ?base= (obrigatório com chave)
curl -sS "$API/v1/paginas/<pagina-id>/rascunho" "${H[@]}"            # -> 200 {template, rascunho_em} | 204
curl -sS -X PUT "$API/v1/paginas/<pagina-id>/rascunho?base=<rascunho_em>" "${H[@]}" -d '{"template": {...}}'
# -> 200 { "rascunho_em": "..." } | 409 RascunhoConflito (com o rascunho do servidor) | 428 sem ?base=

Sem template no POST /v1/paginas, a página nasce com um documento inicial (uma seção hero com o título digitado). Corpo máximo: 512 KiB.

1.4 O endereço da página e o domínio padrão

Toda conta tem um domínio padrão num subdomínio de apages.xyz (ex.: minhaconta.apages.xyz). Uma página criada sem dominio nasce nele; a url_publica da resposta é o endereço para abrir. Para usar outro domínio (um próprio, já verificado), crie/atualize a página com dominio ou, depois, mova com PUT /v1/paginas/{id}/dominio (API key pages:write):

curl -sS "$API/v1/dominios" "${H[@]}"          # pages:read, o padrão vem primeiro
curl -sS -X PUT "$API/v1/paginas/<pagina-id>/dominio" "${H[@]}" -d '{ "dominio_id": "<id>", "caminho": "novo-slug" }'

Detalhes (301 do endereço antigo, erros 409/422) na seção 6.5.

1.5 Antes de gerar JSON

1. Escolha a estrutura (seção 2) e os tipos de item (seção 3.1).
2. Gere ids únicos no documento inteiro (sugestão: s1, s1c1, s1c1i1...).
3. Use somente os campos das tabelas da seção 3; tudo que não está lá é recusado.
4. Imagens: URL da galeria da conta ou https:// externa (seção 5).
5. Valide contra o schema, envie, leia o 422 se vier (seção 4).

2. Modelo mental

documento (versao: 2)
 |- configuracoes   (livre, passthrough)
 |- estilo          (a PÁGINA: tema, fundo, textura, fontes, caixa do conteúdo)
 '- secoes[]        (faixas horizontais, de cima para baixo)
     '- colunas[]   (células lado a lado dentro da seção)
         '- itens[] (objetos atômicos: titulo, texto, imagem, botao...)
              '- abas / acordeao: painéis com itens aninhados (um único nível)

• Seção é uma faixa de página inteira: fundo, borda, padding, altura, âncora e comportamento (normal, fixa_topo, popup). Tem de ter 1..12 colunas.
• Coluna é a célula da grade. Seu largura é um peso (fr do CSS grid): colunas 1+2 ocupam 1/3 e 2/3; cinco colunas de peso 1 dão quintos. Define também o alinhamento do conteúdo e o gap entre os itens.
• Item é o objeto. Mora sempre dentro de uma coluna e não contém outros itens, exceto os painéis de abas/acordeao (um nível só, sem abas, acordeao, html nem formulario dentro).
• Estilo da página (estilo) vem antes das seções: tema (claro/escuro/auto), fundo atrás de tudo (cor, degradê, imagem), textura sutil, fontes e a caixa do conteúdo (estilo.conteudo: o miolo contido de toda seção, a "coluna estreita" de uma página de links).

Responsividade. Os pontos de quebra são fixos: celular até 767 px, tablet 768 a 1023 px, computador a partir de 1024 px. No celular as colunas empilham (layout_celular: empilhar, o padrão) ou ficam lado a lado (manter); inverter_celular inverte a ordem da pilha. padding_celular e espacador.altura_celular ajustam o respiro no celular. ocultar_em (seção ou item) esconde por dispositivo. Não há CSS livre: tudo é campo fechado.

Ids. ^[A-Za-z0-9_-]{1,64}$, únicos no documento inteiro: seção, coluna, item e os itens dentro de painéis dividem o mesmo espaço (um item de painel com o id de uma seção é ErrID). Âncoras (secao.ancora): ^[a-z][a-z0-9-]{0,63}$, únicas na página; viram o id HTML da seção e o alvo de #ancora em botões e menus.

Ordem e tamanho. As seções são renderizadas na ordem do array. Tetos importantes: 200 seções, 12 colunas por seção, 100 itens por coluna, 1000 itens por página (contando os de painéis). Tabela completa na seção 3.

Versões do formato. Só o versao: 2 deve ser escrito. O formato v1 (lista plana de blocos) ainda é lido, mas está em saída; não gere v1.

Normalização. O servidor valida e regrava o documento na forma canônica; o que você lê de volta pode ter a ordem das chaves diferente do que enviou.

3. Referência de campos

Tudo nesta seção vem do schema. Convenções das tabelas: Tipo é o tipo JSON; "cor" e "url de mídia" são tipos nomeados (seção 3.4); Padrão é o que o renderer aplica quando a prop está ausente (só aparece quando verificado); "obrigatório" marca campos sem os quais o documento é recusado. Todas as props de item são opcionais, mas um item sem conteúdo (por exemplo um botao sem rotulo) não desenha nada útil.

3.1 Limites do documento

3.2 Os 20 tipos de item

3.3 Documento, estilo da página, seção e coluna

Documento e estilo da página

Documento (raiz):

estilo (a página inteira):

Famílias de fonte aceitas em estilo.fonte_titulos e estilo.fonte_texto (ids exatos, em minúsculas; vazio herda do kit de marca; qualquer outro valor é ErrEstiloInvalido):

comfortaa, urbanist, montserrat, inter, poppins, open-sans, nunito, playfair-display, merriweather, dm-sans, manrope, raleway São auto-hospedadas pelo runtime (/_f/), sem chamada a terceiros.

Seção

Seção:

estilo da seção (estiloSecao):

Para uma seção popup, atraso_popup é em segundos (0..120). fixa_topo serve para cabeçalhos. ocultar_se_vazia esconde a seção quando nenhum item desenha algo.

Coluna

Coluna:

estilo da coluna (estiloCaixa, o mesmo de estilo.conteudo da página):

O envelope do item

Os campos id, tipo e props são obrigatórios. O estilo do item é opcional e comum a todos os tipos: margem (por lado), alinhamento, largura_max, cor_texto e subir.

3.4 Objetos e tipos reutilizados

Cores (cor)

Uma cor é um hex #rrggbb / #rrggbbaa OU um token da paleta da página: transparente, acento, texto, suave, fundo, superficie, borda. acento segue a cor da marca da conta; transparente serve de ponta de degradê (fade). Nome de cor CSS (red), rgb(), hex curto (#fff) e qualquer texto livre são recusados. Onde o schema diz "cor ou vazio", "" significa "use o padrão do tema".

lados

fundo

gradiente

borda

3.5 Cada tipo de item, campo a campo

titulo

Título (h1..h6). Aceita marcação inline [rótulo](url) e [[trecho]].

texto

Parágrafo de texto. Aceita a mesma marcação inline do título e quebras de linha.

imagem

Imagem, com forma, proporção, moldura e link opcional.

botao

Botão (ou link-botão) com visual granular, vidro, ícones e imagem.

tags

Chips (etiquetas) com ícone, link e visual por chip.

Cada entrada de tags.itens[]:

links

Lista de botões de link (o miolo de um link-na-bio), com visual por entrada.

Cada entrada de links.itens[]:

cartoes

Galeria de cartões (foto, título, texto, tag, ícone, link) em grade, carrossel ou lista.

Cada entrada de cartoes.itens[]:

abas

Abas; cada aba é um painel com itens aninhados (um nível só).

Cada entrada de abas.itens[]:

acordeao

Acordeão (sanfona); com faq: true gera FAQPage no JSON-LD da página.

Cada entrada de acordeao.itens[]:

redes

Ícones de redes sociais (Instagram, WhatsApp...) com link.

Cada entrada de redes.itens[]:

menu

Menu de navegação (links de texto), horizontal ou vertical; pode colapsar no celular.

Cada entrada de menu.itens[]:

formulario

Embute um formulário do Asender (campos reais, anti-spam e captura de lead).

video

Vídeo incorporado (<iframe>) a partir de uma URL de embed.

divisor

Linha divisória horizontal.

espacador

Espaço vertical em branco.

icone

Um ícone avulso (kit de ícones ou ícone clássico).

selo

Selo (pílula de destaque com um texto curto).

contador

Contagem regressiva até um prazo.

marca

Logo e/ou nome da conta (vindos do kit de marca efetivo); útil em cabeçalhos.

html

HTML cru. PRIVILEGIADO: só quem tem o nível elevado grava; sem ele a escrita é barrada (403).

3.6 Campos visuais compartilhados

Os mesmos nomes aparecem em vários tipos e têm o mesmo significado. A tabela abaixo é gerada: lista todo campo presente em três ou mais tipos.

Como pensar neles:

• Cores. Hex #rrggbb/#rrggbbaa ou um token (acento, texto, suave, fundo, superficie, borda, transparente). Prefira tokens quando quiser que a página siga o kit de marca; use hex para cores fixas. Nunca red, rgb(...), #fff ou texto livre.
• Vidro líquido. vidro: true liga fundo translúcido com backdrop-filter. Ajuste com vidro_opacidade (0..100, padrão 30), vidro_desfoque (0..40 px, padrão 14) e vidro_saturacao (100..200, padrão 160). Vale em botao, links, tags e cartoes (item e entradas). Não existe em titulo, texto etc. (prop desconhecida).
• Raio. raio (0..200) arredonda todos os cantos; raio_sup_esq, raio_sup_dir, raio_inf_dir, raio_inf_esq fixam cada canto (sentido horário). Com ao menos um canto presente, o canto ausente usa raio. Em imagem, raio presente vence forma.
• Sombra. Caixas (seção, coluna, conteúdo): nenhuma, suave, media, forte. Itens (imagem, botão, entradas, cartões): nenhuma, leve, forte. Os dois vocabulários não se misturam.
• Espaçamento. padding e margem são objetos {topo, direita, base, esquerda} em px (0..400); padding_v/padding_h são o respiro interno de botões/entradas; gap é o espaço entre elementos. Lado omitido = 0.
• Tipografia. transformar (nenhum, caixa_alta, caixa_baixa, capitalizar) e espacamento (0..6 px entre letras) em titulo, texto e botao; fonte_peso (texto: "400".."800") e fonte_tamanho (10..72 px) em botões e entradas; tamanho (p/m/g/gg) em título e texto. Fontes de página: seção 3.3.
• Ícones de kit. icone e icone_dir são nomes, não URLs: clássicos (raio, escudo, coracao, estrela, check, seta, relogio, calendario, telefone, local, usuario, carrinho, presente, chat, cadeado, foguete, grafico, mais), redes (instagram, x, facebook, linkedin, youtube, tiktok, whatsapp, telegram, email, site, github, pinterest) e os kits: Lucide sem prefixo (mountain, arrow-right...; 1942 ícones), Tabler tabler-<nome> (5826) e tabler-f-<nome> (preenchidos), Phosphor ph-<nome> (1434) e Heroicons hero-<nome> / hero-s-<nome> (648). Os nomes são os dos kits originais em minúsculas e com hífen. Um nome que o renderer não conhece não é erro: o ícone some (em links vira o ícone genérico de link), então confira o nome.
• Ícone de mídia (personalizado). icone_img / icone_dir_img aceitam uma URL de mídia e vencem o glifo icone. Vira um <img>; as props de cor de ícone não se aplicam.
• Contêiner do ícone. icone_fundo / icone_dir_fundo (circulo ou quadrado) desenham uma forma atrás do ícone, com _cor e _tamanho (24..72 px). Em redes só vale no item, não nas entradas.
• Imagem dentro do botão. imagem, imagem_alt, imagem_posicao, imagem_tamanho, imagem_forma em botao e nas entradas de links/tags.
• Moldura da imagem. Em imagem: borda, cor_borda, sombra, cor_fundo e padding (0..40) entre a borda e a foto.
• Subir. estilo.subir (0..200 px) puxa o item sobre o anterior (margem de topo negativa que substitui a margem de topo).
• Camadas de fundo. fundo.cor_base fica sob as demais camadas; fundo.sobreposicao é uma película por cima (cor ou degradê, nunca os dois, com opacidade 0..100) e vale sobre cor, degradê e imagem. Exemplo: imagem de fundo com película escura:

{ "tipo": "imagem", "cor_base": "#111111",
  "imagem": { "url": "https://exemplo.test/capa.jpg", "tamanho": "cobrir", "posicao": "centro" },
  "sobreposicao": { "gradiente": { "de": "#000000", "para": "transparente", "angulo": 180 }, "opacidade": 60 } }

3.7 Marcação inline em titulo.texto e texto.texto

Dentro do texto de um título ou parágrafo (e só nesses dois campos) valem duas marcações. Todo o resto é texto: HTML não é interpretado (< e & são escapados), então não envie tags.

Regras: sem aninhamento; o rótulo não pode ter [ ou ]; o endereço vai até o primeiro ), sem espaço, aspas, <, >, \ ou crase, até 2048 caracteres; em http(s) o que vem depois de // não pode começar com /. Link com endereço não permitido reprova a validação (ErrPropInvalida, apontando ...props.texto); não use javascript:, data: nem caminho relativo na marcação (use um item botao ou links para isso). Quebras de linha são mantidas.

{ "id": "t1", "tipo": "titulo",
  "props": { "texto": "Organize seus pedidos sem [[planilhas]]", "nivel": 1, "destaque_cor": "acento" } }
{ "id": "t2", "tipo": "texto",
  "props": { "texto": "Veja o [portfólio](https://exemplo.test/portfolio) ou escreva para [oi@exemplo.test](mailto:oi@exemplo.test)." } }

3.8 Formulários embutidos

O item formulario renderiza um formulário real do Asender (campos, anti-spam, captura de lead). Ele referencia um formulário existente pelo form_id; a ordem é:

1. Crie o formulário: POST /v1/formularios (sessão ou API key forms:write):

curl -sS -X POST "$API/v1/formularios" "${H[@]}" -d '{
  "nome": "Contato do site",
  "external_id": "site-contato",
  "campos": [
    { "nome": "nome",  "rotulo": "Nome",   "tipo": "texto", "obrigatorio": true },
    { "nome": "email", "rotulo": "E-mail", "tipo": "email", "obrigatorio": true },
    { "nome": "mensagem", "rotulo": "Mensagem", "tipo": "texto_longo" }
  ],
  "texto_botao": "Enviar",
  "mensagem_pos_envio": "Recebemos, obrigado."
}'
# -> 201 { "id": "<form-id>", "external_id": "site-contato", ... }

1. Use o id devolvido no item: { "tipo": "formulario", "props": { "form_id": "<form-id>" } }.
2. Páginas publicadas mostram o formulário na hora; capturas viram leads no CRM. Fora de produção, use endereços @exemplo.test em testes: nada sai para ninguém.

form_id vazio significa "ainda não configurado" (o item não desenha nada). Ao importar uma página para outra conta, form_id que a conta de destino não tem é zerado, com aviso. O tipo formulario não pode ficar dentro de abas/acordeão. Campos, destinos e envio de leads por chave: guia de Páginas.

3.9 Abas, acordeão e FAQ (JSON-LD)

abas e acordeao guardam os painéis em props.itens. Cada painel tem titulo (obrigatório, não vazio) e itens: objetos de item completos (id, tipo, props obrigatórios) dos tipos permitidos em painel (titulo, texto, imagem, botao, tags, links, cartoes, redes, menu, video, divisor, espacador, icone, selo, contador, marca). Nunca abas, acordeao, html, formulario (ErrEstruturaInvalida).

• abas.aberta é o índice (0 = primeira) da aba aberta de início e tem de existir.
• acordeao.aberto marca painéis abertos; com um_por_vez: true no máximo um.
• Sem JavaScript todo o conteúdo fica visível; com JS há abas e sanfona acessíveis (WAI-ARIA, teclado).
• FAQ: acordeao com faq: true gera um nó FAQPage no JSON-LD da página publicada. Cada painel é uma pergunta (titulo) e a resposta é o texto dos itens texto/titulo do painel: precisa existir, ter até 4000 caracteres, e a página aceita no máximo 50 perguntas somadas. abas não gera schema.org.

3.10 SEO e meta da página

O SEO não mora no documento: é uma rota própria, GET/PUT /v1/paginas/{id}/seo (sessão ou chave: pages:read / pages:write), e vale sem publicar nova versão (na próxima resolução do runtime). Campos: titulo (até 120), descricao (até 320), canonical_url, noindex, og_titulo, og_descricao, og_imagem_url (só https), og_imagem_alt, og_imagem_largura/og_imagem_altura (juntas, 1..10000). Vazio volta ao padrão do runtime (título da página, primeiro texto, primeira imagem).

curl -sS -X PUT "$API/v1/paginas/<pagina-id>/seo" "${H[@]}" -d '{
  "titulo": "Lançamento | Minha marca", "descricao": "Conheça a novidade de 2026.",
  "og_imagem_url": "https://exemplo.test/og.jpg", "og_imagem_alt": "Capa do lançamento",
  "og_imagem_largura": 1200, "og_imagem_altura": 630
}'

PUT substitui todos os campos de uma vez: leia com GET, altere e devolva.

4. Validação e erros comuns

O servidor valida tudo na escrita (POST /v1/paginas, POST /v1/paginas/{id}/versoes, importação). O rascunho (seção 6.2) só confere a forma, de propósito.

4.1 O formato do erro

Recusa de documento v2 = 422 com três campos:

{
  "erro": "documento: prop de item inválida: secoes[0].colunas[0].itens[0].props.url",
  "codigo": "ErrPropInvalida",
  "caminho": "secoes[0].colunas[0].itens[0].props.url"
}

caminho aponta o nó culpado (índices de array entre colchetes); sem nó, vale versao, secoes ou documento. O servidor devolve o primeiro erro; corrija e reenvie até passar. Os códigos:

Outros status das rotas de página: 400 corpo inválido (campo desconhecido no corpo da requisição, como tenant_id, também é 400), 401 sem credencial (ou rota que não aceita chave), 403 item html sem nível ou chave sem escopo, 404 página inexistente ou de outra conta, 409 endereço em uso, 413 corpo grande demais, 422 regra de negócio (domínio não verificado, título vazio).

4.2 Regras que valem para todo valor

• Campo desconhecido é recusado em todo nível (documento, seção, coluna, item, estilo, props e entradas de lista). O erro nomeia o campo.
• Texto vale em code points, não bytes nem UTF-16: os limites ≤N contam caracteres.
• Inteiros são inteiros. 1.5, "12" e true no lugar de número são ErrPropInvalida.
• Cores só nos formatos do tipo cor (seção 3.4). Nada de nome de cor CSS ou função.
• URL de link (url, link, menu.itens[].url, video.url): vazia, #ancora (^[a-z][a-z0-9-]{0,63}$), /caminho (nunca //) ou esquema http, https, mailto, tel; até 2048 caracteres; sem caractere de controle. javascript:, data:, vbscript: e protocolo relativo //host são recusados.
• URL de mídia (imagem.url, fundo.imagem.url, icone_img, img, imagem...): vazia, /caminho (nunca //) ou http(s)://host/...; sem aspas, apóstrofo, parênteses, barra invertida, espaço, <, > nem controle. Isso existe porque a URL vai para dentro de um url("...") de CSS.
• Valores fechados em CSS. Não existe estilo livre: tudo é enum, faixa numérica ou cor validada. Tentativas de injeção (red;}body{...}, </style><script>, url(...)) caem em ErrPropInvalida/ErrEstiloInvalido.
• html é privilegiado: o item html exige nível elevado (403 sem ele), e a página continua editável sem o item.
• <prop>_rastreio (ex.: url_rastreio) é o objeto do encurtador e só existe ao lado de uma prop de URL de link; não o envie (o editor o gerencia). Em video não existe.
• Limites. Veja a tabela 3.1; estourar é ErrLimite.

4.3 Exemplos reais do corpus de testes

Estes são casos do corpus hostil que os três validadores (Go, TS e schema) rodam em CI (asender_docs/contratos/fixtures/pages-v1-v2/validacao.json, centenas de casos). Cada um mostra o código e o fragmento enviado:

4.4 Como consertar, por classe

4.5 O laço de validação do agente

1. Gere o JSON.
2. Valide localmente contra o schema (qualquer validador JSON Schema 2020-12). O schema não confere ids únicos, âncoras únicas, o teto de 1000 itens, as regras de painel, o limite de FAQ nem a marcação inline; esses o servidor confere (confira ids e âncoras você mesmo).
3. Envie (POST /v1/paginas ou POST /v1/paginas/{id}/versoes).
4. 422? Leia codigo + caminho, corrija somente aquele nó e volte ao passo 3. Não reescreva o documento inteiro a cada erro.
5. 201? Confira a página renderizada (a url_publica só abre a versão publicada) antes de publicar.

5. Mídia

Uma imagem entra no documento por URL. Dois tipos servem:

1. Galeria da conta (recomendado). Envie o arquivo e use o url devolvido:

# upload (multipart, campo "arquivo"); 201 novo, 200 se o MESMO conteúdo já existia (dedup por hash)
curl -sS -X POST "$API/v1/midias" -H "Authorization: Bearer $KEY" \
  -F 'arquivo=@capa.jpg'
# -> { "id":"<midia-id>", "nome":"capa.jpg", "mime":"image/jpeg", "tamanho":123456,
#      "url":"https://.../v1/public/midias/<midia-id>", ... }

# importar por URL (o servidor baixa, com defesa contra SSRF)
curl -sS -X POST "$API/v1/midias/de-url" "${H[@]}" -d '{ "url": "https://exemplo.test/foto.png", "nome": "foto" }'

Use exatamente o campo url da resposta (.../v1/public/midias/<id>) em imagem.url, fundo.imagem.url, icone_img, cartoes.itens[].img etc. A leitura é pública e anônima (a página publicada precisa dela). Variantes redimensionadas: .../v1/public/midias/<id>/w/<largura> (o renderer usa no srcset). Só imagens (JPG, PNG, GIF, WebP, AVIF, SVG; o tipo é decidido pelo conteúdo, não pelo nome; SVG é sanitizado; antivírus se configurado). GET /v1/midias lista a galeria; DELETE /v1/midias/{id} apaga (não apague mídia que uma página usa).

1. Externa https://... : aceita pelo validador, mas a página passa a depender do host de terceiros (some se ele apagar). Para algo que importa, suba para a galeria.

Vídeo não é mídia da galeria: o item video recebe uma URL de embed (ex.: https://www.youtube.com/embed/<id>).

Cópia na importação. POST /v1/paginas/importar e a galeria de templates baixam de novo cada imagem referenciada (imagem de item, galeria, fundo de seção/coluna/página, *_img, cartoes[].img, imagem de botão...) para a galeria da conta de destino e trocam as URLs; apagar a origem depois não quebra o destino. url de link e de botão nunca é baixada. O que não puder ser copiado mantém a URL original e aparece no relatório (mantido_original + motivo). Tetos: 10 MB por arquivo, 50 MB por importação, 60 URLs únicas.

6. Fluxos de trabalho

6.1 Criar do zero

1. (Opcional) POST /v1/formularios se a página tem formulário (seção 3.8).
2. Suba as imagens (seção 5) e anote os url.
3. Monte o documento (receitas na seção 7) e valide.
4. POST /v1/paginas com titulo, slug (^[a-z0-9]+(-[a-z0-9]+)*$), opcional dominio, e o template. Resposta 201 traz id, url_publica, ultima_versao: 1, versao_publicada: 0.
5. PUT /v1/paginas/{id}/seo (opcional).
6. Revisão humana (a página ainda não está no ar).
7. POST /v1/paginas/{id}/publicar com {"versao": 1}.

6.2 Editar com segurança (rascunho, versão, publicação)

Semântica. Uma página tem versões imutáveis (numeradas, só crescem), um ponteiro de publicada e, no máximo, um rascunho: o auto-save do editor, uma cópia de trabalho que não é versão e não está no ar. Publicar só move o ponteiro; versões antigas continuam e publicar uma delas de novo é o rollback.

# 1) ler o estado: a última versão (ou ?versao=N) e os contadores
curl -sS "$API/v1/paginas/<id>" "${H[@]}"
# -> { "pagina": {..., "ultima_versao": 3, "versao_publicada": 2, "url_publica": "..."},
#      "template": { "versao": 2, ... }, "versao": 3 }

# 2) existe rascunho de alguém? 204 = não; 200 = sim, com o instante da última gravação
curl -sS -i "$API/v1/paginas/<id>/rascunho" "${H[@]}"
# -> 200 { "template": {...}, "rascunho_em": "2026-10-09T12:00:00.123456Z" }   |   204

# 3) gravar o SEU rascunho com controle de concorrência
curl -sS -X PUT "$API/v1/paginas/<id>/rascunho?base=<rascunho_em lido, ou vazio se era 204>" "${H[@]}" \
  -d '{ "template": { "versao": 2, "secoes": [ ... ] } }'
# -> 200 { "rascunho_em": "..." }
# -> 409 { "erro":"o rascunho foi alterado em outra aba", "codigo":"RascunhoConflito",
#          "rascunho": { "template": {...do servidor...}, "rascunho_em": "..." } }

# 4) promover a versão (aqui o documento é validado por inteiro: 422 se inválido)
curl -sS -X POST "$API/v1/paginas/<id>/versoes" "${H[@]}" -d '{ "template": { ... } }'   # -> 201 {"versao": 4}

# 5) publicar a versão pelo NÚMERO
curl -sS -X POST "$API/v1/paginas/<id>/publicar" "${H[@]}" -d '{ "versao": 4 }'          # -> 200

• ?base= ausente grava sem condição (clientes antigos); ?base= vazio diz "eu esperava que não houvesse rascunho"; ?base=<rascunho_em> diz "eu vi esta gravação". Se outra gravação aconteceu no meio, o servidor responde 409 com o rascunho dele e não sobrescreve nada: mantenha os dois lados, mescle e tente de novo com o novo rascunho_em.
• O rascunho só confere a forma (objeto JSON até 512 KiB); a validação completa acontece em POST /versoes. Salvar versão não apaga o rascunho (o editor humano é quem o descarta, DELETE /v1/paginas/{id}/rascunho).
• Cada POST /versoes cria a versão seguinte; ninguém sobrescreve a versão de outro. Se duas pessoas salvam ao mesmo tempo, as duas versões existem.

Nunca perca trabalho humano (regras para o agente):

1. Nunca sobrescreva página publicada sem ordem expressa. Para alterar uma página que está no ar, trabalhe em versão nova (não publique), ou duplique (6.6), edite a cópia e peça revisão.
2. Rascunho presente = trabalho humano em andamento. Se GET .../rascunho devolveu 200, não o substitua: parta dele (ele é o estado mais novo), grave com ?base=<rascunho_em>, ou pare e informe. Nunca use DELETE .../rascunho por conta própria.
3. Publique pelo número ({"versao": N}), a versão que você acabou de salvar e validar; não publique "a última" às cegas (uma pessoa pode ter salvado outra no meio).
4. Para desfazer, publique a versão anterior (versao_publicada antes de você mexer).
5. Conflito (409)? Leia o corpo, preserve os dois lados e decida com o humano; nunca force.
6. Guarde o ultima_versao/versao_publicada que você leu e confira antes de publicar.

6.3 Importar e exportar (envelopes)

O arquivo exportado pelo editor (e os 15 link-bios de referência em asender_archive/link-bios/) tem este envelope (asender_pages_template: 2, até 256 KB):

{
  "asender_pages_template": 2,
  "nome": "Minha landing",
  "descricao": "opcional",
  "seo": { "titulo": "Minha landing", "descricao": "...", "og_titulo": "..." },
  "template": { "versao": 2, "secoes": [ ... ] }
}

seo é opcional e não leva canonical_url. Para importar por API, desembrulhe o envelope e chame POST /v1/paginas/importar, que valida como a criação, copia a mídia para a conta, cria a página despublicada e grava o SEO:

curl -sS -X POST "$API/v1/paginas/importar" "${H[@]}" -d '{
  "slug": "minha-landing", "titulo": "Minha landing",
  "template": { "versao": 2, "secoes": [ ... ] },
  "seo": { "titulo": "Minha landing" }
}'
# -> 201 { "pagina": {...}, "importacao": { "itens":[...], "avisos":[...], "copiadas":3, "ja_na_conta":0,
#                                           "mantidas":0, "copia_disponivel":true, "seo_aplicado":true } }

Se alguma imagem não pôde ser copiada, POST /v1/paginas/{id}/midias/copiar tenta de novo (grava versão nova só se algo mudou). 409 se o endereço (slug + domínio) já existe (checado antes de copiar). Para exportar: GET /v1/paginas/{id} e monte o envelope com o template.

6.4 Ações em massa

POST /v1/paginas/lote (sessão): publicar, despublicar, duplicar, mudar_dominio, até 100 páginas por chamada, resultado por página (sem tudo-ou-nada), simular: true para ver o efeito sem escrever. Detalhes e política de rascunho (pular / publicar_salva) no guia de Páginas.

6.5 Mudar o domínio (301 do endereço antigo)

PUT /v1/paginas/{id}/dominio com {"dominio_id": "...", "caminho": "novo-slug"} (sessão ou API key pages:write; dominio_id: "" = host da plataforma, caminho: "" mantém o slug). Se a página já esteve no ar, o endereço antigo passa a responder 301 (308 para métodos que não são GET/HEAD) para o novo, preservando a query string; repetir o pedido é idempotente. 409 com motivo: caminho_em_uso ou pagina_inicial; 422 com dominio_nao_verificado ou caminho_invalido. Domínio próprio exige posse verificada (TXT) antes de qualquer uso.

6.6 Duplicar

POST /v1/paginas/lote com {"acao":"duplicar","ids":["<id>"]} cria uma cópia despublicada (slug com -copia). É a forma segura de iterar sobre uma página que está no ar: edite a cópia, revise, publique a cópia e, se for o caso, troque os endereços com PUT .../dominio.

6.7 O que a API não faz

Não existe exclusão de página nem exclusão em massa, nem listagem de versões (use ultima_versao e GET /v1/paginas/{id}?versao=N). Páginas v1 antigas continuam lidas, mas o conteúdo novo deve ser v2.

7. Receitas completas

Todas validam no schema, no validador Go e no validador TS (teste de CI). As imagens usam o domínio de teste exemplo.test: troque pelos url da sua galeria. Os ids são só exemplos.

7.1 Link na bio

Uma coluna estreita, avatar, nome, bio com marcação inline, lista de links com vidro, redes sociais e rodapé; tema escuro com degradê e textura.

{
  "versao": 2,
  "estilo": {
    "tema": "escuro",
    "fonte_titulos": "montserrat",
    "fonte_texto": "inter",
    "fundo": {
      "tipo": "gradiente",
      "gradiente": {
        "tipo": "linear",
        "de": "#0f172a",
        "para": "#1e293b",
        "angulo": 160
      }
    },
    "padrao": {
      "tipo": "pontos",
      "opacidade": 6,
      "tamanho": 24
    }
  },
  "secoes": [
    {
      "id": "bio",
      "nome": "Perfil e links",
      "estilo": {
        "largura": "contida",
        "largura_max": 480,
        "padding": {
          "topo": 48,
          "direita": 16,
          "base": 48,
          "esquerda": 16
        }
      },
      "colunas": [
        {
          "id": "bio-col",
          "alinhamento_horizontal": "centro",
          "gap": 16,
          "itens": [
            {
              "id": "bio-foto",
              "tipo": "imagem",
              "props": {
                "url": "https://exemplo.test/avatar.jpg",
                "alt": "Foto da Ana Souza",
                "forma": "circulo",
                "largura": 112,
                "proporcao": "1:1",
                "borda": 3,
                "cor_borda": "acento"
              }
            },
            {
              "id": "bio-nome",
              "tipo": "titulo",
              "props": {
                "texto": "Ana Souza",
                "nivel": 1,
                "tamanho": "g"
              },
              "estilo": {
                "alinhamento": "centro"
              }
            },
            {
              "id": "bio-resumo",
              "tipo": "texto",
              "props": {
                "texto": "Designer de [[interfaces]] e marcas. Veja o [portfólio](https://exemplo.test/portfolio).",
                "variante": "suave",
                "destaque_cor": "acento"
              },
              "estilo": {
                "alinhamento": "centro"
              }
            },
            {
              "id": "bio-links",
              "tipo": "links",
              "props": {
                "estilo": "suave",
                "tamanho": "g",
                "efeito": "elevar",
                "raio": 16,
                "vidro": true,
                "vidro_opacidade": 30,
                "itens": [
                  {
                    "titulo": "Portfólio",
                    "texto": "Projetos recentes",
                    "url": "https://exemplo.test/portfolio",
                    "icone": "site",
                    "nova_aba": true,
                    "destaque": true
                  },
                  {
                    "titulo": "Agende uma conversa",
                    "url": "https://exemplo.test/agenda",
                    "icone": "calendario",
                    "icone_fundo": "circulo",
                    "cor": "acento",
                    "cor_texto": "#0f172a"
                  },
                  {
                    "titulo": "Fale no WhatsApp",
                    "url": "https://wa.me/5511900000000",
                    "icone": "whatsapp",
                    "nova_aba": true
                  },
                  {
                    "titulo": "E-mail",
                    "url": "mailto:ana@exemplo.test",
                    "icone": "email"
                  }
                ]
              }
            },
            {
              "id": "bio-redes",
              "tipo": "redes",
              "props": {
                "tamanho": "m",
                "itens": [
                  {
                    "rede": "instagram",
                    "url": "https://instagram.com/exemplo"
                  },
                  {
                    "rede": "linkedin",
                    "url": "https://linkedin.com/in/exemplo"
                  },
                  {
                    "rede": "github",
                    "url": "https://github.com/exemplo"
                  }
                ]
              }
            },
            {
              "id": "bio-rodape",
              "tipo": "texto",
              "props": {
                "texto": "© 2026 Ana Souza",
                "variante": "suave",
                "tamanho": "p"
              },
              "estilo": {
                "alinhamento": "centro",
                "margem": {
                  "topo": 16
                }
              }
            }
          ]
        }
      ]
    }
  ]
}

7.2 Landing com hero, cartões e FAQ

Cabeçalho fixo com menu e âncoras, hero em duas colunas, três cartões em grade, FAQ (acordeao com faq: true, gera JSON-LD) e chamada final.

{
  "versao": 2,
  "estilo": {
    "tema": "claro",
    "fonte_titulos": "poppins",
    "fonte_texto": "inter",
    "fundo": {
      "tipo": "cor",
      "cor": "#ffffff"
    }
  },
  "secoes": [
    {
      "id": "topo",
      "nome": "Cabeçalho",
      "comportamento": "fixa_topo",
      "estilo": {
        "fundo": {
          "tipo": "cor",
          "cor": "#ffffff"
        },
        "borda": {
          "largura": 1,
          "cor": "borda",
          "lados": [
            "base"
          ]
        },
        "padding": {
          "topo": 12,
          "direita": 24,
          "base": 12,
          "esquerda": 24
        }
      },
      "colunas": [
        {
          "id": "topo-marca",
          "largura": 1,
          "alinhamento_vertical": "centro",
          "itens": [
            {
              "id": "topo-logo",
              "tipo": "marca",
              "props": {
                "mostrar_logo": true,
                "mostrar_nome": true,
                "altura_logo": 32
              }
            }
          ]
        },
        {
          "id": "topo-menu",
          "largura": 2,
          "alinhamento_vertical": "centro",
          "alinhamento_horizontal": "fim",
          "itens": [
            {
              "id": "topo-nav",
              "tipo": "menu",
              "props": {
                "orientacao": "horizontal",
                "colapsar_celular": true,
                "itens": [
                  {
                    "rotulo": "Benefícios",
                    "url": "#beneficios"
                  },
                  {
                    "rotulo": "Perguntas",
                    "url": "#faq"
                  },
                  {
                    "rotulo": "Contato",
                    "url": "#contato"
                  }
                ]
              }
            }
          ]
        }
      ]
    },
    {
      "id": "hero",
      "nome": "Hero",
      "ancora": "inicio",
      "layout_celular": "empilhar",
      "estilo": {
        "fundo": {
          "tipo": "gradiente",
          "gradiente": {
            "tipo": "linear",
            "de": "#eef2ff",
            "para": "#ffffff",
            "angulo": 180
          }
        },
        "padding": {
          "topo": 80,
          "direita": 24,
          "base": 80,
          "esquerda": 24
        },
        "padding_celular": {
          "topo": 40,
          "direita": 16,
          "base": 40,
          "esquerda": 16
        },
        "alinhamento_vertical": "centro"
      },
      "colunas": [
        {
          "id": "hero-texto",
          "largura": 6,
          "gap": 20,
          "itens": [
            {
              "id": "hero-selo",
              "tipo": "selo",
              "props": {
                "texto": "Novo · versão 2"
              }
            },
            {
              "id": "hero-titulo",
              "tipo": "titulo",
              "props": {
                "texto": "Organize seus pedidos sem [[planilhas]]",
                "nivel": 1,
                "tamanho": "gg",
                "destaque_cor": "acento"
              }
            },
            {
              "id": "hero-sub",
              "tipo": "texto",
              "props": {
                "texto": "Cadastre, acompanhe e entregue. Tudo em um só lugar, em minutos.",
                "tamanho": "g",
                "variante": "suave"
              }
            },
            {
              "id": "hero-cta",
              "tipo": "botao",
              "props": {
                "rotulo": "Começar grátis",
                "url": "#contato",
                "variante": "solido",
                "tamanho": "g",
                "icone_dir": "seta"
              }
            },
            {
              "id": "hero-cta2",
              "tipo": "botao",
              "props": {
                "rotulo": "Ver como funciona",
                "url": "#beneficios",
                "variante": "texto",
                "tamanho": "m"
              }
            }
          ]
        },
        {
          "id": "hero-imagem",
          "largura": 6,
          "alinhamento_vertical": "centro",
          "itens": [
            {
              "id": "hero-foto",
              "tipo": "imagem",
              "props": {
                "url": "https://exemplo.test/produto.jpg",
                "alt": "Tela do aplicativo mostrando a lista de pedidos",
                "forma": "arredondada",
                "proporcao": "4:3",
                "sombra": "forte"
              }
            }
          ]
        }
      ]
    },
    {
      "id": "beneficios",
      "nome": "Benefícios",
      "ancora": "beneficios",
      "estilo": {
        "padding": {
          "topo": 64,
          "direita": 24,
          "base": 64,
          "esquerda": 24
        }
      },
      "colunas": [
        {
          "id": "ben-col",
          "gap": 24,
          "alinhamento_horizontal": "centro",
          "itens": [
            {
              "id": "ben-titulo",
              "tipo": "titulo",
              "props": {
                "texto": "Por que usar",
                "nivel": 2
              },
              "estilo": {
                "alinhamento": "centro"
              }
            },
            {
              "id": "ben-cartoes",
              "tipo": "cartoes",
              "props": {
                "layout": "grade",
                "colunas": 3,
                "efeito": "elevar",
                "raio": 16,
                "sombra": "leve",
                "alinhamento_texto": "inicio",
                "icone_fundo": "circulo",
                "itens": [
                  {
                    "icone": "raio",
                    "titulo": "Rápido",
                    "texto": "Cadastre um pedido em menos de dez segundos.",
                    "tag": "Produtividade"
                  },
                  {
                    "icone": "escudo",
                    "titulo": "Seguro",
                    "texto": "Seus dados ficam separados dos de outras contas.",
                    "tag": "Confiança"
                  },
                  {
                    "icone": "grafico",
                    "titulo": "Claro",
                    "texto": "Relatórios simples para decidir o que fazer amanhã.",
                    "tag": "Controle"
                  }
                ]
              }
            }
          ]
        }
      ]
    },
    {
      "id": "faq",
      "nome": "Perguntas frequentes",
      "ancora": "faq",
      "estilo": {
        "largura": "contida",
        "largura_max": 760,
        "padding": {
          "topo": 64,
          "direita": 24,
          "base": 64,
          "esquerda": 24
        }
      },
      "colunas": [
        {
          "id": "faq-col",
          "gap": 24,
          "itens": [
            {
              "id": "faq-titulo",
              "tipo": "titulo",
              "props": {
                "texto": "Perguntas frequentes",
                "nivel": 2
              }
            },
            {
              "id": "faq-acordeao",
              "tipo": "acordeao",
              "props": {
                "faq": true,
                "um_por_vez": true,
                "nivel": 3,
                "estilo": "cartao",
                "indicador": "seta",
                "itens": [
                  {
                    "titulo": "Preciso instalar alguma coisa?",
                    "aberto": true,
                    "itens": [
                      {
                        "id": "faq-r1",
                        "tipo": "texto",
                        "props": {
                          "texto": "Não. Funciona no navegador, no computador ou no celular."
                        }
                      }
                    ]
                  },
                  {
                    "titulo": "Posso cancelar quando quiser?",
                    "itens": [
                      {
                        "id": "faq-r2",
                        "tipo": "texto",
                        "props": {
                          "texto": "Sim. Não há fidelidade e você exporta seus dados a qualquer momento."
                        }
                      }
                    ]
                  },
                  {
                    "titulo": "Como falo com o suporte?",
                    "itens": [
                      {
                        "id": "faq-r3",
                        "tipo": "texto",
                        "props": {
                          "texto": "Escreva para [suporte@exemplo.test](mailto:suporte@exemplo.test); respondemos em até um dia útil."
                        }
                      }
                    ]
                  }
                ]
              }
            }
          ]
        }
      ]
    },
    {
      "id": "final",
      "nome": "Chamada final",
      "ancora": "contato",
      "estilo": {
        "fundo": {
          "tipo": "cor",
          "cor": "acento"
        },
        "padding": {
          "topo": 56,
          "direita": 24,
          "base": 56,
          "esquerda": 24
        }
      },
      "colunas": [
        {
          "id": "final-col",
          "gap": 16,
          "alinhamento_horizontal": "centro",
          "itens": [
            {
              "id": "final-titulo",
              "tipo": "titulo",
              "props": {
                "texto": "Pronto para começar?",
                "nivel": 2
              },
              "estilo": {
                "alinhamento": "centro"
              }
            },
            {
              "id": "final-botao",
              "tipo": "botao",
              "props": {
                "rotulo": "Criar minha conta",
                "url": "https://exemplo.test/cadastro",
                "variante": "contorno",
                "tamanho": "g",
                "nova_aba": true
              }
            }
          ]
        }
      ]
    }
  ]
}

7.3 Página com formulário

Crie o formulário (seção 3.8), copie o id e troque SUBSTITUA_PELO_ID_DO_FORMULARIO.

{
  "versao": 2,
  "estilo": {
    "tema": "claro",
    "fonte_titulos": "manrope",
    "fonte_texto": "inter"
  },
  "secoes": [
    {
      "id": "contato",
      "nome": "Contato",
      "ancora": "contato",
      "estilo": {
        "largura": "contida",
        "largura_max": 560,
        "padding": {
          "topo": 64,
          "direita": 16,
          "base": 64,
          "esquerda": 16
        }
      },
      "colunas": [
        {
          "id": "contato-col",
          "gap": 16,
          "itens": [
            {
              "id": "contato-titulo",
              "tipo": "titulo",
              "props": {
                "texto": "Fale com a gente",
                "nivel": 1
              }
            },
            {
              "id": "contato-texto",
              "tipo": "texto",
              "props": {
                "texto": "Deixe seu e-mail e retornamos em até um dia útil.",
                "variante": "suave"
              }
            },
            {
              "id": "contato-form",
              "tipo": "formulario",
              "props": {
                "form_id": "SUBSTITUA_PELO_ID_DO_FORMULARIO",
                "rotulo": "Enviar mensagem"
              }
            },
            {
              "id": "contato-lgpd",
              "tipo": "texto",
              "props": {
                "texto": "Usamos seus dados só para responder a esta mensagem.",
                "variante": "suave",
                "tamanho": "p"
              }
            }
          ]
        }
      ]
    }
  ]
}

8. Checklist e prompt para agentes

8.1 Checklist

• [ ] Tenho um token de sessão (páginas) ou uma API key com o escopo certo (formulários/domínio).
• [ ] O JSON tem versao: 2 e só campos das tabelas da seção 3.
• [ ] Todo id é único no documento (seção, coluna, item e itens de painel) e casa ^[A-Za-z0-9_-]{1,64}$.
• [ ] Âncoras únicas, ^[a-z][a-z0-9-]{0,63}$; links #x apontam para âncoras que existem.
• [ ] URLs: link só http/https/mailto/tel, #ancora ou /caminho; mídia só http(s) ou /caminho.
• [ ] Cores em hex ou token; fontes da allowlist; inteiros dentro das faixas.
• [ ] Imagens enviadas para a galeria (ou https:// externa consciente).
• [ ] form_id de formulário existente (ou vazio de propósito).
• [ ] Antes de editar: li o rascunho; não vou sobrescrever rascunho humano nem página publicada.
• [ ] Salvei versão, li o 422 se veio, e publico pelo número só com autorização.
• [ ] Guardei a versão publicada anterior para rollback.

8.2 Prompt para colar no agente

Você cria e edita páginas do Asender Pages pela API https://api.pages.asender.net.
Fonte da verdade: https://docs.asender.net/guias/pages-documento-v2.html (e llms-full.txt).

REGRAS
1. Escreva SEMPRE documentos {"versao": 2, "secoes": [...]} (seção > colunas > itens). Cada seção tem
   "id" e "colunas"; cada coluna tem "id" e "itens"; cada item tem "id", "tipo" e "props" (objeto).
2. Use SOMENTE os campos documentados para cada tipo (titulo, texto, imagem, botao, tags, links, cartoes,
   abas, acordeao, redes, menu, formulario, video, divisor, espacador, icone, selo, contador, marca, html).
   Campo desconhecido é recusado. Não use o tipo "html" (privilegiado).
3. "id": ^[A-Za-z0-9_-]{1,64}$, ÚNICO no documento inteiro (inclusive itens dentro de abas/acordeão).
   "ancora" de seção: ^[a-z][a-z0-9-]{0,63}$, única.
4. Cores: "#rrggbb", "#rrggbbaa" ou token (acento, texto, suave, fundo, superficie, borda, transparente).
   Nunca nomes de cor CSS, rgb() ou CSS livre. Fontes (estilo.fonte_titulos/fonte_texto): somente
   comfortaa, urbanist, montserrat, inter, poppins, open-sans, nunito, playfair-display, merriweather,
   dm-sans, manrope, raleway.
5. URLs de link: http, https, mailto, tel, "#ancora" ou "/caminho" (nunca "//" nem javascript:).
   URLs de mídia: https://host/... ou /caminho, sem aspas, espaços ou parênteses. Imagens: suba por
   POST /v1/midias (multipart, campo "arquivo") e use o campo "url" devolvido.
6. Texto de titulo/texto aceita [rótulo](https://...) e [[destaque]]; nada de HTML.
7. Limites: 200 seções, 12 colunas/seção, 100 itens/coluna, 1000 itens/página, listas até 50 entradas,
   abas/acordeão até 20 painéis (um nível, sem html/formulario/abas/acordeao dentro).

FLUXO
- Criar: POST /v1/paginas {"titulo","slug","template"} -> nasce DESPUBLICADA.
- Editar: GET /v1/paginas/{id} (template + ultima_versao + versao_publicada); GET /v1/paginas/{id}/rascunho.
  Se houver rascunho (200), é trabalho humano: parta dele e grave com PUT .../rascunho?base=<rascunho_em>
  (409 RascunhoConflito = preserve os dois lados, não force). Para versionar: POST .../versoes {"template"}.
- Publicar: SOMENTE com autorização do usuário, pelo número: POST .../publicar {"versao": N}.
  Nunca sobrescreva uma página publicada sem ordem expressa; prefira duplicar (POST /v1/paginas/lote
  {"acao":"duplicar","ids":[...]}) e editar a cópia. Rollback = publicar a versão anterior.
- Nunca chame DELETE .../rascunho. Não há exclusão de página.

VALIDAÇÃO
- Valide o JSON contra o schema (pages-documento-v2.schema.json) antes de enviar.
- Se vier 422 {"erro","codigo","caminho"}: corrija SOMENTE o nó em "caminho" conforme "codigo" e reenvie
  (ErrPropInvalida/ErrEstiloInvalido = valor ou campo fora do contrato; ErrID/ErrAncora = repetido ou
  mal formado; ErrLimite = teto; ErrEstruturaInvalida = tipo proibido em painel ou enum). Repita até 201.
- Em testes use apenas e-mails @exemplo.test e imagens de exemplo.test; nunca dados reais de terceiros.

9. Manutenção deste guia

As seções de referência (3.1 a 3.6, 4.1, 4.3 e 7) são geradas. Mudou o contrato do documento (schema, Go, TS)? Rode:

node scripts/docs-pages/gerar-referencia.mjs           # reescreve os blocos gerados deste arquivo
node scripts/docs-pages/gerar-referencia.mjs --check   # CI: falha se o guia está defasado
node --test scripts/docs-pages/documento-v2.test.mjs   # guia em dia + receitas no schema

e commite este arquivo. As notas em prosa das tabelas (finalidade de cada tipo, descrição e padrão de cada prop) ficam em scripts/docs-pages/referencia-notas.mjs; o gerador reprova nota sobre prop que saiu do schema. Receitas: asender_docs/apis/pages/exemplos-v2/*.json; cada uma é validada contra o schema (node), o validador Go (receitas_docs_test.go) e o validador TS (receitas-docs.test.ts).