Integration Architecture & Data Flow

Endpoint Sequence & Dependencies

The integration involves four primary API endpoints that work together to manage patient visits and payment processing within Cambodia's healthcare system:

Endpoint 1: Authentication

• Purpose: Obtain a secure OAuth 2.0 access token (Bearer token) for authenticating all subsequent API calls to the NPCA platform.
• URL: POST /oauth/token
• When to Use: Before any API call; upon token expiration (via 401 Unauthorized response); or as part of a scheduled refresh cycle.
• Frequency: Initial setup and periodic refresh (tokens are typically valid for 1 hour).
• Dependencies: None. This is the entry point requiring only client credentials.
• Grant Types: Password grant for initial authentication, refresh token for token renewal.

Endpoint 2: Beneficiary Search

• Purpose: Verify if the benefit card exists, validate eligibility status, and retrieve essential demographic information for HEF/NSSF beneficiaries.
• URL: GET /api/v1/external/beneficiary/search
• When to Use: Strongly recommended before visit submission to ensure data linkage, validate coverage, and avoid submission errors.
• Frequency: Once per patient/visit verification, or when patient information needs updating.
• Dependencies: Requires a valid access token from Endpoint 1 and proper facility authorization headers.
• Output: Critical eligibility data including SPID, patient demographics, benefit card status, and coverage information used in Visit Submission payload.

Endpoint 3: Visit Submission

• Purpose: Submit complete or partial clinical visit data for processing, validation, and storage in the NPCA system for payment processing.
• URL: POST /api/v1/external/visits
• When to Use: After successful patient verification (Endpoint 2) and with a valid access token (Endpoint 1).
• Frequency: Once per patient visit event (create/update). IPD cases may require multiple submissions (admission, updates, discharge).
• Dependencies: Requires a valid access token (Endpoint 1), verified patient information (Endpoint 2), and proper facility/system authorization.
• Response: Immediate HTTP 200 with processing status, unique visit_ulid, and visit_code for tracking.

Endpoint 4: Processing Status

• Purpose: Monitor the processing status of submitted visits, track validation results, and retrieve processing outcomes.
• URL: GET /api/v1/external/visits/processed
• When to Use: After visit submission to monitor processing progress, especially for batch submissions or complex cases.
• Frequency: As needed for status monitoring and reconciliation processes.
• Dependencies: Requires valid access token and appropriate query parameters for filtering.
• Output: Processing status, validation results, and any error details for submitted visits.

How EMR Integration Works

Step 1: Beneficiary Lookup & Verification

This is where the healthcare delivery process begins with patient identification and eligibility verification.

• Action: Healthcare staff scans or manually enters the patient's HEF/NSSF benefit card number into the EMR system.
• System Process: EMR calls the Beneficiary Search endpoint with the card number.
• Outcomes:
  • Card Found & Eligible: System retrieves comprehensive patient details including:
    • Demographics (name, address following NCDD standards, contact information)
    • SPID (System Patient ID) for linking visits
    • Benefit program details (HEF-Poor, HEF-Informal, HEF-Risk, NSSF-Employee, etc.)
    • Coverage status and eligibility dates
    • Previous medical history if available
  • Card Not Found: Patient is not registered in the benefit system and would need to pay out-of-pocket or register for coverage.
  • Card Found but Not Eligible: Card exists but coverage may be expired, suspended, or not applicable for the requested services.

Step 2: Clinical Service Delivery

With confirmed eligibility, healthcare providers proceed with clinical care while documenting all activities.

• Patient Registration: EMR system creates or updates patient record using verified demographic information.
• Clinical Documentation: Healthcare providers document all clinical activities including:
  • Triage assessment with vital signs
  • Medical history and physical examination
  • Diagnostic procedures and laboratory tests
  • Treatment plans and medication prescriptions
  • Progress notes and SOAP documentation
• Service Classification: All services are categorized according to payment type eligibility and coverage rules.

Step 3: Visit Data Preparation & Validation

Before submission, the EMR system prepares comprehensive visit data following NPCA standards.

• Data Mapping: EMR maps local data formats to NPCA standard structure including:
  • ICD-10 diagnosis codes for all conditions
  • Standardized medication names and dosages
  • Proper encounter classifications (OPD, IPD, Emergency)
  • Administrative codes for admission/discharge types
• Local Validation: EMR performs pre-submission validation:
  • Required field completeness
  • Data format compliance (dates, codes, numeric values)
  • Clinical logic validation (medication dosages, vital sign ranges)
  • Cross-reference validation between related data elements

Step 4: Benefit Request Submission

The timing and content of submission varies by visit type and payment program.

Submission Timing by Visit Type:

• OPD Visits: Submit after treatment completion with full encounter data
• IPD Admissions: Submit initial data upon admission for pre-authorization
• IPD Discharge: Submit complete visit data including all treatments and outcomes
• Emergency Cases: Submit as soon as clinically appropriate, often after stabilization

EMR Portal Validation Process:

• Pre-submission Checks: EMR validates data completeness and format compliance
• Submission Attempt: System attempts to submit data to NPCA platform
• Response Handling:
  • Success (Status 1): Complete processing, visit accepted and queued for payment
  • Partial Success (Status 3): Some data accepted, additional information may be required
  • Validation Errors: Detailed field-level error messages returned for correction

NPCA Server Processing: After successful EMR validation, the NPCA platform performs comprehensive validation:

• Eligibility Verification: Confirms patient benefit status at time of service
• Coverage Validation: Verifies services are covered under patient's benefit program
• Policy Compliance: Ensures treatments align with coverage policies and clinical guidelines
• Financial Processing: Calculates covered amounts and generates payment authorizations
• Audit Trail: Creates comprehensive audit log for all processing activities

Component Architecture

The API follows a modular, healthcare-standards-compliant architecture with interconnected components representing different aspects of healthcare delivery:

Core Architecture Principles

• Modular Design: Each component serves a specific healthcare function while maintaining interoperability
• Standards Compliance: Adherence to ICD-10, ISO 8601, and NCDD demographic standards
• Extensibility: Flexible structure accommodates various healthcare scenarios and future enhancements
• Data Integrity: Comprehensive validation and referential integrity across all components

Component Categories

Patient Story Components

• Understand the comprehensive approach to linking various healthcare components
• Provides context for how individual data elements contribute to complete patient care narratives
• Supports continuity of care across multiple encounters and healthcare providers

Base Components

• Encounters: Fundamental interaction units between patients and healthcare providers
• Observations: Standardized measurement and assessment structures (vital signs, lab results)
• Administrative Elements: Visit types, admission/discharge classifications, payment categories
• Building blocks that support more complex healthcare operations

Core Components

• Patient Management: Demographics, identifications, medical history, and benefit information
• Visit Coordination: Comprehensive visit lifecycle from admission through discharge
• Clinical Documentation: Triage, examinations, diagnoses, treatments, and progress notes
• Financial Integration: Invoicing, payment processing, and benefit claim management
• Essential models that form the backbone of the healthcare information system

Encounter-Specific Components

• Outpatient Services: Same-day care and consultation management
• Inpatient Services: Multi-day hospitalization with comprehensive care coordination
• Emergency Services: Urgent care with rapid assessment and treatment protocols
• Surgical Services: Procedure-specific documentation with detailed operative records
• Supporting structures that accommodate different types of healthcare delivery

Data Model Relationships

The components maintain strict referential integrity through standardized code relationships:

Hierarchical Structure

• Visit Level: Each visit contains patient information and multiple encounter types
• Encounter Level: Each encounter (OPD, IPD, Emergency, Surgery) can have associated:
  • Clinical data (observations, diagnoses, prescriptions, lab results)
  • Administrative data (scheduling, provider assignments, service classifications)
  • Financial data (service charges, medication costs, payment information)

Cross-Reference Validation

• Patient Codes: Unique identifiers linking all patient-related data across encounters
• Visit Codes: Facility-specific identifiers for tracking complete episodes of care
• Encounter Codes: Specific identifiers for individual service events within visits
• Provider Codes: Healthcare professional identifiers for accountability and audit trails

Implementation Considerations

Technical Requirements

• Interoperability: Designed for seamless integration with diverse EMR systems
• Performance: Optimized for high-volume healthcare environments with concurrent users
• Reliability: Robust error handling and retry mechanisms for critical healthcare data
• Security: End-to-end encryption and comprehensive audit logging for patient data protection

Cambodia-Specific Adaptations

• Administrative Divisions: Support for Province, District, Commune, Village hierarchies per NCDD standards
• Healthcare Facility Structure: Integration with national facility registration and coding systems
• Payment Programs: Native support for HEF and NSSF benefit structures and processing rules
• Language Support: Khmer language support for patient names and clinical documentation

Scalability Features

• Flexible Data Model: Accommodates various healthcare specialties and service types
• Batch Processing: Support for high-volume data submission and processing
• Real-time Integration: Immediate validation and response for critical healthcare decisions
• Audit Compliance: Comprehensive logging for regulatory compliance and quality assurance

Key Integration Features

Clinical Documentation

• Comprehensive Medical Records: Complete patient history tracking across all encounters
• Standardized Observations: Flexible model accommodating various clinical measurements and assessments
• Multi-Provider Coordination: Support for care teams and referral management between facilities
• Quality Metrics: Built-in support for clinical quality indicators and outcome tracking

Financial Integration

• Real-time Benefit Verification: Immediate eligibility checking and coverage validation
• Automated Claims Processing: Seamless integration between clinical documentation and payment systems
• Multi-Program Support: Unified handling of HEF and NSSF benefit programs with different coverage rules
• Financial Reconciliation: Comprehensive tracking and reporting for healthcare facility financial management

Operational Efficiency

• Workflow Optimization: Streamlined processes reducing administrative burden on healthcare providers
• Error Prevention: Comprehensive validation preventing common data submission errors
• Status Monitoring: Real-time tracking of submission and processing status for operational visibility
• Integration Support: Comprehensive documentation and technical support for EMR vendors and healthcare facilities