# Validação do contrato de integração — 18/09/2026

Escopo: [guia do Atendro](https://wpp.atendro.cloud/docs/ATENDRO_INTEGRATION.md), [OpenAPI](https://wpp.atendro.cloud/openapi.json),
[catálogo](https://wpp.atendro.cloud/docs/API_ENDPOINTS.md) e [llms.txt](https://wpp.atendro.cloud/llms.txt). Revisão funcional do
serviço: esta alteração adiciona cadastro global persistido, herança por instância,
rotas públicas de documentação e gerenciamento no console. A migração 0013
preserva inscrições anteriores como exceções explícitas.

## Documentação central — 18/09/2026

A referência pública é servida pelo console em `https://wpp.atendro.cloud/docs`.
As URLs da API continuam específicas de cada servidor. Os antigos caminhos de
documentação redirecionam com 308 para a central, descartando parâmetros de consulta.

A organização contém 10 guias, 56 operações em 12 categorias e 71 modelos.
São 152 páginas com versões HTML e Markdown, além do OpenAPI, `llms.txt`,
`llms-full.txt` e arquivos públicos de apoio. Os exemplos são sintéticos.

| Verificação desta revisão | Resultado |
|---|---|
| Cobertura da referência | Cada operação e modelo do OpenAPI possui página; cada operação está nos dois arquivos para IA |
| Exemplos contra JSON Schema 2020-12 | 181 requisições/respostas ilustrativas válidas; verificação executada no ambiente Python temporário |
| Publicação pelo console | GET/HEAD sem login, sem acesso a store, credenciais ou worker; POST recusado |
| Privacidade dos redirects | Destino fixo em `wpp.atendro.cloud`; host e query do solicitante não são propagados |
| Autenticação existente | Console privado preservado; rotas operacionais continuam na API com os headers originais |
| Conteúdo sem JavaScript | Títulos, campos, exemplos e respostas renderizados pelo servidor; Markdown integral disponível |
| Navegação no navegador | Busca com acentos, páginas de endpoint, abas cURL/JavaScript e status HTTP, cópia de código |
| Responsividade | Revisão visual de desktop e quadros locais com 390 px e 1024 px de largura |
| Renderer e links para IA | Testes de escape HTML, preservação do código e resolução de todos os links Markdown passaram |
| `go test -race ./...`, `go vet ./...`, builds da API e console | Passaram; integração em PostgreSQL descartável |
| Dependências e receptor | 47 módulos revisados; 5 testes do validador HMAC passaram |

O CI compara o catálogo gerado, os índices para IA e o conteúdo completo com o
OpenAPI e os guias. A conferência dos exemplos valida o formato; não comprova
execução de cada exemplo contra WhatsApp real.

## Resultados da integração — 17/09/2026

| Verificação | Resultado | O que demonstra |
|---|---|---|
| Readiness remota (revisão anterior `b626aa3`) | `200 ready` em 17/09 | Evidência anterior, não valida a instalação desta alteração |
| `python3 scripts/sync_api_docs.py --check` | Passou; 56 operações / 50 caminhos | Referências locais, parâmetros de caminho, headers e catálogo sincronizados |
| `openapi-spec-validator 0.7.2` sobre `docs/openapi.json` | `OK` | Documento válido segundo a especificação OpenAPI 3.1 |
| `TestOpenAPICoversRouter` | Passou | Rotas fixas e catálogo de rotas por prefixo correspondem ao OpenAPI; testes referenciados existem |
| `TestOpenAPIAuthenticationMatchesRouter` | Passou nas 56 operações | Headers administrativos/de instância, rejeição de credenciais ausentes/incorretas/duplicadas, Bearer/query/instancekey; despacho autenticado com fixtures |
| `go test -race ./...` | Passou em todos os pacotes | Suíte HTTP/sessão/engine/storage/webhooks e testes de persistência com banco descartável |
| `go vet ./...` | Passou | Análise estática Go |
| `go build ./cmd/atendrozap` e build do console | Passou | Binários compilados |
| `docker build --target api` | Passou | Empacotamento com documentação embutida e compilação dos alvos API/console |
| `python3 scripts/check_dependencies.py` | Passou; 47 módulos revisados | Inventário de dependências Go preservado |
| Herança global e concorrência | Passou com PostgreSQL descartável | Instâncias atuais/futuras, exceções, opt-out, troca de URL, remoção persistida e rotação de chave |
| `TestGlobalWebhookSignedHTTPDelivery` | Passou | Cadastro via HTTP, criação com herança, projeção e entrega HTTP assinada de connection/groups, ordem e baixa na outbox |
| `node --test scripts/verify_webhook_test.mjs` | 5 testes passaram | Corpo bruto, assinatura, timestamp, metadados, limites e falhas do exemplo do receptor |
| Console de webhook | Testes e navegador passaram | Autenticação, CSRF, gravação global/por instância, ausência do segredo nas páginas e bloqueio de redirects com credenciais |
| Documentação no navegador | Passou | Busca entre 56 operações, expansão de schemas, autenticação indicada; tela desktop e largura de 390 px sem overflow horizontal |
| `git diff --check` | Passou | Sem problemas de whitespace no diff |

O PostgreSQL foi criado exclusivamente para esta validação, em contêiner
temporário com armazenamento descartável, e informado por
`ATENDROZAP_TEST_DATABASE_URL`. Não foi usado o banco de laboratório ou o banco
do Atendro. O validador OpenAPI foi instalado em ambiente Python temporário;
nenhuma dependência de execução foi adicionada ao projeto.

O teste de autenticação não substitui os testes funcionais de cada operação:
eles estão relacionados no catálogo e foram executados pela suíte completa.
As sessões HTTP são falsas, por desenho. A validação formal do OpenAPI verifica
o documento, não compara automaticamente cada campo de todos os payloads de
resposta ao JSON Schema. Exemplos e contratos foram revisados no código.

## Publicação inicial autorizada — 17/09/2026

A revisão funcional `74a63a9` foi publicada na API e no console após autorização
do responsável. A configuração de logs do proxy recebeu filtros para dados sensíveis.
Um backup do banco e as imagens anteriores foram preservados antes da atualização.

| Verificação no servidor publicado | Resultado |
|---|---|
| `https://1.atendro.cloud/health/ready` | `200 ready` após reiniciar API e console |
| Documentação pública | As 16 rotas permitidas responderam 200, com conteúdo correspondente aos arquivos da revisão |
| OpenAPI publicado | 56 operações / 50 caminhos |
| `https://wpp.atendro.cloud/login` | 200, formulário de acesso disponível |
| `GET /v1/capabilities` com `admintoken`, via HTTPS público | 200; `global_webhook=true`, eventos `groups` disponíveis, `calls=false` |
| `GET /v1/webhook` com `admintoken` | 200; `scope=server`, `registered=false`: aguardando a URL do novo receptor no Atendro |
| `GET /v1/webhook` sem credenciais | 401 |
| Migrações do banco | As 13 migrações aplicadas, incluindo 0013 |
| Logs do proxy | Marcadores sintéticos confirmaram a ausência de headers e URI no acesso público; um contêiner isolado confirmou a mesma proteção nos logs de acesso e de erro para respostas 502 |

Os tokens permaneceram no servidor durante as consultas autenticadas; não foram
exibidos nem incluídos na documentação. A publicação preservou banco, volumes e
configurações existentes. O webhook global não foi ativado: seu cadastro pelo
console depende da URL e do segredo do receptor que será criado no Atendro.

## Constatações da publicação inicial para o consumidor (17/09/2026)

- **Ligações:** `POST /call/make` retorna `501 calls_not_supported` com token
  válido; `capabilities.calls=false` naquela publicação. A etapa 5d posterior habilita voz por instâncias `calls`, conforme o guia de ligações.
- **Instâncias:** token do servidor usa `admintoken`; token da instância usa
  `token`. Criação responde 200. Listagem não recupera o segredo.
- **Restart administrativo:** responde `202 {message, worker}`; agenda o
  trabalho em background e não devolve a quantidade de sessões reiniciadas.
- **Grupos no webhook:** o cadastro REST agora permite `groups`; a entrega
  assinada foi verificada com evento sintético e receptor HTTP local.
- **Idempotência:** cobre init, todos os envios, ações e mutações de grupo,
  conforme o catálogo; não cobre qualquer POST indiscriminadamente.

## Limites e pendências

As consultas remotas acima validam publicação, autenticação administrativa e
leitura da configuração global. Não substituem a homologação das operações que
alteram instâncias ou interagem com o WhatsApp, nem a entrega ao futuro receptor
do Atendro. O teste de entrega assinada usou somente eventos sintéticos e um
receptor local.

Não houve novo pareamento, envio de mensagem, chamada,
alteração de grupos, cadastro/ativação de servidor no Atendro, migração de
tráfego ou chamadas à rota de conexão durante esta publicação. Os testes locais
e as consultas remotas não encerram os [gates de piloto](https://wpp.atendro.cloud/docs/PILOT_GATES.md).
A documentação foi centralizada no console: `/docs`, `/openapi.json` e
`/llms.txt` são públicos em `https://wpp.atendro.cloud`. Os caminhos antigos
em `https://1.atendro.cloud` redirecionam para a central; a URL das operações
da API permanece específica de cada servidor.

O próximo teste de cadastro no consumidor deve verificar readiness e
capabilities com o token informado no backend privado. As demais operações
reais dependem de ambiente de homologação, números/grupo de teste autorizados
e dos cenários descritos no guia e nos gates.

## Reproduzir as verificações

Com `ATENDROZAP_TEST_DATABASE_URL` já configurada para **um banco descartável**:

```sh
python3 scripts/sync_api_docs.py --check
python3 scripts/check_dependencies.py
python3 -m unittest discover -s scripts -p 'test_build_docs.py'
node --test scripts/verify_webhook_test.mjs
go test -race ./...
go vet ./...
go build ./cmd/atendrozap
git diff --check
```

Opcionalmente, em um ambiente que tenha `openapi-spec-validator==0.7.2`:

```sh
python -m openapi_spec_validator docs/openapi.json
```

O CI executa a sincronização da documentação, o exemplo de verificação HMAC,
os testes Go, vet e build.
A validação formal externa acima foi executada nesta revisão e não é uma
dependência do CI. Sem `ATENDROZAP_TEST_DATABASE_URL`, os testes de PostgreSQL
são pulados; esse resultado não equivale à execução com banco descartável.