NPHIES Integration (تكامل نفيس)

Saudi National Platform for Health Electronic Exchange Services integration module. Supports FHIR R4 messaging for eligibility checks, prior authorizations, and claim submissions.

Overview

Feature	Status
Module Setup & Config	Done
FHIR Client (mTLS, Bundle builder)	Done
Transaction Logging	Done
Eligibility Check	Done
Prior Authorization	Done
Claim Submission	Done
Polling & Cancel	Done

Configuration

Endpoints

Method	Endpoint	Description
GET	/api/nphies/config	Get NPHIES configuration
PUT	/api/nphies/config	Update configuration
POST	/api/nphies/test-connection	Test NPHIES connectivity
POST	/api/nphies/upload-certificate	Upload mTLS certificate + key

Configuration Fields

Field	Type	Description
provider_license	string	NPHIES provider license number
facility_nphies_id	string	Facility ID registered with NPHIES
sandbox_mode	boolean	Use sandbox endpoint (default: true)
is_active	boolean	Enable NPHIES integration
sender_id	string	Provider organization identifier
receiver_id	string	Payer/NPHIES organization identifier

Certificate Upload

mTLS authentication is required for NPHIES. Upload certificate and private key files:

POST /api/nphies/upload-certificate
Content-Type: multipart/form-data

certificate: [.pem file]
private_key: [.pem file]

Transaction Log

Method	Endpoint	Description
GET	/api/nphies/transactions	List transactions
GET	/api/nphies/transactions/{id}	Get transaction detail

Query Parameters

Param	Type	Description
type	string	eligibility, preauth, claim, cancel, poll
status	string	pending, queued, success, error, timeout
patient_id	integer	Filter by patient
date_from	date	From date
date_to	date	To date

Permissions

Permission	Description
nphies.config.view	View NPHIES configuration
nphies.config.manage	Manage config, test connection, upload certs
nphies.transactions.view	View transaction logs
nphies.eligibility.check	Run eligibility checks
nphies.preauth.submit	Submit prior authorizations
nphies.claim.submit	Submit claims
nphies.cancel	Cancel transactions
nphies.poll	Poll for pending responses

Eligibility Check

Endpoint

Method	Endpoint	Description
POST	/api/nphies/eligibility	Check patient insurance eligibility

Request Body

Field	Type	Required	Description
patient_id	integer	Yes	Patient ID (must have national_id)
insurer_code	string	Yes	Insurance company NPHIES code
service_date	date	No	Service date (defaults to today)

Response

{
  "data": {
    "eligible": true,
    "disposition": "Patient is eligible",
    "benefits": [...],
    "transaction_id": 1,
    "error": null
  }
}

Prior Authorization

Endpoints

Method	Endpoint	Description
POST	/api/nphies/preauth	Submit prior authorization
GET	/api/nphies/preauths	List preauthorizations
GET	/api/nphies/preauths/{id}	Get preauth detail

Request Body (POST)

Field	Type	Required	Description
patient_id	integer	Yes	Patient ID
lab_request_id	integer	Yes	Lab request ID
insurer_code	string	Yes	Insurance company code
diagnosis_code	string	Yes	ICD-10-AM diagnosis code
investigation_ids	array	Yes	Investigation IDs to authorize

Response

{
  "data": {
    "approved": true,
    "preauth_ref": "PA-12345",
    "valid_from": "2026-04-03",
    "valid_to": "2026-05-03",
    "items": [{"sequence": 1, "approved_amount": 50}],
    "total_approved": 50.000,
    "transaction_id": 2,
    "preauth_id": 1,
    "error": null
  }
}

Architecture