# 🏥 SHA Portal Preauth Integrations Guide

📋 Overview

Integration guide for submitting preauthorizations to SHA Portal Health Information Exchange using FHIR R4.

Base URL: https://uat.dha.go.ke

🔐 Authentication

Include Bearer token in all requests. Get your credentials from the Afyalink developer self onboarding portal at https://developer.dha.go.ke

Authorization: Bearer {access_token}

🔗 API Endpoints

1. Submit Preauthorization Bundle

📤 POST https://uat.dha.go.ke/v1/shr-med/bundle

Submit preauthorization with patient, coverage, organization, and claim data.

📦 Minimal Request Body

{
  "resourceType": "Bundle",
  "type": "transaction",
  "entry": [
    {
      "resource": {
        "resourceType": "Patient",
        "identifier": [{"system": "http://sha.go.ke/patient-id", "value": "SHA123456789"}],
        "name": [{"family": "Doe", "given": ["John"]}],
        "gender": "male",
        "birthDate": "1980-01-01"
      },
      "request": {"method": "POST", "url": "Patient"}
    },
    {
      "resource": {
        "resourceType": "Organization", 
        "identifier": [{"system": "http://sha.go.ke/facility-id", "value": "FAC001"}],
        "name": "Nairobi Hospital"
      },
      "request": {"method": "POST", "url": "Organization"}
    },
    {
      "resource": {
        "resourceType": "Coverage",
        "status": "active",
        "beneficiary": {"reference": "Patient/patient-001"},
        "payor": [{"reference": "Organization/org-001"}]
      },
      "request": {"method": "POST", "url": "Coverage"}
    },
    {
      "resource": {
        "resourceType": "Claim",
        "status": "active",
        "type": {"coding": [{"system": "http://terminology.hl7.org/CodeSystem/claim-type", "code": "professional"}]},
        "use": "preauthorization",
        "patient": {"reference": "Patient/patient-001"},
        "created": "2025-07-10T10:00:00Z",
        "insurer": {"reference": "Organization/org-001"},
        "provider": {"reference": "Organization/org-001"},
        "item": [{
          "sequence": 1,
          "productOrService": {"coding": [{"system": "http://www.ama-assn.org/go/cpt", "code": "99213"}]},
          "unitPrice": {"value": 150.00, "currency": "KES"}
        }]
      },
      "request": {"method": "POST", "url": "Claim"}
    }
  ]
}

✅ Response (200 OK)

{
  "message": {
    "mediator_id": "30f8d4d4-5d6f-42af-9cee-fc5656effd27",
    "message": "Use this reference ID to use for Polling for the status of your Resource.",
    "claim_ids": [
      "270ef1f5-d36d-471b-b12f-c8fb41dd294e"
    ]
  }
}

2. Check Claim Status

📊 GET https://uat.dha.go.ke/v1/shr-med/claim-status?claim_id={claim_id}

Check preauthorization status using claim_id from bundle response.

🔍 Request Example

GET https://uat.dha.go.ke/v1/shr-med/claim-status?claim_id=270ef1f5-d36d-471b-b12f-c8fb41dd294e

✅ Response (200 OK)

{
  "message": [
    {
      "claim_id": "b4466a63-7bfa-4f2c-bffe-91aae33ddcd2",
      "claim_status": "failed_dispatch",
      "response": "HTTP ERROR",
      "claim_upstream_response": null
    },
    {
      "errors": [
        {
          "message": "HTTP Error: {...}",
          "verbose_error": "Error while processing Organization for claim ID https://qa-sha.apeiro-digital.com/fhir/Claim/b4466a63-7bfa-4f2c-bffe-91aae33ddcd2. Cause: Mismatch in Facility Level: HIE has 'LEVEL 3A', but Provider has 'LEVEL 3B'. [Facility ID: FID-20-114807-9]"
        }
      ]
    }
  ]
}

📈 Status Values:

• Success: Claim processed successfully

• Failed: Claim processing failed

• Received: Claim received, not yet processed

• In Process: Currently being processed

• Pending Consultant Review: Awaiting consultant review

• Rejected by Consultant: Consultant rejected the claim

• Processing: In processing state

• failed_dispatch: Failed to dispatch to upstream payer system

⚠️ Error Handling

API errors return simple JSON format with error details:

{
  "error": "Error while processing Organization for claim ID https://fhir.sha.go.ke/fhir/Claim/afbc2d7c-2ce0-45a7-8ca3-3b54d32ac001. Cause: Provider not found in SAFARICOM HIE for identifier: XXXX"
}

Common Status Codes: 200 (OK), 400 (Bad Request), 401 (Unauthorized), 404 (Not Found)

💡 Implementation Notes

1. Required Identifiers: Patient (CR ID), Organization (Facility ID)
2. Content-Type: application/fhir+json
3. Currency: Use "KES" for Kenya Shillings
4. Dates: ISO 8601 format
5. Testing: Use staging environment for development

🆘 Support

• 📧 Email: [email protected]
• 📚 Docs: https://kps.dha.go.ke/artifacts.html
• 🚀 Afyalink Onboarding Portal Docs: https://afyalink.dha.go.ke/wiki/afyalink-documentation
• 📋 Claims Submission Guide: https://afyalink.dha.go.ke/claim-integration