Segurança e LGPD

Responsabilidades da clínica (consumidor)

Manter a chave somente no servidor; nunca em navegador, app distribuído, URL, log, analytics, repositório, screenshot ou mensagem.
Guardar a chave em secret manager ou variável de ambiente protegida.
Rotacionar a chave a cada 90 dias ou imediatamente após suspeita de vazamento.
Revogar chaves de funcionários/integrações desligados sem esperar a expiração.
Restringir scopes ao mínimo necessário. Tratar contacts:delete e followups:execute como alto risco.
Registrar as chamadas no sistema próprio, sem registrar PII (telefone, e-mail, anotação, conteúdo de mensagem).
Enviar Idempotency-Key única por intenção lógica.
Tratar 429 com Retry-After + backoff e jitter; nunca retentar em janelas curtas.
Não usar a API em browser. Não há CORS público por design.

Responsabilidades da plataforma (fornecedor)

Hash único SHA-256 da chave, com secret_hash e prefixo de exibição somente.
Derivação da clínica a partir da credencial; o consumidor nunca envia clinica_id. Tentativa de ler recurso de outra clínica retorna o mesmo 404 resource_not_found que recurso inexistente.
Rate limit por credencial, três grupos (read/write/key_management).
Auditoria de mutação em activity_logs com redação; sem PII, sem body, sem chave.
last_used_at atualizado no máximo uma vez por hora por chave.
Logs sem ck_live_*, telefone, e-mail, conteúdo de mensagem ou body de request.
Revogação imediata surte efeito no próximo request.
Conformidade com revisão contínua: ver modelo de ameaças e pré-flight.

Dados pessoais (PII)

Recursos que contêm PII:

contacts: nome, telefone, e-mail, anotação;
account: telefone, e-mail;
users: nome, e-mail;
appointments: título, descrição;
ads/contacts: herda PII do contato.

Recomendações de tratamento:

Finalidade: usar a API somente para integrações de gestão clínica declaradas.
Minimização: requisitar limit baixo, iterar com cursor; evitar varredura completa.
Retenção: o histórico de mutações (activity_logs de api_*) é mantido por 30 dias. Idempotência expira em 24h. Para dados operacionais (contatos, mensagens), a retenção segue a do CRM.
Acesso: somente funcionários autorizados devem ter acesso à chave.
Direitos do titular: exclusão, retificação e portabilidade podem ser atendidos pelo painel do CRM; a API é ferramenta operacional.

Em caso de incidente

Revogar a chave suspeita pelo painel.
Auditar activity_logs via request_id conhecido.
Comunicar o time de segurança da plataforma e abrir chamado.
Gerar nova chave com scopes mínimos.
Revisar integração para identificar a causa (log exposto, commit indevido, servidor comprometido).

Semântica de exclusão

A API não executa cascata destrutiva em dados clínicos:

DELETE /contacts/{id} → bloqueia se houver histórico; não apaga mensagens/agendamentos/follow-up.
DELETE /kanban/stages/{id} → exige destino da mesma clínica; move contatos; exclui etapa.
DELETE /follow-ups/... → arquiva (define archived_at), preserva execuções.
DELETE /services/{id} → desativa (ativo = false), nunca apaga histórico.
DELETE /appointments/{id} → cancela (status = 'cancelado'), preserva linha.

Fora da V1

Prontuários, conteúdo de conversas, upload de arquivos, envio de WhatsApp/Instagram, segredos de integrações e alteração de assinatura. Não há rota que permita alterar plano, cobrança, webhook ou credenciais de integração.