# Integração demonstrativa VEREDA

A VEREDA é uma marca fictícia. Use somente nome e telefone inventados. O padrão é armazenamento local, sem envio, atendimento ou mensagens. O exemplo GAS é opcional e requer configuração e teste de transporte no destino efetivo.

## Instalação local

Use Node.js compatível com Astro 7 e Python 3 para o empacotamento. Execute `npm ci`, `npm test`, `npm run check`, `npm run package`, `npm run build` e `npm run serve`. O servidor informa uma porta livre e serve `dist` sem alterar seus arquivos. `npm run dev` inicia o desenvolvimento. `npm run proof` compara os contratos protegidos, os arquivos de download e os conteúdos do ZIP.

## Planilha e propriedades privadas

Cole `gas/Code.gs` em um projeto Google Apps Script com runtime V8. Execute `setup()` pelo editor e conceda acesso à planilha. A função cria a planilha e as três abas; não sobrescreve cabeçalhos incompatíveis. Nas Script Properties, configure:

| Propriedade | Uso |
| --- | --- |
| `SPREADSHEET_ID` | ID da planilha demonstrativa criada ou preparada. |
| `CREATE_TOKEN` | Segredo privado de um operador autorizado a criar e reconciliar seus testes. |
| `ADMIN_TOKEN` | Segredo privado separado para leitura e exclusão administrativas. |
| `CANCEL_SECRET` | Segredo usado para derivar a capability vinculada à marca, registro e tentativa. |
| `RATE_LIMIT_PER_MINUTE` | Inteiro de 1 a 600; padrão configurado por setup: 60, por papel autorizado. |

Tokens são strings não vazias de até 512 pontos de código, sem controles. Compartilhe-os somente por canal privado. Nenhum segredo vai em URL, variável pública, logs, exportação ou armazenamento do navegador. A interface `/demo/#acesso` mantém os tokens apenas em memória; recarregar exige nova autorização. A configuração demonstra acesso privado de um único operador por papel; não é autenticação comercial de múltiplos usuários.

| Aba | Colunas, na ordem |
| --- | --- |
| `pedidos` | RecordId, BrandId, RequestId, Fingerprint, PayloadJson, Status, CreatedAt, CancelledAt, CancelHash, DeletedAt |
| `tentativas` | BrandId, RequestId, Fingerprint, State, RecordId, CreatedAt |
| `operacoes` | OperationId, Kind, RecordId, RequestId, State, CreatedAt |

Todas as colunas usam formato texto. O payload fica em JSON, evitando interpretar nomes como fórmulas. A planilha e o ledger são privados. Não publicar a planilha nem permitir que visitantes alterem suas linhas. Limites de Apps Script, Sheets e permissões da conta continuam aplicáveis; o limite privado por minuto não elimina as quotas da plataforma.

## Publicação e transporte

Publique como web app executado pela conta operadora, com a política de acesso necessária à demonstração autorizada. A conta precisa ter permissão de leitura e escrita sobre a planilha. Copie o URL `/exec` para `PUBLIC_DEMO_GAS_ENDPOINT` em um `.env` local e execute novamente o build. `.env.example` mantém o endpoint vazio. Não coloque tokens em variáveis `PUBLIC_*`.

O único GET público é `?op=health`, com `ok`, `schemaVersion` e `brandId`; não lista dados. Um health positivo não confirma criação. As cinco operações privadas usam POST com JSON `{op,authToken,payload}` e `Content-Type: text/plain;charset=UTF-8`, limitado a 8.192 bytes UTF-8. Nenhum proxy é obrigatório. Teste a resposta legível no navegador com o redirecionamento real do GAS; CORS não é uma autorização e não se oferece configuração arbitrária de headers pelo GAS. Não usar `no-cors` para simular confirmação.

`register_inquiry`, `request_status`, `cancel_record`, `list_records` e `delete_record` seguem os envelopes, schemas e provas terminais de [integration.md](/downloads/integration.md). A interface principal registra localmente. Em `/demo`, o operador pode autorizar em memória e escolher o destino remoto com aceite desmarcado e destino explícito. A lista administrativa é uma visão separada dos registros deste navegador.

## Idempotência, falhas e recuperação

Criação normaliza nome e telefone, calcula SHA-256 sobre os nove campos na ordem canônica e preserva a mesma tentativa. O servidor usa ScriptLock, ledger durável e chave marca+requestId. Uma inserção interrompida é recuperada pela chave existente sem segunda linha. Cancelamento usa operationId estável e capability privada; repetir uma criação cancelada não reativa o registro. A exclusão administrativa remove o JSON/capability e conserva tombstone e vínculo dos IDs.

HTML, resposta opaca, timeout, ID/fingerprint incoerente, rejeição sem prova terminal e resultado não confirmado mantêm a pendência. Recarregar preserva os dados, nonce e destino; token e capability precisam ser recuperados em memória. Mutação, limpeza, edição, mudança de destino e fallback ficam bloqueados. Cancelamento que retorna recebido não é confirmado como cancelado. Falha na cópia local após confirmação remota exige recuperar a mesma tentativa, sem criar outra.

Uma rejeição encerra criação somente com IDs/fingerprint correspondentes, `definitive:true`, `accepted:false`, `tombstoned:true` e ausência de registro. Após resolução, o operador pode escolher um novo teste local com novo nonce. Exclusão comprovada usa `cancelled`, `deleted:true`, `accepted:true`; não é rejeição de não aceitação e não permite esse fallback.

## Retenção e concorrência

Defina a retenção dos dados fictícios e o acesso da conta antes de admitir tráfego. O exemplo não remove automaticamente registros nem ledger. Não excluir proteção de nonce/operação enquanto replay ou retry daquela chave puder ocorrer. Exclusão remota exige admin e confirmação por registro; não há reset remoto em lote. Limpeza local remove apenas namespaces VEREDA e não apaga a planilha.

Web Locks serializam mutações deste navegador quando disponíveis. Sem Web Locks, a fila e a releitura protegem chamadas na mesma página e deduplicam tentativas, mas não garantem atomicidade entre abas. Eventos storage atualizam contagens e bloqueios. Não limpar manualmente o armazenamento para resolver resultado desconhecido. Dados corrompidos são preservados; limpeza explícita só é possível sem pendência.

## Limites

O pacote e os testes locais não comprovam execução de endpoint real, persistência externa, entrega de mensagens, identidade profissional ou prontidão comercial. Verifique permissões, quotas, transporte, proteção dos segredos e retenção no destino real antes de habilitar a integração demonstrativa. Não use este formulário para relatos, documentos, CPF, processos ou dados pessoais reais.