Uhi
UHI Physical Consultation Integration — Overview
What is UHI?
The Unified Health Interface (UHI) is an open protocol developed by India's National Health Authority (NHA) to enable interoperability across healthcare applications. It allows any patient app (EUA) to discover doctors, book appointments, and communicate with any clinic system (HSPA) on the network — regardless of which software each party uses.
Kulcare participates in UHI in both roles:
| Role | Acronym | Description |
|---|---|---|
| End User Application | EUA | Patient-facing app that searches for doctors and books appointments |
| Health Service Provider Application | HSPA | Clinic-facing app that lists doctors, holds slots, and confirms bookings |
Supported Service Types
| Service | UHI Domain | Credentials Path |
|---|---|---|
| Physical Consultation | nic2004:85111 | uhi.tele_physical_consultation |
| Tele Consultation | nic2004:85121 | uhi.tele_physical_consultation |
| PMJAY | nic2004:85131 | uhi.pmjay |
Architecture
┌──────────────────────────────────────────────────────────────────────┐
│ UHI Network │
│ │
│ ┌─────────────┐ broadcast ┌─────────────────────────────┐ │
│ │ UHI Gateway │ ──────────────── │ HSPAs (other clinics) │ │
│ │ (NHA) │ │ hspasbx.abdm.gov.in │ │
│ └──────┬──────┘ └─────────────────────────────┘ │
│ │ │
│ │ auth + route │
│ │ │
│ ┌──────▼──────────────────────────────────────────────────────┐ │
│ │ Kulcare Platform │ │
│ │ │ │
│ │ EUA Role (api-stg.kulcare.com/uhi/*) │ │
│ │ ├── Outbound: search, init, confirm, status, cancel │ │
│ │ └── Inbound: on_search, on_init, on_confirm, ... │ │
│ │ │ │
│ │ HSPA Role (api-stg.kulcare.com/uhi/*) │ │
│ │ ├── Inbound: search, init, confirm, status, cancel │ │
│ │ └── Outbound: on_search, on_init, on_confirm, ... │ │
│ └──────────────────────────────────────────────────────────────┘ │
└──────────────────────────────────────────────────────────────────────┘Five Phases
| Phase | Stage | Key Actions |
|---|---|---|
| Phase 1 | Foundation | Auth service, Network Registry lookup, base callbacks |
| Phase 2 | Discovery | /search broadcast → on_search catalog responses |
| Phase 3 | Booking | /init + /confirm → on_init T&C + on_confirm PIN |
| Phase 4 | Fulfilment | /status queries + on_update state pushes |
| Phase 5 | Post-Fulfilment | /cancel + on_cancel + on_message chat |
Code Location
backend/domains/uhi/
├── routes.rb
├── migrations/
│ ├── 20260420000001_create_uhi_requests.rb
│ └── 20260420000002_create_uhi_webhooks.rb
├── models/
│ ├── uhi_request.rb # Outbound API call log
│ └── uhi_webhook.rb # Inbound webhook log
├── services/
│ ├── auth_service.rb # Ed25519 + BLAKE-512 signing
│ ├── uhi_logger.rb # Logging service
│ ├── network_registry_service.rb
│ ├── search_service.rb
│ ├── catalog_service.rb
│ ├── booking_service.rb
│ ├── audit_service.rb
│ ├── status_service.rb
│ ├── cancellation_service.rb
│ └── messaging_service.rb
└── controllers/
├── uhi_controller.rb # Base (signature verification)
├── eua/ # Uhi::Eua::*
│ ├── search_controller.rb
│ ├── booking_controller.rb
│ ├── status_controller.rb
│ ├── cancellation_controller.rb
│ ├── messages_controller.rb
│ ├── network_registry_controller.rb
│ └── on_*.rb # 7 callback controllers
└── hspa/ # Uhi::Hspa::*
├── search_controller.rb
├── init_controller.rb
├── confirm_controller.rb
├── status_controller.rb
└── cancel_controller.rb