# Tenhal Healthcare Platform - API Documentation

## Base URL
```
http://localhost:8000/api/v1/
```

## Authentication
Currently using Django Session Authentication (DRF Browsable API).

**Future:** Token authentication will be added for mobile apps.

## API Endpoints

### 🏥 Core Module

#### Patients
```
GET    /api/v1/patients/                    - List all patients
POST   /api/v1/patients/                    - Create new patient
GET    /api/v1/patients/{id}/               - Get patient details
PATCH  /api/v1/patients/{id}/               - Update patient
DELETE /api/v1/patients/{id}/               - Soft delete patient
GET    /api/v1/patients/{id}/files/         - Get patient files
GET    /api/v1/patients/{id}/consents/      - Get patient consents
GET    /api/v1/patients/{id}/audit_trail/   - Get patient audit history
```

**Query Parameters:**
- `search` - Search by MRN, name, phone
- `gender` - Filter by gender (MALE/FEMALE)
- `is_active` - Filter active patients
- `ordering` - Sort by created_at, mrn, first_name_en

**Example:**
```bash
GET /api/v1/patients/?search=john&gender=MALE&ordering=-created_at
```

#### Clinics
```
GET    /api/v1/clinics/                     - List all clinics
GET    /api/v1/clinics/{id}/                - Get clinic details
```

**Query Parameters:**
- `specialty` - Filter by specialty (MEDICAL, NURSING, ABA, OT, SLP)
- `is_active` - Filter active clinics

#### Files & SubFiles
```
GET    /api/v1/files/                       - List patient files
GET    /api/v1/files/{id}/                  - Get file details
GET    /api/v1/files/{id}/subfiles/         - Get file's subfiles
GET    /api/v1/subfiles/                    - List subfiles
GET    /api/v1/subfiles/{id}/               - Get subfile details
```

#### Consents
```
GET    /api/v1/consents/                    - List consents
POST   /api/v1/consents/                    - Create consent
GET    /api/v1/consents/{id}/               - Get consent details
PATCH  /api/v1/consents/{id}/               - Update consent
DELETE /api/v1/consents/{id}/               - Delete consent
POST   /api/v1/consents/{id}/verify/        - Verify signature
```

#### Attachments
```
GET    /api/v1/attachments/                 - List attachments
POST   /api/v1/attachments/                 - Upload attachment
GET    /api/v1/attachments/{id}/            - Get attachment details
DELETE /api/v1/attachments/{id}/            - Delete attachment
```

#### Audit Logs
```
GET    /api/v1/audit-logs/                  - List audit logs
GET    /api/v1/audit-logs/{id}/             - Get audit log details
```

---

### 📅 Appointments Module

#### Appointments
```
GET    /api/v1/appointments/                - List appointments
POST   /api/v1/appointments/                - Book appointment
GET    /api/v1/appointments/{id}/           - Get appointment details
PATCH  /api/v1/appointments/{id}/           - Update appointment
DELETE /api/v1/appointments/{id}/           - Cancel appointment
```

**Query Parameters:**
- `patient` - Filter by patient ID
- `clinic` - Filter by clinic ID
- `provider` - Filter by provider ID
- `status` - Filter by status
- `scheduled_date` - Filter by date
- `start_date` & `end_date` - Date range filter
- `search` - Search by appointment number, patient MRN/name

**Workflow Actions:**
```
POST   /api/v1/appointments/{id}/confirm/   - Confirm appointment
POST   /api/v1/appointments/{id}/arrive/    - Mark patient arrived
POST   /api/v1/appointments/{id}/start/     - Start appointment
POST   /api/v1/appointments/{id}/complete/  - Complete appointment
POST   /api/v1/appointments/{id}/cancel/    - Cancel with reason
POST   /api/v1/appointments/{id}/reschedule/ - Reschedule appointment
```

**Special Endpoints:**
```
GET    /api/v1/appointments/today/          - Today's appointments
GET    /api/v1/appointments/upcoming/       - Upcoming appointments
GET    /api/v1/appointments/statistics/     - Appointment statistics
```

**Example - Book Appointment:**
```json
POST /api/v1/appointments/
{
  "patient": "uuid-here",
  "clinic": "uuid-here",
  "provider": "uuid-here",
  "room": "uuid-here",
  "service_type": "CONSULTATION",
  "scheduled_date": "2025-10-15",
  "scheduled_time": "10:00:00",
  "duration": 30,
  "notes": "First visit"
}
```

**Example - Confirm Appointment:**
```json
POST /api/v1/appointments/{id}/confirm/
{
  "method": "SMS"
}
```

**Example - Cancel Appointment:**
```json
POST /api/v1/appointments/{id}/cancel/
{
  "cancel_reason": "Patient requested cancellation"
}
```

#### Providers
```
GET    /api/v1/providers/                   - List providers
GET    /api/v1/providers/{id}/              - Get provider details
GET    /api/v1/providers/{id}/availability/ - Check availability
GET    /api/v1/providers/{id}/appointments/ - Provider's appointments
```

**Example - Check Availability:**
```
GET /api/v1/providers/{id}/availability/?start_date=2025-10-15&end_date=2025-10-20
```

#### Rooms
```
GET    /api/v1/rooms/                       - List rooms
GET    /api/v1/rooms/{id}/                  - Get room details
```

#### Schedules
```
GET    /api/v1/schedules/                   - List schedules
POST   /api/v1/schedules/                   - Create schedule
GET    /api/v1/schedules/{id}/              - Get schedule details
PATCH  /api/v1/schedules/{id}/              - Update schedule
DELETE /api/v1/schedules/{id}/              - Delete schedule
```

---

### 💰 Finance Module

#### Invoices
```
GET    /api/v1/invoices/                    - List invoices
POST   /api/v1/invoices/                    - Create invoice
GET    /api/v1/invoices/{id}/               - Get invoice details
PATCH  /api/v1/invoices/{id}/               - Update invoice
DELETE /api/v1/invoices/{id}/               - Delete invoice
```

**Query Parameters:**
- `patient` - Filter by patient ID
- `status` - Filter by status (DRAFT, ISSUED, PAID, etc.)
- `issue_date` - Filter by issue date
- `search` - Search by invoice number, patient MRN/name

**Workflow Actions:**
```
POST   /api/v1/invoices/{id}/issue/         - Issue draft invoice
GET    /api/v1/invoices/{id}/payments/      - Get invoice payments
POST   /api/v1/invoices/{id}/mark_paid/     - Mark as fully paid
```

**Special Endpoints:**
```
GET    /api/v1/invoices/overdue/            - Get overdue invoices
GET    /api/v1/invoices/statistics/         - Invoice statistics
```

**Example - Create Invoice:**
```json
POST /api/v1/invoices/
{
  "patient": "uuid-here",
  "appointment": "uuid-here",
  "issue_date": "2025-10-13",
  "due_date": "2025-10-20",
  "subtotal": "500.00",
  "tax": "75.00",
  "discount": "0.00",
  "line_items": [
    {
      "service": "uuid-here",
      "description": "Medical Consultation",
      "quantity": 1,
      "unit_price": "500.00"
    }
  ],
  "notes": "Payment due within 7 days"
}
```

#### Payments
```
GET    /api/v1/payments/                    - List payments
POST   /api/v1/payments/                    - Record payment
GET    /api/v1/payments/{id}/               - Get payment details
PATCH  /api/v1/payments/{id}/               - Update payment
DELETE /api/v1/payments/{id}/               - Delete payment
```

**Workflow Actions:**
```
POST   /api/v1/payments/{id}/process/       - Process pending payment
POST   /api/v1/payments/{id}/refund/        - Refund completed payment
```

**Example - Record Payment:**
```json
POST /api/v1/payments/
{
  "invoice": "uuid-here",
  "payment_date": "2025-10-13",
  "amount": "575.00",
  "method": "CARD",
  "transaction_id": "TXN123456",
  "reference": "Card ending 1234"
}
```

#### Services
```
GET    /api/v1/services/                    - List services (read-only)
GET    /api/v1/services/{id}/               - Get service details
```

#### Packages
```
GET    /api/v1/packages/                    - List packages (read-only)
GET    /api/v1/packages/{id}/               - Get package details
```

#### Package Purchases
```
GET    /api/v1/package-purchases/           - List package purchases
POST   /api/v1/package-purchases/           - Purchase package
GET    /api/v1/package-purchases/{id}/      - Get purchase details
PATCH  /api/v1/package-purchases/{id}/      - Update purchase
POST   /api/v1/package-purchases/{id}/use_session/ - Use one session
```

#### Payers
```
GET    /api/v1/payers/                      - List payers
POST   /api/v1/payers/                      - Create payer
GET    /api/v1/payers/{id}/                 - Get payer details
PATCH  /api/v1/payers/{id}/                 - Update payer
DELETE /api/v1/payers/{id}/                 - Delete payer
```

---

### 🔄 Referrals Module

#### Referrals
```
GET    /api/v1/referrals/                   - List referrals
POST   /api/v1/referrals/                   - Create referral
GET    /api/v1/referrals/{id}/              - Get referral details
PATCH  /api/v1/referrals/{id}/              - Update referral
DELETE /api/v1/referrals/{id}/              - Delete referral
```

**Query Parameters:**
- `patient` - Filter by patient ID
- `from_clinic` - Filter by source clinic
- `to_clinic` - Filter by destination clinic
- `status` - Filter by status (PENDING, ACCEPTED, COMPLETED, REJECTED)
- `urgency` - Filter by urgency (ROUTINE, URGENT, EMERGENCY)
- `is_internal` - Filter internal/external referrals

**Workflow Actions:**
```
POST   /api/v1/referrals/{id}/accept/       - Accept referral
POST   /api/v1/referrals/{id}/reject/       - Reject referral
POST   /api/v1/referrals/{id}/complete/     - Complete referral
```

**Special Endpoints:**
```
GET    /api/v1/referrals/sent/              - Sent referrals
GET    /api/v1/referrals/received/          - Received referrals
GET    /api/v1/referrals/pending/           - Pending referrals
GET    /api/v1/referrals/urgent/            - Urgent referrals
GET    /api/v1/referrals/statistics/        - Referral statistics
GET    /api/v1/referrals/workflow/          - Workflow statistics
```

**Example - Create Referral:**
```json
POST /api/v1/referrals/
{
  "patient": "uuid-here",
  "from_clinic": "uuid-here",
  "to_clinic": "uuid-here",
  "from_provider": "uuid-here",
  "to_provider": "uuid-here",
  "reason": "Patient requires ABA assessment for behavioral concerns",
  "clinical_summary": "3-year-old with speech delay and repetitive behaviors",
  "urgency": "ROUTINE",
  "notes": "Parent prefers morning appointments"
}
```

**Example - Accept Referral:**
```json
POST /api/v1/referrals/{id}/accept/
{
  "response_notes": "Referral accepted. Will schedule initial assessment within 2 weeks."
}
```

#### Referral Auto Rules
```
GET    /api/v1/referral-rules/              - List auto-referral rules
POST   /api/v1/referral-rules/              - Create rule
GET    /api/v1/referral-rules/{id}/         - Get rule details
PATCH  /api/v1/referral-rules/{id}/         - Update rule
DELETE /api/v1/referral-rules/{id}/         - Delete rule
```

---

## Response Formats

### Success Response
```json
{
  "id": "uuid-here",
  "field1": "value1",
  "field2": "value2",
  ...
}
```

### List Response
```json
{
  "count": 100,
  "next": "http://localhost:8000/api/v1/patients/?page=2",
  "previous": null,
  "results": [
    {...},
    {...}
  ]
}
```

### Error Response
```json
{
  "error": "Error message here"
}
```

### Validation Error Response
```json
{
  "field_name": [
    "Error message for this field"
  ]
}
```

---

## Common Query Parameters

### Pagination
- `page` - Page number (default: 1)
- `page_size` - Items per page (default: varies by endpoint)

### Filtering
- Use field names as query parameters
- Example: `?status=PENDING&urgency=URGENT`

### Search
- `search` - Full-text search across specified fields
- Example: `?search=john`

### Ordering
- `ordering` - Sort by field (prefix with `-` for descending)
- Example: `?ordering=-created_at`

---

## HTTP Status Codes

- `200 OK` - Successful GET, PATCH, PUT
- `201 Created` - Successful POST
- `204 No Content` - Successful DELETE
- `400 Bad Request` - Validation error
- `401 Unauthorized` - Authentication required
- `403 Forbidden` - Permission denied
- `404 Not Found` - Resource not found
- `500 Internal Server Error` - Server error

---

## Rate Limiting

**Not yet implemented.** Will be added in future updates.

---

## API Versioning

Current version: **v1**

Base URL includes version: `/api/v1/`

---

## Testing the API

### Using cURL
```bash
# List patients
curl -X GET http://localhost:8000/api/v1/patients/ \
  -H "Authorization: Token your-token-here"

# Create patient
curl -X POST http://localhost:8000/api/v1/patients/ \
  -H "Content-Type: application/json" \
  -H "Authorization: Token your-token-here" \
  -d '{
    "first_name_en": "John",
    "last_name_en": "Doe",
    "date_of_birth": "1990-01-01",
    "gender": "MALE",
    "phone": "+966501234567"
  }'
```

### Using Python requests
```python
import requests

# List patients
response = requests.get(
    'http://localhost:8000/api/v1/patients/',
    headers={'Authorization': 'Token your-token-here'}
)
patients = response.json()

# Create appointment
response = requests.post(
    'http://localhost:8000/api/v1/appointments/',
    headers={'Authorization': 'Token your-token-here'},
    json={
        'patient': 'uuid-here',
        'clinic': 'uuid-here',
        'provider': 'uuid-here',
        'scheduled_date': '2025-10-15',
        'scheduled_time': '10:00:00',
        'duration': 30
    }
)
appointment = response.json()
```

### Using JavaScript fetch
```javascript
// List appointments
fetch('http://localhost:8000/api/v1/appointments/', {
  headers: {
    'Authorization': 'Token your-token-here'
  }
})
.then(response => response.json())
.then(data => console.log(data));

// Create referral
fetch('http://localhost:8000/api/v1/referrals/', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Token your-token-here'
  },
  body: JSON.stringify({
    patient: 'uuid-here',
    from_clinic: 'uuid-here',
    to_clinic: 'uuid-here',
    reason: 'Requires assessment',
    urgency: 'ROUTINE'
  })
})
.then(response => response.json())
.then(data => console.log(data));
```

---

## Future Enhancements

1. **Token Authentication** - For mobile apps
2. **Swagger/OpenAPI UI** - Interactive API documentation
3. **Rate Limiting** - Prevent API abuse
4. **Webhooks** - Real-time notifications
5. **Batch Operations** - Bulk create/update
6. **GraphQL Support** - Alternative to REST
7. **API Analytics** - Usage tracking and monitoring

---

## Support

For API support, contact: api@tenhal.com

**Last Updated:** October 13, 2025
**API Version:** v1.0.0