Changelog

Política de versionamento da API Pública V1.

Regras

Mudanças incompatíveis entram em uma nova versão de URL (/v2, /v3...). A V1 permanece disponível por pelo menos 12 meses após /v2 sair.
Mudanças compatíveis podem entrar na V1 a qualquer momento:
- novos campos anuláveis em resposta;
- novos códigos de erro documentados;
- novas rotas;
- novos parâmetros opcionais em query.
Mudanças não documentadas são consideradas bug e corrigidas sem aviso prévio.
Cada release sai como entry neste arquivo e como tag Git.

Guia em HTML em /docs, no formato de documentação de produto (menu, início rápido, recursos e referência das 63 rotas).

Lançamento da V1 em piloto com duas clínicas. Escopos e recursos iniciais.

Account: leitura e escrita dos dados cadastrais allowlistados.
Subscription: leitura do plano/status/período.
Users: lista, convite (somente usuario), rename, desativa/reativa.
Contacts: lista paginada, detalhe, criar, editar, excluir (com scope separado), mover de etapa, pausar/retomar follow-up.
Kanban: CRUD de etapas, reordenação, exclusão com destino.
Follow-ups: campanhas e templates CRUD, arquivamento, ativação/pausa separadas; execuções e métricas somente leitura.
Ads: contatos por leads.anuncio, CRUD de regras custom_ads.
Links: CRUD de custom_links e tracking_links, contatos e métricas de link.
Tags: CRUD, substituição em transação, vínculo por contato.
Services: CRUD com desativação lógica.
Appointments: CRUD com cancelamento lógico.
63 operações OpenAPI 3.1 com clinicApiKey e x-required-scope.
Edge Functions: clinic-api-keys (gestão JWT) e public-api-v1 (kernel autenticado).
Frontend: aba API em Configurações, só para perfil clinica ativo.
Headers de rate limit (X-RateLimit-*, Retry-After) e X-Request-Id.

Atribuição Meta aparece com campos null enquanto a ingestão CTWA não está validada em produção. Fonte atual é leads.anuncio.
Sem upload de arquivos. Mídia de follow-up é somente leitura.
Sem envio de WhatsApp/Instagram pela API.
Sem gerenciar Stripe, plano, webhook ou credenciais de integração.

Credenciais hash-only (SHA-256 + prefixo), scopes explícitos, expiração 1–365 dias.
contacts:delete e followups:execute exigem confirmação extra.
Rate limit: 120 read/min, 30 write/min, 10 key-management/min por credencial.
Auditoria de mutação em activity_logs (ação api_*, retenção 30 dias).
Idempotência 24h, body persistido até 2 KiB.
Funções críticas legadas (test_rls_bypass*, update_clinica_evolution_key, upsert_lead, rotinas administrativas) tiveram EXECUTE revogado de anon/authenticated.
Todas as RPCs api_v1_* são SECURITY DEFINER, SET search_path = public, pg_temp, e EXECUTE exclusivo de service_role.

Instalar Docker/WSL para validação local das migrations (Tasks 2-11 não rodaram db reset --local no Windows do desenvolvedor).
Alinhar 8 migrations remotas que constam aplicadas mas não existem no worktree antes de qualquer db push de produção.
Piloto de 7 dias com 2 clínicas, depois expansão gradual conforme pré-flight.

docs/api/authentication.md, errors.md, pagination-idempotency.md, resources.md, security-and-lgpd.md e este changelog.
scripts/publish-public-api-contract.mjs: publica docs/api/openapi.json em public/api/openapi.json durante o build, com validação anti-drift prévia.
src/components/settings/api/ApiQuickstartCard.tsx: card de quickstart dentro da aba API com exemplos PowerShell e Node, aviso server-to-server e botão de download do OpenAPI.
Script npm run api:docs:publish encadeado em npm run build.
/public/api/openapi.json no .gitignore (asset reproduzível, não segunda fonte versionada).
scripts/test-public-api-smoke.ps1: smoke test server-to-server que valida X-Request-Id sem imprimir a chave.

scripts/validate-public-api-contract.mjs rejeita nomes reservados a segredos no contrato publicado.
docs/api/README.md ganhou índice dos guias detalhados.
docs/security/public-api-preflight.md ganhou seção "Status após implementação" com gates atualizados.

Ampliar o validador para exigir X-Request-Id em responses e Idempotency-Key em mutações após regenerar o openapi.json com esses headers por operação.