# Caresoft HIS connector — what your .NET developer needs to build

**Not built here.** This is the on-premise half of the Phase 10 integration: a
small Windows service that sits next to a hospital's HIS database and talks to
CareCollect. The cloud half — every endpoint below — is built and tested.

## Why an agent and not a direct connection

Caresoft HIS runs on-premise on MSSQL behind a hospital firewall. The cloud
cannot reach in. Asking a thousand hospitals for a VPN, a static IP or an
inbound port is not a rollout plan; it is a two-year project that never
finishes, and it stalls on the one hospital whose IT contact left.

The agent only ever makes **outbound HTTPS calls**, which every hospital
already permits. No firewall change, no network team, no per-site negotiation.
It is the same shape as a backup agent, and it can be installed by whoever
installs HIS updates today.

## What it does

A loop, every 30 seconds:

1. `POST /his/v1/hello` — heartbeat. Sends agent version, HIS version, machine
   name. Gets back how much work is waiting. This is what makes the console say
   "last seen 4 minutes ago" instead of a hospital finding out three days later
   that nothing has synced.
2. `GET /his/v1/pull?limit=25` — collects work. Each item is one collected
   sample with its barcode, the patient, and the tests already translated into
   **HIS item codes**.
3. Write it into HIS. Create or find the patient, create the lab entry, and use
   **our barcode as the lab barcode** — that is the decision that removes the
   relabelling step at the bench.
4. `POST /his/v1/ack` — report per item. On success send back `his_lab_no` and
   the patient key (`his_ptype`, `his_pno`, `his_pyr`, `his_uhid`). On failure
   send `ok: false` and an `error`; add `permanent: true` only when retrying
   genuinely cannot help.

Separately, whenever a report is finalised in HIS:

5. `POST /his/v1/results` — `{his_lab_no, status, report_url}`. We notify the
   patient and call any partner webhooks.

And in the other direction, so a clerk never keys a patient twice:

6. `GET /his/v1/slots?pincode=...` then `POST /his/v1/orders` — a home
   collection raised inside HIS appears on the CareCollect board. Send
   `his_ref`; the same one twice returns the same order rather than sending a
   second phlebotomist.

## Rules the cloud side enforces, so you do not have to

- **Nothing is pushed for an unmapped test.** A guessed item code means the
  wrong test billed and possibly the wrong result filed against a patient, so
  those rows sit as `blocked` on a worklist until a person maps them. Mapping a
  test releases everything it was holding up.
- **Claimed, not deleted.** If the agent dies mid-batch the rows return after
  ten minutes rather than vanishing.
- **Failures retry by default.** HIS being restarted mid-push is far more
  common than a genuinely bad payload, so only `permanent: true` stops a retry.
- **The patient key is three columns.** `ptype`, `pno`, `pyr` — not a single
  UHID. Storing our own guess breaks the moment a hospital reuses numbers
  across years, which is what `pyr` exists for.

## Auth

`X-Agent-Key` and `X-Agent-Secret` headers. Issued per hospital from the
CareCollect console; the secret is shown once and stored hashed. Keys are
scoped to one hospital — another hospital's agent pulling your queue gets an
empty list, and acknowledging your row gets "no such entry" (both tested).

## Mapping help

`POST /his/v1/suggest-mappings` with the HIS item master. It returns suggested
pairings — exact code matches at confidence 1.0, fuzzy name matches lower.
**Suggestions only.** A person confirms each one in the console before anything
is pushed. Getting a mapping wrong is worse than having no mapping.

## Suggested implementation

- .NET 8 Windows Service (or 4.8 if the hospital's server is older — many are)
- `HttpClient` with retry and jitter; nothing here is latency-sensitive
- Read HIS via stored procedures rather than direct table writes, so a HIS
  upgrade that changes a table does not break the connector
- Log to a rolling file and to the Windows event log; hospitals will ring
  Caresoft support, not read a JSON log
- Config in a plain `.ini` beside the exe: base URL, agent key, agent secret,
  poll interval. Nothing that needs a UI.