devsofttech_hms_ci4/docs/ABDM_QUICK_START.md

ABDM Sandbox Integration — Quick Start Guide

Approved: May 12, 2026
Client ID: SBXID_033661
Integration Mode: DreamSoft Middleware (csnotk.e-atria.in)

---

🎯 What's Ready

Your HMS application now has:

✅ ABDM Sandbox Credentials Configured

• Client ID: SBXID_033661
• Client Secret: Configured in .env
• Middleware Gateway: https://csnotk.e-atria.in

✅ ABDM Controllers Ready

• ABHA validation endpoint
• Consent request/callback handlers
• Bundle push for OPD, Lab, Discharge
• FHIR bundle generation

✅ OPD Enhancements for ABDM

• ABHA number input field
• SNOMED CT diagnosis/complaint coding
• Vitals with proper units
• Medicine SNOMED/ATC coding
• Recent patient entries chips (for faster data reuse)

✅ Documentation Created

• docs/ABDM_SANDBOX_SETUP.md — Complete integration guide
• docs/ABDM_SANDBOX_CHECKLIST.md — Testing checklist
• This quick start guide

---

🚀 Immediate Next Steps

Step 1: Get Missing Bearer Token (BLOCKING)

Contact your middleware provider (CSNOtk/DreamSoft) to obtain:

BRIDGE_SYNC_TOKEN = <your-bearer-token>

Once received, update .env:

BRIDGE_SYNC_TOKEN = your-token-here

Step 2: Register in ABDM Sandbox

1. Go to: https://sandbox.abdm.gov.in
2. Register your organization with Client ID: SBXID_033661
3. Note your HFR ID (Health Facility Registry ID)
4. Note your NPI (National Practitioner Identifier)

Step 3: Update .env with Your IDs

ABDM_HFR_ID = your-hfr-id
ABDM_NPI_ID = your-npi-id

Step 4: Get Test ABHA Numbers

From ABDM sandbox portal, get 2-3 test ABHA numbers, e.g.:

14-0061-0000-0001
14-0061-0000-0002
14-0061-0000-0003

Step 5: Create Test Patient in HMS

Patient Name: Test Patient
ABHA Number: 14-0061-0000-0001
Gender: Male
Age: 35

---

🧪 Testing Sequence

Test 1: Verify Middleware Connectivity (2 min)

curl -H "Authorization: Bearer YOUR_TOKEN" \
  https://csnotk.e-atria.in/api/bridge/status
# Should return: {"status": "ok"}

Test 2: ABHA Validation (5 min)

1. Open OPD Consult form in HMS
2. Create new patient → Enter ABHA: 14-0061-0000-0001
3. Click "Validate ABHA"
4. Expected: ✅ ABHA linked successfully

Test 3: SNOMED Terminology (3 min)

1. In Diagnosis field → Type: fever
2. Click search icon
3. Expected: Dropdown shows SNOMED codes via csnotk
4. Select one → SNOMED ID auto-fills

Test 4: OPD Consult Creation (10 min)

1. Fill OPD form:
   • Complaints: Fever and cough
   • Vital Signs: BP 120/80, Pulse 72, Temp 37.5°C
   • Diagnosis: Select fever (SNOMED)
   • Prescription: Add 1-2 medicines
2. Click "Save & Submit"
3. Check database:

   SELECT opd_id, fhir_bundle_id, abdm_push_status 
   FROM opd_prescription 
   ORDER BY id DESC LIMIT 1;
   

4. Expected: fhir_bundle_id populated, abdm_push_status = 0

Test 5: Consent Request (5 min)

1. Open saved OPD record
2. Scroll to "ABDM Actions" section
3. Click "Request Consent"
4. Check sandbox portal for consent request
5. Expected: Consent request appears in ABDM sandbox

Test 6: Accept Consent in Sandbox (2 min)

1. Login to https://sandbox.abdm.gov.in with test account
2. Navigate to "Consent Requests"
3. Accept the request from your HMS
4. Expected: Status changes to "GRANTED"

Test 7: Push Bundle to ABDM (3 min)

1. After consent granted in HMS, refresh page
2. Click "Share Records" → "Push to ABDM"
3. Check ABDM sandbox for record appearance
4. Expected: ✅ Record pushed successfully

---

📊 Dashboard Access

Once configured, access ABDM features via:

1. OPD Consult → Bottom section "ABDM Actions"

   • Link ABHA
   • Request Consent
   • Share Records

2. ABDM Task Board → Menu → "ABDM"

   • View all ABDM operations
   • Monitor consent status
   • Check bundle push history

3. Patient Profile → "ABHA" tab

   • View linked ABHA
   • History of shares

---

🔑 Key API Endpoints (for your reference)

Operation	Endpoint	Method
ABHA Validate	/AbdmGateway/abha_validate	POST
Consent Request	/AbdmGateway/consent_request	POST
Push OPD	/AbdmGateway/share_prescription_bundle	POST
Push Lab	/AbdmGateway/share_diagnosis_report_bundle	POST
Push Discharge	/AbdmGateway/share_ipd_discharge_bundle	POST

---

⚠️ Common Issues & Fixes

Issue: "Middleware unreachable"

BRIDGE_SYNC_URL = https://csnotk.e-atria.in/api/bridge
BRIDGE_SYNC_TOKEN = <missing-or-invalid>

Fix:

1. Verify .env has correct URL and token
2. Contact middleware provider for token
3. Check firewall allows HTTPS outbound

Issue: "ABHA validation stuck in 'pending'"

Fix:

1. Verify ABHA number exists in sandbox
2. Check token has permission for ABHA operations
3. Check logs: writable/logs/log-*.log

Issue: "SNOMED code not found in diagnosis"

Fix:

1. Ensure CSNOtk service is responding
2. Try common term: fever, cough, headache
3. Check: snomed.csnotk.baseUrl in .env

Issue: "Consent never shows 'GRANTED' status"

Fix:

1. Login to ABDM sandbox portal
2. Navigate to "Consent Requests" section
3. Manually accept the request (for testing)
4. Refresh HMS page — status updates

---

📋 Configuration Summary

Current State:

Environment:         development
ABDM Connector:      dreamsoft
Middleware URL:      https://csnotk.e-atria.in
SNOMED Service:      https://csnotk.e-atria.in/csnoserv
Direct ABDM URL:     https://dev.abdm.gov.in/api/v3

Sandbox Credentials:

Client ID:           SBXID_033661
Client Secret:       656f79f1-ef99-495f-9f37-713219ecbbcf
Mode:                Approved & Ready

Still Needed:

• Bearer token for middleware
• HFR ID from facility registration
• NPI ID for practitioner
• Test ABHA numbers from sandbox

---

📞 Support

Middleware Support

• Provider: CSNOtk / DreamSoft
• URL: https://csnotk.e-atria.in
• Contact: Check middleware provider documentation

ABDM Sandbox Support

• Portal: https://sandbox.abdm.gov.in
• Docs: https://sandbox.abdm.gov.in/sandbox/v3/new-documentation
• API Docs: NHA ABDM M3 Integration Guide

Application Logs

Check for errors:

tail -f writable/logs/log-*.log

---

🎓 Learning Path

1. Day 1: Complete steps 1-4 (get credentials)
2. Day 2: Run Tests 1-2 (connectivity & ABHA)
3. Day 3: Run Tests 3-4 (SNOMED & OPD creation)
4. Day 4: Run Tests 5-7 (full consent → push flow)
5. Day 5+: Move to Phase 2 (database schema additions)

---

Status: 🟢 Ready for Sandbox Testing
Last Updated: May 12, 2026

---

Quick Reference: .env Configuration

# ABDM Sandbox Mode
abdm.connector = dreamsoft

# Direct API Fallback
abdm.directClientId = SBXID_033661
abdm.directClientSecret = 656f79f1-ef99-495f-9f37-713219ecbbcf
abdm.directBaseUrl = https://dev.abdm.gov.in/api/v3

# Middleware Gateway (DreamSoft)
BRIDGE_SYNC_URL = https://csnotk.e-atria.in/api/bridge
BRIDGE_SYNC_TOKEN = <TO_BE_OBTAINED>
BRIDGE_SOURCE_CODE = SBXID_033661
BRIDGE_SYNC_TIMEOUT = 20

# SNOMED CT Terminology
snomed.csnotk.baseUrl = https://csnotk.e-atria.in/csnoserv
snomed.csnotk.enabled = true
snomed.csnotk.timeoutSec = 10

# Facility Details
ABDM_HFR_ID = <TO_BE_OBTAINED>
ABDM_NPI_ID = <TO_BE_OBTAINED>

---

Ready to proceed? → Start with Step 1 above! 🚀