# 🏥 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)**
```json
{
  "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)**
```json
{
  "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**
```bash
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