API Endpoints

The NPCA EMR Clinical Data Submission API provides endpoints to manage patient visits, authentication, beneficiary search, and processing status. All endpoints require proper authentication and specific headers.

ចំណុចតភ្ជាប់សាធារណៈ

ចំណុចតភ្ជាប់ទាំងនេះអាចចូលប្រើបានជាសាធារណៈ ហើយមិនត្រូវការការផ្ទៀងផ្ទាត់ទេ។

1. ទទួលបានទិន្នន័យស្តង់ដារ

ទទួលបានប្រភេទទិន្នន័យស្តង់ដារផ្សេងៗដែលប្រើប្រាស់នៅទូទាំងប្រព័ន្ធដោយមិនចាំបាច់ការផ្ទៀងផ្ទាត់។

វាល	តម្លៃ
URL	`GET /v1/external/common/standard-data`
ការផ្ទៀងផ្ទាត់	មិនត្រូវការ
ប៉ារ៉ាម៉ែត្រសំណួរ	`type` (ចាំបាច់), `per_page` (ស្រេចចិត្ត), `query` (ស្រេចចិត្ត)

ប្រភេទទិន្នន័យដែលមាន:

marital_statuses - ជម្រើសស្ថានភាពអាពាហ៍ពិពាហ៍
admission_types - ប្រភេទការចូលមន្ទីរពេទ្យ
visit_types - ប្រភេទនៃការពិនិត្យព្យាបាល (OPD, IPD, Emergency)
discharge_types - ប្រភេទការចេញពីមន្ទីរពេទ្យ
visit_outcomes - ការចាត់ថ្នាក់លទ្ធផលការពិនិត្យ
diagnosis_types - ប្រភេទនៃការធ្វើរោគវិនិច្ឆ័យ (បឋម, បន្ទាប់បន្សំ, ។ល។)
payment_types - ជម្រើសវិធីសាស្ត្រទូទាត់
card_types - ប្រភេទកាតធានារ៉ាប់រង/អត្ថប្រយោជន៍
nationalities - ជម្រើសសញ្ជាតិ
diagnoses - កូដរោគវិនិច្ឆ័យនិងការពិពណ៌នា
health_facilities - ព័ត៌មានអំពីមន្ទីរពេទ្យ
medications - ថ្នាំនិងឱសថដែលមាន

ប៉ារ៉ាម៉ែត្រសំណួរ:

type (ចាំបាច់): ប្រភេទទិន្នន័យស្តង់ដារដែលត្រូវទទួល
per_page (ស្រេចចិត្ត): ចំនួនកំណត់ត្រាក្នុងមួយទំព័រ (លំនាំដើម: 100)
query (ស្រេចចិត្ត): ពាក្យស្វែងរកដើម្បីត្រងលទ្ធផល

ឧទាហរណ៍សំណើ:

bash

curl -X GET "https://demo-authena.pmrs2.org/api/v1/external/common/standard-data?type=diagnoses&per_page=50&query=fever" \
  -H "Accept: application/json"

ឧទាហរណ៍ចម្លើយ:

json

{
  "success": true,
  "http_code": 200,
  "message": "Data retrieved successfully",
  "data": {
    "current_page": 1,
    "data": [
      {
        "code": "R50",
        "name": "Fever, unspecified",
        "description": "Elevated body temperature of unknown origin"
      },
      {
        "code": "A01.0",
        "name": "Typhoid fever",
        "description": "Infection caused by Salmonella typhi"
      }
    ],
    "per_page": 50,
    "total": 125,
    "last_page": 3
  }
}

ចំណុចតភ្ជាប់ទិន្នន័យ

ចំណុចតភ្ជាប់ទិន្នន័យទាំងអស់ត្រូវការការផ្ទៀងផ្ទាត់និងក្បាលជាក់លាក់។

ក្បាលដែលត្រូវការសម្រាប់ចំណុចតភ្ជាប់ទិន្នន័យ

http

Authorization: Bearer {access_token}
Accept: application/json
Content-Type: application/json
X-System-Code: {system_code}
X-Health-Facility-Code: {facility_code}

2. ស្វែងរកអ្នកទទួលអត្ថប្រយោជន៍

Search for beneficiary information using card number.

Field	Value
URL	`GET /api/v1/external/beneficiary/search`
Authentication	Bearer Token Required
Query Parameters	`card_number` (required)

Example Request:

bash

curl -X GET "https://demo-authena.pmrs2.org/api/v1/external/beneficiary/search?card_number=160498163" \
  -H "Authorization: Bearer {access_token}" \
  -H "Accept: application/json" \
  -H "X-System-Code: SHCH" \
  -H "X-Health-Facility-Code: 121020"

Response Fields:

spid: String - System Patient ID
patient_code: String - Unique patient identifier
surname: String - Patient's surname
name: String - Patient's given name
sex: String - Patient's gender (M/F)
birthdate: String (YYYY-MM-DD) - Date of birth
phone_number: String - Contact phone number
nationality: String - Patient's nationality
relationship_to_head: String - Relationship to household head
dead: Boolean - Death status
death_date: DateTime - Date of death (if applicable)
created_at: DateTime - Record creation timestamp
updated_at: DateTime - Last update timestamp
address: Object - Address information
benefit_cards: Array - Benefit card information
identifications: Array - Identification documents
occupation: String - Patient's occupation
disabilities: Array - List of disabilities

3. បញ្ជូនទិន្នន័យការពិនិត្យ

Submit comprehensive patient visit data including encounters, diagnoses, and treatments.

Field	Value
URL	`POST /api/v1/external/visits`
Authentication	Bearer Token Required
Content-Type	`application/json`

Example Request:

bash

curl -X POST https://demo-authena.pmrs2.org/api/v1/external/visits \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "X-System-Code: SHCH" \
  -H "X-Health-Facility-Code: 121020" \
  -d @visit_data.json

4. ទទួលបានស្ថានភាពដំណើរការ

Retrieve the processing status of submitted visits with pagination support.

Field	Value
URL	`GET /api/v1/external/visits/processed`
Authentication	Bearer Token Required

Query Parameters:

per_page: Number of records per page (default: 10)
discharged_at_from: Filter by discharge date from (YYYY-MM-DD)
discharged_at_to: Filter by discharge date to (YYYY-MM-DD)
admitted_at_from: Filter by admission date from (YYYY-MM-DD)
admitted_at_to: Filter by admission date to (YYYY-MM-DD)
processing_status: Filter by processing status
sort_by: Field to sort by
sort_direction: Sort direction (asc/desc)

Example Request:

bash

curl -X GET "https://demo-authena.pmrs2.org/api/v1/external/visits/processed?per_page=4" \
  -H "Authorization: Bearer {access_token}" \
  -H "Accept: application/json" \
  -H "X-System-Code: SHCH" \
  -H "X-Health-Facility-Code: 121020"

រចនាសម្ព័ន្ធនៃខ្លឹមសារស្នើសុំ

The visit submission endpoint accepts a comprehensive JSON structure containing all patient visit data. Below is the complete structure with all available components:

json

{  
  "visits": [{  
    "health_facility_code": "121020",
    "patient_code": "P25003877",
    "code": "V420650",
    "admission_type": "Self Refer",
    "discharge_type": "Authorized",
    "visit_outcome": "Improved",
    "visit_type": "OPD",
    "admitted_at": "2025-03-17T09:30:00.000+07:00",
    "discharged_at": "2025-03-17T10:45:00.000+07:00",
    "followup_at": "2025-03-24T09:00:00.000+07:00",
    "created_at": "2025-03-17T09:30:00.000+07:00",
    "updated_at": "2025-03-17T10:45:00.000+07:00",
    
    "patient": {
      "code": "PT20250317001",
      "surname": "Smith",
      "name": "John",
      "sex": "M",
      "birthdate": "1980-05-15",
      "phone": "012 345 678",
      "nationality": "Cambodian",
      "disabilities": ["Hearing impairment"],
      "occupation": "Teacher",
      "marital_status": "Married",
      "photos": ["https://hospital.example/photos/PT20250317001_1.jpg"],
      "address": {
        "province": {"code": "12", "name": "Phnom Penh"},
        "district": {"code": "1201", "name": "Chamkar Mon"},
        "commune": {"code": "120101", "name": "Tonle Bassac"},
        "village": {"code": "12010101", "name": "Phsar Deum Thkov"},
        "house_number": "45",
        "street_number": "302",
        "location": "Near Central Market 1"
      },
      "identifications": [{
        "patient_code": "P25003877",
        "card_code": "ID123456789",
        "card_type": "National ID"
      }],
      "death_at": null,
      "spid": "250317001",
      "created_at": "2025-03-17T08:30:00.000+07:00",
      "updated_at": "2025-03-17T08:30:00.000+07:00"
    },
    
    "triages": [{
      "parent_code": "P2324",
      "visit_code": "V420650",
      "code": "TR250317",
      "chief_complaint": "Periodic fever with chills for 3 days",
      "height": 170,
      "weight": 65,
      "recorded_at": "2025-03-17T09:32:00.000+07:00",
      "recorded_by": "Khun Srey Mom",
      "title": "Doctor"
    }],
    
    "vital_signs": [{
      "encounter_code": "TR250317",
      "recorded_at": "2025-03-17T09:40:00.000+07:00",
      "recorded_by": "Khun Srey Mom",
      "title": "Doctor",
      "observations": [
        {"name": "Blood Pressure Systolic", "value": 135},
        {"name": "Blood Pressure Diastolic", "value": 85},
        {"name": "Pulse", "value": 92},
        {"name": "Respiratory Rate", "value": 18},
        {"name": "Temperature", "value": 38.7},
        {"name": "SpO2", "value": 97},
        {"name": "Glucose", "value": 110}
      ]
    }],
    
    "medical_histories": [{
      "patient_code": "P25003877",
      "visit_code": "V420650",
      "encounter_code": "E417002",
      "name": "Immunization History",
      "value": ["BCG", "OPV", "DTP", "Measles", "COVID-19"]
    }],
    
    "physical_examinations": [{
      "patient_code": "P25003877",
      "visit_code": "V420650",
      "encounter_code": "EN20250317001",
      "name": "General Appearance",
      "value": "Ill-appearing with intermittent shivering",
      "value_type": "text",
      "value_unit": null
    }],
    
    "outpatients": [{
      "visit_code": "V420650",
      "code": "E417001",
      "name": "General Outpatient",
      "service_type": "General Medicine",
      "started_at": "2025-03-17T09:35:00.000+07:00",
      "ended_at": "2025-03-17T10:15:00.000+07:00",
      "encountered_by": "Dr. Chhun Sovannarith",
      "title": "Doctor"
    }],
    
    "inpatients": [{
      "visit_code": "V420650",
      "code": "E417002",
      "name": "General Inpatient",
      "service_type": "Internal Medicine",
      "started_at": "2025-03-20T14:00:00.000+07:00",
      "ended_at": "2025-03-23T10:00:00.000+07:00",
      "encountered_by": "Dr. Chhun Sovannarith",
      "title": "Doctor"
    }],
    
    "emergencies": [{
      "visit_code": "V420650",
      "code": "E417003",
      "name": "Emergency",
      "service_type_name": "Emergency Medicine",
      "started_at": "2025-03-17T15:30:00.000+07:00",
      "ended_at": "2025-03-17T17:45:00.000+07:00",
      "encountered_by": "Dr. Hor Mony",
      "title": "Doctor"
    }],
    
    "surgeries": [{
      "visit_code": "V420650",
      "parent_code": "E417001",
      "code": "E417004",
      "theater_name": "Operating Theater 2",
      "service_type": "Laparoscopic Cholecystectomy",
      "started_at": "2025-04-01T08:30:00.000+07:00",
      "ended_at": "2025-04-01T10:15:00.000+07:00",
      "reason": "Symptomatic gallstones with recurrent biliary colic",
      "anesthesia_type": "General Endotracheal",
      "procedure_notes": "Patient positioned supine. Pneumoperitoneum established...",
      "complications": ["Mild bleeding from liver bed, controlled with electrocautery"],
      "specimens": ["Gallbladder with multiple stones", "Cystic fluid sample"],
      "blood_loss": "5cl",
      "surgeon_name": "Dr. Sok Vichet",
      "anesthetist_name": "Dr. Meas Sokunthea",
      "assistant_names": ["Dr. Chhan Rathana", "Nurse Van Bopha"]
    }],
    
    "progress_notes": [{
      "visit_code": "V420650",
      "parent_code": "E417001",
      "code": "E317001",
      "started_at": "2025-03-17T16:00:00.000+07:00",
      "ended_at": "2025-03-17T16:15:00.000+07:00",
      "encountered_by": "Dr. Chhun Sovannarith",
      "title": "Doctor"
    }],
    
    "soaps": [{
      "encounter_code": "E417002",
      "subjective": "Patient reports fever has decreased after first dose...",
      "objective": "Temperature 37.8°C (down from 38.7°C). Heart rate 85/min...",
      "assessment": "Uncomplicated malaria showing initial response to treatment...",
      "plan": "Continue artemether-lumefantrine as prescribed...",
      "evaluation": null
    }],
    
    "laboratories": [{
      "patient_code": "P25003877",
      "visit_code": "V420650",
      "encounter_code": "E417002",
      "request_code": "EL23222",
      "requested_at": "2025-03-17T10:30:00.000+07:00",
      "requested_by": "Dr. Chhun Sovannarith",
      "title": "Doctor",
      "collected_at": "2025-03-17T10:30:00.000+07:00",
      "collected_by": "Dr. Chhun Sovannarith",
      "results": [{
        "name": "Malaria Blood Smear",
        "category": "Parasitology",
        "value": "Positive for P. falciparum",
        "value_type": "string",
        "value_unit": null,
        "reference_range": "Negative",
        "interpretation": "Positive",
        "verified_at": "2025-03-17T10:50:00.000+07:00",
        "verified_by": "Dr. Meas Chenda",
        "recorded_at": "2025-03-17T10:52:00.000+07:00",
        "recorded_by": "Meas Chandaravuth"
      }]
    }],
    
    "imageries": [{
      "patient_code": "P25003877",
      "visit_code": "V420650",
      "encounter_code": "E417002",
      "request_code": "EL23222",
      "requested_at": "2025-03-17T11:30:00.000+07:00",
      "requested_by": "Dr. Chhun Sovannarith",
      "title": "Doctor",
      "collected_at": "2025-03-17T10:30:00.000+07:00",
      "collected_by": "Dr. Chhun Sovannarith",
      "results": [{
        "name": "Brain Scan",
        "category": "CT Scan",
        "images": ["img.com/result2.jpg"],
        "result": "Normal brain structure",
        "conclusion": null,
        "verified_at": "2025-03-17T10:50:00.000+07:00",
        "verified_by": "Dr. Meas Chenda",
        "recorded_at": "2025-03-17T10:52:00.000+07:00",
        "recorded_by": "Meas Chandaravuth"
      }]
    }],
    
    "diagnosis": [{
      "patient_code": "P25003877",
      "visit_code": "V420650",
      "encounter_code": "E317001",
      "diagnosis_type_name": "Primary",
      "diagnosis_code": "B50",
      "diagnosis_name": "Plasmodium falciparum malaria",
      "diagnosis_description": "Plasmodium falciparum malaria with cerebral complications",
      "diagnosed_at": "2025-03-17T10:05:00.000+07:00",
      "diagnosed_by": "Dr. Chhun Sovannarith",
      "title": "Doctor"
    }],
    
    "prescriptions": [{
      "patient_code": "P25003877",
      "visit_code": "V420650",
      "encounter_code": "E317001",
      "code": "RX20250317001",
      "prescribed_at": "2025-03-17T10:10:00.000+07:00",
      "prescribed_by": "Dr. Chhun Sovannarith",
      "title": "Doctor",
      "medications": [{
        "code": "MED001",
        "medicine_name": "Artemether-Lumefantrine",
        "strength": "20/120mg",
        "form": "Tablet",
        "method": "Oral",
        "unit": "Tablet",
        "morning": 4,
        "afternoon": 0,
        "evening": 4,
        "night": 0,
        "days": 3,
        "interval": null,
        "note": "Take with food. Complete full course even if feeling better."
      }]
    }],
    
    "referrals": {
      "referred_from": null,
      "referred_to": {
        "code": "REF20250317001",
        "letter_number": "HCPP/REF/2025/317",
        "transportation": "Ambulance",
        "reason": "Severe malaria with signs of organ dysfunction requiring ICU care",
        "has_called": true,
        "caretaker_name": "Sok Channary",
        "caretaker_phone": "012345678",
        "referred_by": "Dr. Chhun Sovannarith",
        "referred_by_phone": "0987654321",
        "referred_at": "2025-03-17T11:30:00.000+07:00",
        "received_by": "0712345678",
        "received_at": "2025-03-17T12:15:00.000+07:00",
        "medications": "Artemether-Lumefantrine 20/120mg (1 dose given at 10:15)"
      }
    },
    
    "invoices": [{
      "patient_code": "P25003877",
      "visit_code": "V420650",
      "encounter_code": "E317001",
      "code": "INV20250317001",
      "payment_type": "HEF",
      "invoice_date": "2025-03-17T11:00:00.000+07:00",
      "total": 120000,
      "cashier": "Sok Kunthea",
      "services": [{
        "invoice_code": "INV20250317001",
        "service_code": "SRV001",
        "service_name": "Blood Smear for Malaria",
        "service_category": "Lab Test",
        "price": 15000,
        "payment": 0,
        "paid": false,
        "discount_type": null,
        "discount": 0
      }],
      "medications": [{
        "invoice_code": "INV20250317001",
        "medicine_code": "MED001",
        "medicine_name": "Artemether-Lumefantrine 20/120mg",
        "quantity": 24,
        "price": 1500,
        "payment": 0,
        "paid": false,
        "discount_type": null,
        "discount": 0
      }]
    }]
  }]  
}

ច្បាប់នៃការធ្វើសុពលភាពទិន្នន័យ

Patient Code: Must be unique system-wide and pre-existing
Visit Code: Must be unique per healthcare facility
Encounter Codes: Must be unique within the EMR system
Date Format: Use ISO 8601 format with timezone (YYYY-MM-DDTHH:mm:ss.sss+07:00)
Empty Values: Use null instead of removing fields
Referral Data: Required when patients are transferred between facilities
Required Fields: All codes, timestamps, and identifiers are mandatory
Array Fields: Can be empty arrays [] but should not be null

ការចាត់ចែងការឆ្លើយតប

Success Responses

Complete Success (Status 1)

json

{
  "success": true,
  "http_code": 200,
  "message": "Save successfully",
  "data": {
    "status": 1,
    "uuld": "unique-identifier-12345",
    "visit_code": "V420650"
  }
}

Submission has been completely stored successfully.

Partial Success (Status 3)

json

{
  "success": true,
  "http_code": 200,
  "message": "Save successfully",
  "data": {
    "status": 3,
    "uuld": "unique-identifier-12345",
    "visit_code": "V420650"
  }
}

Submission has been partially stored successfully and is waiting to be updated.

Error Responses

400 Bad Request

json

{  
  "success": false,  
  "http_code": 400,  
  "message": "Invalid request data",  
  "errors": {
    "visits.0.patient_code": ["The patient code field is required."],
    "visits.0.visit_code": ["The visit code has already been taken."]
  }
}

401 Unauthorized

json

{  
  "success": false,  
  "http_code": 401,  
  "message": "Unauthenticated",  
  "errors": "Invalid or expired token"  
}

403 Forbidden

json

{  
  "success": false,  
  "http_code": 403,  
  "message": "Access denied",  
  "errors": "You do not have permission to create visits for this facility"  
}

422 Unprocessable Entity

json

{
  "success": false,
  "http_code": 422,
  "message": "Validation failed",
  "errors": {
    "visits.0.admitted_at": ["The admitted at field must be a valid date."],
    "visits.0.patient.birthdate": ["The birthdate field must be in YYYY-MM-DD format."]
  }
}

500 Internal Server Error

json

{  
  "success": false,  
  "http_code": 500,  
  "message": "Internal server error",  
  "errors": "An unexpected error occurred while processing your request"  
}

Rate Limiting

The API implements rate limiting to ensure fair usage:

Authentication endpoints: 60 requests per minute per IP
Data endpoints: 1000 requests per hour per authenticated user
Rate limit headers are included in responses:
- X-RateLimit-Limit: Request limit per time window
- X-RateLimit-Remaining: Remaining requests in current window
- X-RateLimit-Reset: Time when the rate limit resets

Testing and Development

Demo Environment

Base URL: https://demo-authena.pmrs2.org
Test Credentials: Provided by NPCA team
Sample Data: Use the example request bodies provided above

Best Practices

Always validate data before submission
Implement retry logic for transient failures
Store tokens securely and refresh before expiration
Log API responses for debugging and monitoring
Use proper error handling for all response codes
Test with sample data before production deployment

API Endpoints ​

ចំណុចតភ្ជាប់សាធារណៈ ​

1. ទទួលបានទិន្នន័យស្តង់ដារ ​

ចំណុចតភ្ជាប់ទិន្នន័យ ​

ក្បាលដែលត្រូវការសម្រាប់ចំណុចតភ្ជាប់ទិន្នន័យ ​

2. ស្វែងរកអ្នកទទួលអត្ថប្រយោជន៍ ​

3. បញ្ជូនទិន្នន័យការពិនិត្យ ​

4. ទទួលបានស្ថានភាពដំណើរការ ​

រចនាសម្ព័ន្ធនៃខ្លឹមសារស្នើសុំ ​

ច្បាប់នៃការធ្វើសុពលភាពទិន្នន័យ ​

ការចាត់ចែងការឆ្លើយតប ​

Success Responses ​

Complete Success (Status 1) ​

Partial Success (Status 3) ​

Error Responses ​

400 Bad Request ​

401 Unauthorized ​

403 Forbidden ​

422 Unprocessable Entity ​

500 Internal Server Error ​

Rate Limiting ​

Testing and Development ​

Demo Environment ​

Best Practices ​

API Endpoints

ចំណុចតភ្ជាប់សាធារណៈ

1. ទទួលបានទិន្នន័យស្តង់ដារ

ចំណុចតភ្ជាប់ទិន្នន័យ

ក្បាលដែលត្រូវការសម្រាប់ចំណុចតភ្ជាប់ទិន្នន័យ

2. ស្វែងរកអ្នកទទួលអត្ថប្រយោជន៍

3. បញ្ជូនទិន្នន័យការពិនិត្យ

4. ទទួលបានស្ថានភាពដំណើរការ

រចនាសម្ព័ន្ធនៃខ្លឹមសារស្នើសុំ

ច្បាប់នៃការធ្វើសុពលភាពទិន្នន័យ

ការចាត់ចែងការឆ្លើយតប

Success Responses

Complete Success (Status 1)

Partial Success (Status 3)

Error Responses

400 Bad Request

401 Unauthorized

403 Forbidden

422 Unprocessable Entity

500 Internal Server Error

Rate Limiting

Testing and Development

Demo Environment

Best Practices