# CarePulse IoT ↔ HIS integration (Caresoft HIS or any HIS)

Switch on in **Settings → HIS integration** (client admin). Three flows:

## 1. Patient lookup (CarePulse → HIS)
`GET {his_base_url}{his_patient_path}` — default path `/api/carepulse/patients/{uhid}`
Headers: `X-API-Key: <HIS API key>`, `X-Client-Code: <hospital code>`

HIS returns (200) — 404 if not found:
```json
{ "patient": { "uhid": "UH1001", "patient_id": 55501, "name": "Asha Patil", "gender": "F", "dob": "1961-04-02",
               "mobile": "9822233344", "email": "", "abha_number": "", "address": "", "city": "Pune" } }
```

## 2. Admission / transfer / discharge (HIS → CarePulse)
`POST https://<carepulse>/api/v1/his/adt`
Headers: `X-Client-Code: SHIVA`, `X-HIS-Key: <inbound key generated in CarePulse settings>`
```json
{ "event": "admit",                       // admit | transfer | discharge | patient_update
  "patient":   { "uhid": "UH1001", "patient_id": 55501, "name": "Asha Patil", "gender": "F", "dob": "1961-04-02", "mobile": "9822233344" },
  "admission": { "id": "IP-7781", "ward_code": "ICU", "bed_code": "ICU-04", "doctor": "Dr Rao", "at": "2026-11-17T10:00:00+05:30" },
  "consent":   { "given_by": "Self" }      // optional: consent captured in the HIS admission form
}
```
* Patients are matched on `patient_id` then `uhid`; created if new.
* Wards / beds match CarePulse `HIS ward code` / `HIS bed code` (set in Wards & beds), else by name.
* Bedside devices fixed to that bed are bound to the patient automatically; on transfer/discharge they are released.

Response: `{ "ok": true, "patient_id": 12, "bound_devices": 1 }`

## 3. Vitals to the nursing chart (CarePulse → HIS)
Confirmed readings are queued and posted by the worker (every minute, in order, with retries):
`POST {his_base_url}{his_vitals_path}` — default `/api/carepulse/vitals`
```json
{ "event": "vitals", "client": "SHIVA", "uhid": "UH1001", "his_patient_id": "55501", "his_admission_id": "IP-7781",
  "observations": [ { "carepulse_id": 9912, "code": "spo2", "name": "SpO2", "loinc": "59408-5", "value": 95, "unit": "%",
                      "measured_at": "2026-11-17T10:12:00+05:30", "source": "device", "flag": "normal" } ] }
```
Return any 2xx when stored. `carepulse_id` is unique — use it to ignore repeats.

### FHIR R4 option
Settings → HIS integration → Format **FHIR R4**: the same push becomes a `Bundle` (type `transaction`) of vital-signs `Observation` resources with LOINC codes, UCUM units, `subject.identifier` = UHID, `encounter.identifier` = IP number, `interpretation` A/AA for out-of-range, and `ifNoneExist` on the CarePulse reading id (safe to resend). Content-Type `application/fhir+json`.

### HL7 v2 ADT
HIS interface engines can send ADT^A01/A02/A03/A04/A08 over MLLP to the CarePulse Edge gateway (port 2575) instead of calling the REST endpoint — see `EDGE_GATEWAY.md`.

### Which readings are pushed
* Home / phone / manual readings: automatically once confirmed (setting "Send home / Bluetooth device readings automatically").
* Bedside monitor readings: only after a nurse charts them on **Chart vitals** (corrected values replace monitor artefacts).
