marwan/agdar
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
agdar/API_ENDPOINTS.md
Marwan Alwali 27a71b658a first commit
2025-11-02 14:35:35 +03:00

556 lines
14 KiB
Markdown
Raw Blame History

# 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
Reference in New Issue View Git Blame Copy Permalink