marwan/HH
1
0
Fork 0
Code Issues Pull Requests 1 Actions Packages Projects Releases Wiki Activity
HH/docs/API_ENDPOINTS.md
Marwan Alwali 2e15c5db7c first commit
2025-12-24 12:42:31 +03:00

14 KiB
Raw Permalink Blame History

PX360 API Endpoints

Base URL

http://localhost:8000/api/

Authentication

All API endpoints require JWT authentication (except event creation which can use API keys).

Get JWT Token

POST /api/auth/token/
Content-Type: application/json

{
  "username": "admin",
  "password": "your_password"
}

Response:

{
  "access": "eyJ0eXAiOiJKV1QiLCJhbGc...",
  "refresh": "eyJ0eXAiOiJKV1QiLCJhbGc..."
}

Refresh Token

POST /api/auth/token/refresh/
Content-Type: application/json

{
  "refresh": "eyJ0eXAiOiJKV1QiLCJhbGc..."
}

Use Token

GET /api/auth/users/me/
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGc...

Accounts & Authentication

Users

List Users

GET /api/auth/users/
Authorization: Bearer {token}

Query Parameters:

  • is_active - Filter by active status
  • hospital - Filter by hospital UUID
  • department - Filter by department UUID
  • groups - Filter by role/group
  • search - Search by username, email, name, employee_id

Get Current User

GET /api/auth/users/me/
Authorization: Bearer {token}

Create User

POST /api/auth/users/
Authorization: Bearer {token}
Content-Type: application/json

{
  "username": "jdoe",
  "email": "jdoe@hospital.sa",
  "password": "SecurePass123!",
  "password_confirm": "SecurePass123!",
  "first_name": "John",
  "last_name": "Doe",
  "phone": "+966501234567",
  "hospital": "HOSPITAL_UUID",
  "department": "DEPARTMENT_UUID"
}

Update Profile

PUT /api/auth/users/update_profile/
Authorization: Bearer {token}
Content-Type: application/json

{
  "first_name": "John",
  "last_name": "Doe",
  "phone": "+966501234567",
  "language": "ar"
}

Change Password

POST /api/auth/users/change_password/
Authorization: Bearer {token}
Content-Type: application/json

{
  "old_password": "OldPass123!",
  "new_password": "NewPass123!",
  "new_password_confirm": "NewPass123!"
}

Assign Role

POST /api/auth/users/{user_id}/assign_role/
Authorization: Bearer {token}
Content-Type: application/json

{
  "role_id": "ROLE_UUID"
}

Roles

List Roles

GET /api/auth/roles/
Authorization: Bearer {token}

Organizations

Hospitals

List Hospitals

GET /api/organizations/hospitals/
Authorization: Bearer {token}

Query Parameters:

  • status - Filter by status (active, inactive)
  • city - Filter by city
  • search - Search by name, code

Create Hospital

POST /api/organizations/hospitals/
Authorization: Bearer {token}
Content-Type: application/json

{
  "name": "AlHammadi Hospital",
  "name_ar": "مستشفى الحمادي",
  "code": "HOSP001",
  "address": "123 Main St",
  "city": "Riyadh",
  "phone": "+966112345678",
  "email": "info@alhammadi.sa",
  "license_number": "LIC123",
  "capacity": 200,
  "status": "active"
}

Departments

List Departments

GET /api/organizations/departments/
Authorization: Bearer {token}

Query Parameters:

  • hospital - Filter by hospital UUID
  • parent - Filter by parent department UUID
  • status - Filter by status

Create Department

POST /api/organizations/departments/
Authorization: Bearer {token}
Content-Type: application/json

{
  "hospital": "HOSPITAL_UUID",
  "name": "Outpatient Department",
  "name_ar": "قسم العيادات الخارجية",
  "code": "DEPT_OPD",
  "parent": null,
  "manager": "USER_UUID",
  "phone": "+966112345679",
  "location": "Building A, Floor 1",
  "status": "active"
}

Physicians

List Physicians

GET /api/organizations/physicians/
Authorization: Bearer {token}

Query Parameters:

  • hospital - Filter by hospital UUID
  • department - Filter by department UUID
  • specialization - Filter by specialization
  • status - Filter by status

Create Physician

POST /api/organizations/physicians/
Authorization: Bearer {token}
Content-Type: application/json

{
  "first_name": "Ahmed",
  "last_name": "Al-Saud",
  "first_name_ar": "أحمد",
  "last_name_ar": "السعود",
  "license_number": "PHY001",
  "specialization": "Internal Medicine",
  "hospital": "HOSPITAL_UUID",
  "department": "DEPARTMENT_UUID",
  "phone": "+966501234567",
  "email": "ahmed.alsaud@hospital.sa",
  "status": "active"
}

Patients

List Patients

GET /api/organizations/patients/
Authorization: Bearer {token}

Query Parameters:

  • primary_hospital - Filter by hospital UUID
  • gender - Filter by gender
  • city - Filter by city
  • status - Filter by status
  • search - Search by MRN, name, phone, email

Create Patient

POST /api/organizations/patients/
Authorization: Bearer {token}
Content-Type: application/json

{
  "mrn": "MRN123456",
  "national_id": "1234567890",
  "first_name": "Mohammed",
  "last_name": "Ali",
  "first_name_ar": "محمد",
  "last_name_ar": "علي",
  "date_of_birth": "1990-01-15",
  "gender": "male",
  "phone": "+966501234567",
  "email": "mohammed.ali@email.com",
  "address": "123 Street, District",
  "city": "Riyadh",
  "primary_hospital": "HOSPITAL_UUID",
  "status": "active"
}

Journeys

Journey Templates

List Journey Templates

GET /api/journeys/templates/
Authorization: Bearer {token}

Query Parameters:

  • journey_type - Filter by type (ems, inpatient, opd)
  • hospital - Filter by hospital UUID
  • is_active - Filter by active status
  • is_default - Filter by default status

Create Journey Template

POST /api/journeys/templates/
Authorization: Bearer {token}
Content-Type: application/json

{
  "name": "Standard OPD Journey",
  "name_ar": "رحلة العيادات الخارجية القياسية",
  "journey_type": "opd",
  "description": "Standard outpatient journey",
  "hospital": "HOSPITAL_UUID",
  "is_active": true,
  "is_default": true
}

Get Journey Template with Stages

GET /api/journeys/templates/{template_id}/
Authorization: Bearer {token}

Response includes all stages:

{
  "id": "...",
  "name": "Standard OPD Journey",
  "journey_type": "opd",
  "hospital_name": "AlHammadi Hospital",
  "stages": [
    {
      "id": "...",
      "name": "MD Consultation",
      "order": 1,
      "trigger_event_code": "OPD_VISIT_COMPLETED",
      "auto_send_survey": true,
      "survey_template_name": "MD Consultation Survey"
    },
    {
      "id": "...",
      "name": "Laboratory",
      "order": 2,
      "trigger_event_code": "LAB_ORDER_COMPLETED",
      "auto_send_survey": true,
      "survey_template_name": "Lab Experience Survey"
    }
  ],
  "stage_count": 2
}

Stage Templates

List Stage Templates

GET /api/journeys/stage-templates/
Authorization: Bearer {token}

Create Stage Template

POST /api/journeys/stage-templates/
Authorization: Bearer {token}
Content-Type: application/json

{
  "journey_template": "TEMPLATE_UUID",
  "name": "MD Consultation",
  "name_ar": "استشارة الطبيب",
  "code": "OPD_MD_CONSULT",
  "order": 1,
  "trigger_event_code": "OPD_VISIT_COMPLETED",
  "survey_template": "SURVEY_TEMPLATE_UUID",
  "auto_send_survey": true,
  "survey_delay_hours": 2,
  "requires_physician": true,
  "requires_department": true,
  "is_optional": false,
  "is_active": true
}

Journey Instances

List Journey Instances

GET /api/journeys/instances/
Authorization: Bearer {token}

Query Parameters:

  • journey_template - Filter by template UUID
  • journey_template__journey_type - Filter by journey type
  • patient - Filter by patient UUID
  • hospital - Filter by hospital UUID
  • status - Filter by status
  • search - Search by encounter_id, patient MRN/name

Create Journey Instance

POST /api/journeys/instances/
Authorization: Bearer {token}
Content-Type: application/json

{
  "journey_template": "TEMPLATE_UUID",
  "patient": "PATIENT_UUID",
  "encounter_id": "ENC20251214001",
  "hospital": "HOSPITAL_UUID",
  "department": "DEPARTMENT_UUID",
  "metadata": {
    "admission_type": "scheduled",
    "referring_physician": "Dr. Smith"
  }
}

Note: Stage instances are automatically created for all active stages in the template.

Get Journey Progress

GET /api/journeys/instances/{instance_id}/progress/
Authorization: Bearer {token}

Response:

{
  "journey_id": "...",
  "encounter_id": "ENC20251214001",
  "patient": "Mohammed Ali",
  "journey_type": "opd",
  "status": "active",
  "completion_percentage": 50,
  "is_complete": false,
  "started_at": "2025-12-14T09:00:00Z",
  "completed_at": null,
  "stages": [
    {
      "name": "MD Consultation",
      "order": 1,
      "status": "completed",
      "completed_at": "2025-12-14T10:45:00Z",
      "survey_sent": true
    },
    {
      "name": "Laboratory",
      "order": 2,
      "status": "completed",
      "completed_at": "2025-12-14T14:30:00Z",
      "survey_sent": true
    },
    {
      "name": "Radiology",
      "order": 3,
      "status": "pending",
      "completed_at": null,
      "survey_sent": false
    },
    {
      "name": "Pharmacy",
      "order": 4,
      "status": "pending",
      "completed_at": null,
      "survey_sent": false
    }
  ]
}

Stage Instances

List Stage Instances

GET /api/journeys/stage-instances/
Authorization: Bearer {token}

Query Parameters:

  • journey_instance - Filter by journey instance UUID
  • stage_template - Filter by stage template UUID
  • status - Filter by status (pending, in_progress, completed, skipped)

Integrations

Inbound Events

Create Event (External Systems)

POST /api/integrations/events/
Authorization: Bearer {token}
Content-Type: application/json

{
  "source_system": "his",
  "event_code": "OPD_VISIT_COMPLETED",
  "encounter_id": "ENC20251214001",
  "patient_identifier": "MRN123456",
  "payload_json": {
    "physician_license": "PHY001",
    "department_code": "DEPT_OPD",
    "visit_date": "2025-12-14",
    "visit_time": "10:30:00",
    "timestamp": "2025-12-14T10:45:00Z"
  }
}

Response:

{
  "id": "EVENT_UUID",
  "source_system": "his",
  "event_code": "OPD_VISIT_COMPLETED",
  "encounter_id": "ENC20251214001",
  "status": "pending",
  "received_at": "2025-12-14T10:45:01Z"
}

Note: Event is queued for async processing by Celery.

Bulk Create Events

POST /api/integrations/events/bulk_create/
Authorization: Bearer {token}
Content-Type: application/json

{
  "events": [
    {
      "source_system": "his",
      "event_code": "OPD_VISIT_COMPLETED",
      "encounter_id": "ENC001",
      "patient_identifier": "MRN001",
      "payload_json": {...}
    },
    {
      "source_system": "lab",
      "event_code": "LAB_ORDER_COMPLETED",
      "encounter_id": "ENC001",
      "patient_identifier": "MRN001",
      "payload_json": {...}
    }
  ]
}

Response:

{
  "created": 2,
  "failed": 0,
  "errors": []
}

List Events (PX Admin Only)

GET /api/integrations/events/
Authorization: Bearer {token}

Query Parameters:

  • status - Filter by status (pending, processing, processed, failed, ignored)
  • source_system - Filter by source system
  • event_code - Filter by event code
  • encounter_id - Filter by encounter ID

Reprocess Failed Event (PX Admin Only)

POST /api/integrations/events/{event_id}/reprocess/
Authorization: Bearer {token}

Integration Configurations (PX Admin Only)

List Integration Configs

GET /api/integrations/configs/
Authorization: Bearer {token}

Create Integration Config

POST /api/integrations/configs/
Authorization: Bearer {token}
Content-Type: application/json

{
  "name": "HIS Integration",
  "source_system": "his",
  "description": "Hospital Information System",
  "api_url": "https://his.hospital.sa/api/",
  "api_key": "secret_key_here",
  "is_active": true,
  "config_json": {
    "timeout": 30,
    "retry_attempts": 3
  }
}

Common Response Codes

  • 200 OK - Success
  • 201 Created - Resource created
  • 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

Pagination

All list endpoints support pagination:

GET /api/organizations/patients/?page=2&page_size=50

Response:

{
  "count": 150,
  "next": "http://localhost:8000/api/organizations/patients/?page=3",
  "previous": "http://localhost:8000/api/organizations/patients/?page=1",
  "results": [...]
}

Filtering & Search

Filtering

GET /api/journeys/instances/?status=active&hospital=HOSPITAL_UUID

Search

GET /api/organizations/patients/?search=mohammed

Ordering

GET /api/journeys/instances/?ordering=-started_at

Error Responses

Validation Error

{
  "field_name": [
    "This field is required."
  ]
}

Permission Denied

{
  "detail": "You do not have permission to perform this action."
}

Not Found

{
  "detail": "Not found."
}

Interactive Documentation

For interactive API documentation with try-it-out functionality:

Rate Limiting

TODO: Implement rate limiting for:

  • Event creation endpoint: 1000 requests/hour per source system
  • Authentication endpoint: 10 requests/minute per IP
  • Other endpoints: 100 requests/minute per user

Webhooks (Future)

TODO: Implement webhooks for:

  • Journey completion
  • Survey completion
  • Action creation
  • SLA breach

Last Updated: December 14, 2025