# CareSterile HIS Integration API (v1)

This is for the HIS or IT team.

- **Base URL:** `https://<your-domain>/api/v1`
- **Format:** JSON over HTTPS.
- **Authentication:** send the key in a header, either `Authorization: Bearer cssd_<CLIENTCODE>_<40 hex>` or `X-API-Key: …`.
- **Keys:** the hospital admin creates them under **Integrations → API keys**. A key is shown once and can be revoked at any time.
- **Requirement:** Level 1 must switch on the "HIS integration" feature for the client. Until then the API returns 403.

| Method | Path | Purpose |
| --- | --- | --- |
| GET | `/ping` | Check the key works |
| POST | `/patients` | Upsert patients. Send one object, or `{"patients":[…]}` with up to 500. Fields: `uhid`, `name` (required); `gender`, `dob`, `mobile`, `ip_no`, `ward`, `bed`, `admitted_at` |
| POST | `/surgeries` | Upsert the OT schedule. Send one object or `{"surgeries":[…]}`. Fields: `surgery_at`, `ot_code` (required); `his_ref`, `patient_uhid`, `patient_name`, `ip_no`, `procedure_code`, `procedure_name`, `surgeon_code`, `surgeon_name`, `status` (`scheduled` / `cancelled`) |
| GET | `/packs/{pack_no}` | Pack status, expiry, load, biological indicator (BI) and recall, plus `safe_to_use` and `not_safe_reason` |
| POST | `/packs/{pack_no}/use` | Link a pack to a patient. Send `{"surgery_ref":"…"}` or `{"patient_uhid","patient_name","ip_no","procedure_name"}`. Returns 422 if the pack is expired, from an unreleased load, under recall or already used |
| GET | `/patients/{uhid}/packs` | Every pack used on the patient (traceability for the EMR) |
| GET | `/charges?status=pending&limit=100` | Patient charges to post into HIS billing |
| POST | `/charges/{id}/posted` | Mark a charge posted, e.g. `{"his_ref":"BILL-123"}`. Posting the same charge twice returns 409 |
| GET | `/recalls?status=open` | Open recalls with the affected patients |
| POST | `/hl7` | Raw HL7 v2 message as the request body. Returns an HL7 ACK |
| POST | `/fhir/Patient`, `/fhir/Appointment` | FHIR R4 resources. Returns an `OperationOutcome` |
| POST | `/rfid/reads` | RFID reader posts tags: `{"reader":"STORE-1","epcs":[…],"read_at":"…"}`. Reader codes are registered under RFID. Needs the RFID feature |
| POST | `/machines/{machine code}/cycles` | Sterilizer / washer cycle report: JSON `{"cycle_no","program","started_at","ended_at","temperature_c","pressure_bar","exposure_min","result","raw"}` or the raw printout / CSV as body. Attaches to the running load. Needs the machine-data feature |

## How records are matched

- **OT:** `ot_code` is matched against the department **code** or **HIS code** (set under Masters → Departments).
- **Procedure and surgeon:** matched by HIS code (`procedure_code`, `surgeon_code`) first, then by exact name.
- **Unmatched records:** they are still saved, and are flagged as "Not mapped" on the OT schedule.
- **Resending:** sending the same `his_ref` again updates the surgery.
- **Late cancellation:** if a case is cancelled after CSSD has raised its indent, the indent is flagged.

## HL7 v2 messages supported

### ADT^A01 / A04 / A08 (patient)

| Field | Used for |
| --- | --- |
| PID-3 | UHID |
| PID-5 | Name |
| PID-7 | Date of birth |
| PID-8 | Sex |
| PID-13 | Phone |
| PV1-3 | Ward^room^bed |
| PV1-19 | IP no. |
| PV1-44 | Admission date |

### SIU^S12 / S13 / S14 (surgery booked)

| Field | Used for |
| --- | --- |
| SCH-1 | Booking id |
| AIS-3 | Procedure code^name |
| AIS-4 | Start date/time |
| AIP-3 | Surgeon id^family^given |
| AIL-3 | OT code |

### SIU^S15 / S17 (surgery cancelled)

These cancel the surgery.

### Acknowledgements (MSA)

| Code | Meaning |
| --- | --- |
| AA | Accepted |
| AE | Application error, for example a missing date |
| AR | Rejected: unsupported message type or no MSH segment |

## Webhooks (CareSterile → your system)

Set these up under **Integrations → Webhooks**. There are presets for **Caresoft HIS** and **CareIPC**.

Each event is sent as a POST with:

- **Body:** `{"event","client_code","occurred_at","data"}`
- **Headers:** `X-CSSD-Event`, `X-CSSD-Delivery`, and `X-CSSD-Signature: sha256=<HMAC_SHA256(raw body, webhook secret)>`

Reply with a 2xx status within 8 seconds. If a delivery fails it is retried after 1, 5, 15, 60 and 240 minutes, then marked failed. Failed deliveries can be retried from the admin screen.

| Event | Sent when | Typical receiver |
| --- | --- | --- |
| `pack.used` | A pack is linked to a patient. Includes `surgery_ref`, `load_no` and expiry | HIS / EMR, CareIPC |
| `charge.created` | A patient charge is created | HIS billing |
| `load.failed` | A sterilizer cycle fails | CareIPC |
| `bi.positive` | A biological indicator turns positive | CareIPC |
| `recall.started` | A recall starts. Includes the patients already exposed | HIS, CareIPC |
| `recall.closed` | A recall closes | HIS, CareIPC |
| `machine.test_failed` | A Bowie-Dick or leak test fails | Biomedical |
| `indent.stat` | A STAT indent is raised | — |
| `env.breach` | Temperature or humidity goes out of limits | — |

## Single sign-on from HIS

Switch it on under **Integrations → Settings**. The HIS then opens:

```
https://<domain>/sso?client=CODE&user=USERNAME&ts=UNIX_TIME&sig=HEX(HMAC_SHA256("CODE|username|ts", sso_secret))&to=app/dept
```

The link is valid for 2 minutes and can be used only once. `user` is the CSSD username or the employee code.

## CSV fallback

If the HIS cannot call the API, upload CSV files under **Integrations → CSV import**. Patients and the OT schedule use the same column names as the JSON fields above.

## Errors

| Code | Meaning |
| --- | --- |
| 400 | Bad body |
| 401 | Missing, wrong or revoked key |
| 403 | Integration off, or account suspended or expired |
| 404 | Not found |
| 409 | Conflict (for example, posting a charge twice) |
| 413 | More than 500 items in one call |
| 422 | A safety rule refused the request. The message explains why |
| 429 | Rate limit reached. Default 600 per minute per key, adjustable by the hospital admin |

Every call is recorded in **Integrations → Log**.
