care-api/API_ENDPOINTS_COMPLETE_MAP.md

🏥 Care API - Mapa Completo de Endpoints

Baseado na análise do código fonte Care API v1.0.0 Namespace: care/v1 Base URL: /wp-json/care/v1

📊 RESUMO EXECUTIVO

Categoria	Endpoints	Funcionalidades Principais
Authentication	7	Login, logout, token refresh, password reset
Clinics	9	CRUD, pesquisa, dashboard, estatísticas
Patients	7	CRUD, pesquisa, dashboard, histórico médico
Doctors	10	CRUD, pesquisa, agenda, estatísticas
Appointments	9	CRUD, cancelamento, disponibilidade, bulk ops
Encounters	13	Consultas médicas, SOAP, sinais vitais, templates
Prescriptions	12	CRUD, renovação, interacções medicamentosas
Bills	14	Facturação, pagamentos, lembretes, overdue
Utilities	3	Status API, health check, versão

TOTAL: 84 Endpoints REST API

---

🔐 AUTHENTICATION ENDPOINTS

Base Path: /auth

Method	Endpoint	Descrição	Auth Required
POST	/auth/login	Login de utilizador com username/password	❌ (rate limited)
POST	/auth/logout	Logout e invalidação de token	✅
POST	/auth/refresh	Renovar token JWT	✅
GET	/auth/validate	Validar token actual	✅
GET	/auth/profile	Obter perfil do utilizador	✅
PUT	/auth/profile	Actualizar perfil do utilizador	✅
POST	/auth/forgot-password	Iniciar reset de password	❌ (rate limited)
POST	/auth/reset-password	Confirmar reset de password	❌ (rate limited)

Funcionalidades Especiais:

• Rate limiting em endpoints públicos
• JWT com refresh tokens
• Password reset seguro

---

🏥 CLINIC ENDPOINTS

Base Path: /clinics

Method	Endpoint	Descrição	Auth Required
GET	/clinics	Listar todas as clínicas (com filtros)	✅
POST	/clinics	Criar nova clínica	✅
GET	/clinics/{id}	Obter clínica específica	✅
PUT	/clinics/{id}	Actualizar clínica	✅
DELETE	/clinics/{id}	Eliminar clínica (soft delete)	✅
GET	/clinics/search	Pesquisar clínicas	✅
GET	/clinics/{id}/dashboard	Dashboard da clínica	✅
GET	/clinics/{id}/statistics	Estatísticas da clínica	✅
POST	/clinics/bulk	Operações em lote	✅

Funcionalidades Especiais:

• Filtros por status, localização
• Dashboard com KPIs
• Estatísticas de desempenho

---

👥 PATIENT ENDPOINTS

Base Path: /patients

Method	Endpoint	Descrição	Auth Required
POST	/patients	Criar novo paciente	✅
GET	/patients/{id}	Obter paciente específico	✅
PUT	/patients/{id}	Actualizar dados do paciente	✅
GET	/patients/search	Pesquisar pacientes	✅
GET	/patients/{id}/dashboard	Dashboard do paciente	✅
GET	/patients/{id}/history	Histórico médico completo	✅
POST	/patients/bulk	Operações em lote	✅

Funcionalidades Especiais:

• Pesquisa por nome, email, telefone
• Histórico médico completo
• Isolamento por clínica

---

👨‍⚕️ DOCTOR ENDPOINTS

Base Path: /doctors

Method	Endpoint	Descrição	Auth Required
GET	/doctors	Listar todos os médicos	✅
POST	/doctors	Criar novo médico	✅
GET	/doctors/{id}	Obter médico específico	✅
PUT	/doctors/{id}	Actualizar dados do médico	✅
DELETE	/doctors/{id}	Eliminar médico	✅
GET	/doctors/search	Pesquisar médicos	✅
GET	/doctors/{id}/schedule	Obter agenda do médico	✅
PUT	/doctors/{id}/schedule	Actualizar agenda	✅
GET	/doctors/{id}/stats	Estatísticas do médico	✅
POST	/doctors/bulk	Operações em lote	✅

Funcionalidades Especiais:

• Gestão de agendas/horários
• Estatísticas de performance
• Especializações e qualificações

---

📅 APPOINTMENT ENDPOINTS

Base Path: /appointments

Method	Endpoint	Descrição	Auth Required
GET	/appointments	Listar consultas (com filtros)	✅
POST	/appointments	Criar nova consulta	✅
GET	/appointments/{id}	Obter consulta específica	✅
PUT	/appointments/{id}	Actualizar consulta	✅
POST	/appointments/{id}/cancel	Cancelar consulta	✅
POST	/appointments/{id}/complete	Marcar consulta como concluída	✅
GET	/appointments/availability/{doctor_id}	Verificar disponibilidade do médico	✅
GET	/appointments/search	Pesquisar consultas	✅
POST	/appointments/bulk	Operações em lote	✅

Funcionalidades Especiais:

• Verificação de disponibilidade em tempo real
• Estados: scheduled, confirmed, cancelled, completed, no_show
• Filtros por data, médico, paciente, status

---

🏥 ENCOUNTER ENDPOINTS (Consultas Médicas)

Base Path: /encounters

Method	Endpoint	Descrição	Auth Required
GET	/encounters	Listar todas as consultas médicas	✅
POST	/encounters	Criar nova consulta médica	✅
GET	/encounters/{id}	Obter consulta específica	✅
PUT	/encounters/{id}	Actualizar consulta	✅
DELETE	/encounters/{id}	Eliminar consulta	✅
POST	/encounters/{id}/start	Iniciar consulta	✅
POST	/encounters/{id}/complete	Finalizar consulta	✅
GET	/encounters/{id}/soap	Obter notas SOAP	✅
PUT	/encounters/{id}/soap	Actualizar notas SOAP	✅
GET	/encounters/{id}/vitals	Obter sinais vitais	✅
PUT	/encounters/{id}/vitals	Actualizar sinais vitais	✅
GET	/encounters/search	Pesquisar consultas	✅
GET	/encounters/templates	Obter templates de consulta	✅

Funcionalidades Especiais:

• Notas SOAP (Subjective, Objective, Assessment, Plan)
• Registo de sinais vitais
• Templates de consulta
• Workflow de consulta (start → complete)

---

💊 PRESCRIPTION ENDPOINTS

Base Path: /prescriptions

Method	Endpoint	Descrição	Auth Required
GET	/prescriptions	Listar todas as prescrições	✅
POST	/prescriptions	Criar nova prescrição	✅
GET	/prescriptions/{id}	Obter prescrição específica	✅
PUT	/prescriptions/{id}	Actualizar prescrição	✅
DELETE	/prescriptions/{id}	Eliminar prescrição	✅
POST	/prescriptions/{id}/renew	Renovar prescrição	✅
POST	/prescriptions/check-interactions	Verificar interacções medicamentosas	✅
GET	/prescriptions/patient/{patient_id}	Histórico de prescrições do paciente	✅
GET	/prescriptions/patient/{patient_id}/active	Prescrições activas do paciente	✅
GET	/prescriptions/search	Pesquisar prescrições	✅
GET	/prescriptions/stats	Estatísticas de prescrições	✅
POST	/prescriptions/bulk	Operações em lote	✅

Funcionalidades Especiais:

• Verificação de interacções medicamentosas
• Renovação de receitas
• Prescrições activas vs histórico
• Estatísticas de medicação

---

💰 BILL ENDPOINTS (Facturação)

Base Path: /bills

Method	Endpoint	Descrição	Auth Required
GET	/bills	Listar todas as facturas	✅
POST	/bills	Criar nova factura	✅
GET	/bills/{id}	Obter factura específica	✅
PUT	/bills/{id}	Actualizar factura	✅
DELETE	/bills/{id}	Eliminar factura	✅
POST	/bills/{id}/finalize	Finalizar factura (draft → pending)	✅
POST	/bills/{id}/payments	Processar pagamento	✅
GET	/bills/{id}/payments	Obter pagamentos da factura	✅
GET	/bills/patient/{patient_id}	Facturas do paciente	✅
GET	/bills/overdue	Facturas em atraso	✅
POST	/bills/{id}/remind	Enviar lembrete de pagamento	✅
GET	/bills/search	Pesquisar facturas	✅
GET	/bills/stats	Estatísticas financeiras	✅
POST	/bills/bulk	Operações em lote	✅

Funcionalidades Especiais:

• Estados: draft, pending, paid, overdue, cancelled
• Gestão de pagamentos
• Lembretes automáticos
• Relatórios financeiros

---

🔧 UTILITY ENDPOINTS

Base Path: /

Method	Endpoint	Descrição	Auth Required
GET	/status	Status completo da API	✅ (admin)
GET	/health	Health check mínimo	❌ (rate limited)
GET	/version	Informação de versão	✅ (admin)

Funcionalidades Especiais:

• Monitorização de saúde da API
• Verificação de dependências
• Rate limiting

---

🛡️ SISTEMA DE AUTENTICAÇÃO

JWT Token System

• Access Token: 24h de validade
• Refresh Token: 7 dias de validade
• Header Format: Authorization: Bearer <token>

Rate Limiting

• Login/Password Reset: 10 tentativas por hora por IP
• API Geral: 1000 requests por hora por token
• Health Check: 60 requests por minuto por IP

Permissões por Role

• Admin: Acesso total a todos os endpoints
• Doctor: Acesso a pacientes, consultas, prescrições da sua clínica
• Receptionist: Acesso a agendamento, pacientes básico
• Patient: Acesso limitado aos próprios dados

---

📋 ESTRUTURA DE RESPOSTA PADRONIZADA

Sucesso (HTTP 2xx)

{
  "success": true,
  "data": { /* conteúdo específico */ },
  "message": "Operation completed successfully",
  "timestamp": "2025-09-14T10:30:00Z",
  "pagination": { /* quando aplicável */ }
}

Erro (HTTP 4xx/5xx)

{
  "success": false,
  "message": "Error description",
  "error_code": "VALIDATION_ERROR",
  "errors": { /* detalhes quando aplicável */ },
  "timestamp": "2025-09-14T10:30:00Z"
}

---

🚀 CARACTERÍSTICAS AVANÇADAS

Bulk Operations

Disponível em: Clinics, Patients, Doctors, Appointments, Bills, Prescriptions

• Operações: create, update, delete, activate, deactivate
• Processamento em lote para eficiência

Search & Filtering

• Full-text search em todas as entidades principais
• Filtros avançados por data, status, categoria
• Paginação padrão: 20 items por página, máximo 100

Dashboard Endpoints

• Clinic Dashboard: KPIs, estatísticas, resumo de actividade
• Patient Dashboard: Consultas recentes, prescrições activas, próximas marcações

Medical Features

• SOAP Notes: Sistema completo de notas médicas
• Vital Signs: Registo de sinais vitais
• Drug Interactions: Verificação automática de interacções
• Encounter Templates: Templates pré-definidos para diferentes tipos de consulta

---

⚙️ CONFIGURAÇÃO DE DESENVOLVIMENTO

Environment Variables

CARE_API_DEBUG=true          # Habilita debugging e CORS
CARE_API_JWT_SECRET=xxx      # Secret para JWT tokens
CARE_API_RATE_LIMIT=1000     # Rate limit por hora

Database Tables (KiviCare)

• kc_clinics - Informação das clínicas
• kc_appointments - Agendamento de consultas
• kc_patient_encounters - Consultas médicas
• kc_prescription - Prescrições médicas
• kc_bills - Sistema de facturação
• kc_services - Serviços oferecidos
• kc_doctor_clinic_mappings - Relação médicos-clínicas

---

📚 PRÓXIMOS PASSOS PARA DOCUMENTAÇÃO

1. OpenAPI 3.0 Specification - Expandir o ficheiro YAML existente
2. Interactive API Explorer - Implementar Swagger UI
3. SDK Generation - Gerar SDKs para JavaScript, PHP, Python
4. Postman Collection - Coleção completa para testing
5. Integration Examples - Exemplos práticos de uso da API

---

Gerado automaticamente em: 2025-09-14 Versão da API: 1.0.0 Total de Endpoints Mapeados: 84