API e webhooks

Endpoints públicos, transparência total.

Esta página lista todos os endpoints HTTP que o sistema expõe externamente — webhooks, cron jobs, health checks. Para devs integrando, parceiros avaliando segurança, ou auditores verificando superfície de ataque.

Importante: não há API REST pública para terceiros consumirem dados de tenant. Todo acesso a dados clínicos é via interface web autenticada com sessão Supabase + defesa em 3 camadas. Os endpoints abaixo são apenas para integração com provedores (Asaas, Meta) e operação interna.

💓 Health & monitoramento

Endpoints de saúde para uso de uptime monitors externos (UptimeRobot, BetterUptime, etc.) e do nosso /status interno.

GET/api/health
Retorna 200 se a aplicação está respondendo e o banco está acessível. Não testa serviços externos (Asaas, OpenAI) — esses são monitorados separadamente em /status.
Auth:Sem auth — endpoint público.
Resposta:
```
{ "status": "ok", "ts": "2026-05-03T12:00:00Z" }
```

💳 Webhooks Asaas

Endpoints que recebem notificações da Asaas quando pagamentos mudam de status. Idempotentes — recebem mesma notificação múltiplas vezes sem duplicar efeitos.

POST/api/webhooks/asaas
Webhook Asaas do TENANT — chamado quando cliente do terapeuta paga PIX/cartão/boleto. Atualiza status em pagamentos da tabela e dispara confirmação WhatsApp/email.
Auth:Validação por payment_id presente no payload. Sem header secreto — Asaas não suporta. Defesa por idempotência: se payment_id já está marcado pago, retorna 200 sem reprocessar.
Payload:
```
{
  "event": "PAYMENT_CONFIRMED",
  "payment": { "id": "pay_xxx", "value": 200.00, ... }
}
```
Resposta:
```
{ "ok": true, "pagamento_id": "uuid" }
```
💡 Configurado em https://www.asaas.com/webhooks no painel do tenant. URL deve ser exatamente esta com HTTPS.
POST/api/webhooks/asaas-master
Webhook Asaas da CONTA MASTER do Atenda — recebe pagamentos das mensalidades dos próprios tenants do SaaS. Diferente do anterior: cliente aqui é o terapeuta, não o paciente.
Auth:Validação por header x-asaas-webhook-secret == ASAAS_MASTER_WEBHOOK_SECRET (variável de ambiente). Configurado no painel master da Asaas.
Payload:
```
Mesmo formato do /api/webhooks/asaas
```
Resposta:
```
{ "ok": true }
```

💬 Webhooks WhatsApp

Recebe notificações de mensagens (entrega, leitura, resposta) e validação de webhook do provider configurado pelo tenant.

GET/api/webhooks/whatsapp?hub.mode=subscribe&hub.verify_token=...
Verificação de webhook (Meta/Cloud API). Comparado com WHATSAPP_VERIFY_TOKEN, retorna o hub.challenge se OK.
Auth:Comparação direta de token. 403 se não bater.
Resposta:
```
Echo do hub.challenge como text/plain.
```
POST/api/webhooks/whatsapp
Recebe eventos de mensagens (mensagem recebida do paciente, status de entrega/leitura, falha). Persiste em whatsapp_mensagens_recebidas e em whatsapp_envios_api conforme tipo.
Auth:Validação X-Hub-Signature-256 (HMAC-SHA256 do body com WHATSAPP_APP_SECRET). Idempotente: message_id duplicado é ignorado.
💡 Mesmo endpoint serve provider 360dialog (BSP oficial Meta) e provider Evolution (self-hosted). O formato do payload é compatível porque Evolution emula o protocolo.

🔔 Push notifications

Endpoints chamados pelo browser do tenant para registrar/desregistrar subscription Web Push (VAPID).

POST/api/push/subscribe
Registra uma nova subscription Web Push para o tenant logado. Salva em push_subscriptions com endpoint, p256dh e auth keys.
Auth:Sessão Supabase (cookie httpOnly).
Payload:
```
{
  "endpoint": "https://fcm.googleapis.com/...",
  "keys": { "p256dh": "...", "auth": "..." },
  "userAgent": "Mozilla/5.0 ..."
}
```
Resposta:
```
{ "ok": true, "id": "uuid" }
```
POST/api/push/unsubscribe
Remove subscription pelo endpoint. Chamado quando tenant desativa push em /configuracoes/notificacoes.
Auth:Sessão Supabase.
Payload:
```
{ "endpoint": "https://fcm.googleapis.com/..." }
```

⏰ Cron jobs

Jobs agendados (Vercel Cron) que rodam tarefas periódicas. Protegidos por header CRON_SECRET — não devem ser chamados externamente sem essa chave.

GET/api/cron/lembretes
Cria tarefas de lembrete (véspera + dia) para agendamentos das próximas 48h. Quando provider WhatsApp do tenant é 360dialog ou Evolution, envia automaticamente.
Auth:Header `x-cron-secret: $CRON_SECRET`. Configurado em Vercel Cron a cada 1h.
Resposta:
```
{ "criadas": 12, "enviadas": 8 }
```
GET/api/cron/snapshots
Gera snapshot LGPD de cada tenant ativo: dump JSON de todas as tabelas filtradas por tenant_id, sobe no Supabase Storage e (se configurado) replica para Backblaze B2.
Auth:Header `x-cron-secret`. Configurado para rodar semanalmente.
Resposta:
```
{ "snapshots": 50, "erros": [] }
```
POST/api/inngest
Endpoint de funções Inngest (jobs assíncronos): processamento de áudio, geração de relatório IA, cleanup de sessões, alertas de trial.
Auth:INNGEST_SIGNING_KEY validado pelo SDK Inngest. Não exposto para chamadas externas.

🔐 Administração

Endpoints de manutenção e operações sensíveis. Protegidos por chave de admin separada do CRON_SECRET.

POST/api/admin/reencrypt-secrets
Re-criptografa todas as credenciais de tenant (chaves Asaas, 360dialog, etc.) com a nova SECRET_ENCRYPTION_KEY. Usar após rotacionar a chave master.
Auth:Header `x-admin-secret: $ADMIN_SECRET` (ou CRON_SECRET como fallback). Falha 401 silenciosamente em chamadas sem chave.
💡 Operação pode levar minutos em produção. Processo é idempotente (re-rodar não corrompe dados já migrados).

📅 Feeds públicos

Endpoints sem auth tradicional, mas protegidos por token único na URL.

GET/agenda.ics?token={token}
Calendar feed iCalendar do tenant. Cada tenant tem token único permanente em tenant_configuracoes.agenda_ics_token. Importável no Google Calendar, Apple Calendar, Outlook como subscrição (atualiza automaticamente).
Auth:Token na query string. Sem token ou token inválido = 401.
Resposta:
```
text/calendar (RFC 5545)
```
GET/portal/{token}
Portal do cliente (token-based, sem login). Cliente confirma agendamento, paga, vê histórico. Token gerado por cliente ou agendamento.
Auth:Token criptograficamente seguro. Single-use para algumas ações.

Ainda não há API REST pública

Por razões de sigilo profissional (dados clínicos), não oferecemos hoje uma API REST para terceiros lerem dados de cliente, agendamento ou prontuário do tenant. Se você tem caso de uso legítimo (ex: integração com sistema contábil), escreva para contato@meuconsultorio.app.br descrevendo o que precisa — avaliamos caso a caso.

Para portabilidade de dados (LGPD), use os snapshots exportáveis em /configuracoes/lgpd — geram CSV/JSON criptografados que você baixa diretamente.

Reportar problema de segurança

Se você descobriu vulnerabilidade em algum endpoint, escreva para seguranca@meuconsultorio.app.br. Pesquisadores que reportam responsavelmente são reconhecidos publicamente após o fix (com sua permissão).

Endpoints públicos, transparência total.