UhiEua
EUA — Phase 4: Fulfilment (Status & State Updates)
The Fulfilment phase covers the appointment lifecycle from confirmation through completion. State changes can be queried (EUA polls HSPA) or pushed (HSPA notifies EUA).
Appointment State Machine
State Ownership
| State | Set By | Mechanism |
|---|---|---|
CONFIRMED | HSPA | on_confirm callback |
APPOINTMENT_STARTED | HSPA | on_update push to EUA |
COMPLETED | HSPA | on_update push to EUA |
CANCELLED | Either | on_cancel callback or on_update push |
NO_SHOW | HSPA | on_update push to EUA |
DOCTOR_NO_SHOW | EUA only | EUA calls HSPA /on_update |
FAILED | HSPA | on_update push (payment/system failure) |
HSPA_OVERRIDE | HSPA | on_update push (started without PIN) |
REFUND_INITIATED | HSPA | on_update push |
Status Query Flow (EUA polls HSPA)
State Push Flow (HSPA notifies EUA)
DOCTOR_NO_SHOW (EUA → HSPA)
This is the only state the EUA can push to the HSPA. Used when the patient attended but the doctor did not appear.
API Endpoints
GET /uhi/bookings/:order_id/status — Query status
Auth required: Yes (Kulcare JWT Bearer token)
Query params / body:
{
"provider_uri": "https://hspasbx.abdm.gov.in/api/v1/hspa",
"transaction_id": "txn-abc123",
"service_type": "physical"
}Response: { "success": true, "transaction_id": "txn-abc123" }
Status arrives asynchronously via on_status.
POST /uhi/bookings/:order_id/update — Push DOCTOR_NO_SHOW
Auth required: Yes
{
"provider_uri": "https://hspasbx.abdm.gov.in/api/v1/hspa",
"transaction_id": "txn-abc123"
}on_status Callback (Inbound)
Endpoint: POST /uhi/on_status
Caller: HSPA (response to /status query)
{
"context": { "action": "on_status", "transaction_id": "txn-abc123" },
"message": {
"order": {
"id": "0415-234567-8901",
"state": "CONFIRMED",
"fulfillment": { "id": "slot-uuid-abc", "type": "Physical" },
"payment": { "status": "NOT_PAID" },
"authorization": { "type": "PIN", "status": "VERIFIED" }
}
}
}on_update Callback (Inbound)
Endpoint: POST /uhi/on_update
Caller: HSPA (unsolicited state push)
{
"context": { "action": "on_update", "transaction_id": "txn-abc123" },
"message": {
"order": {
"id": "0415-234567-8901",
"state": "APPOINTMENT_STARTED",
"authorization": { "status": "VERIFIED" }
}
}
}Internal State Mapping
Uhi::StatusService.map_state(uhi_state) maps UHI strings to internal symbols:
| UHI State | Internal Symbol |
|---|---|
CONFIRMED | :confirmed |
APPOINTMENT_STARTED | :appointment_started |
COMPLETED | :completed |
CANCELLED | :cancelled |
NO_SHOW | :no_show |
DOCTOR_NO_SHOW | :doctor_no_show |
FAILED | :failed |
HSPA_OVERRIDE | :hspa_override |
REFUND_INITIATED | :refund_initiated |