Validação e limites

Escopo: guia do Atendro, OpenAPI, catálogo e 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.

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

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.

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. 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:

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:

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.