Inward Item Request API

Inward Item Request API

Overview

The Inward Item Request API (/api/itemrequests) lets an external system — such as a patient mobile app or a ward request terminal — submit service requests (e.g. Breakfast, Lunch, Dinner) and stock item requests (e.g. Water Bottle, Tea, Milk, Sugar) against an admitted patient's BHT.

Requests are saved as Pending — the patient is not charged and no stock moves. Each request is routed to a target department's in-app approval queue, where a privileged department user approves or rejects it. On approval, the BHT is charged and (for stock items) department stock is deducted, all in one atomic step.

Important: Approval and rejection happen only inside HMIS — there is no API for them. The external system polls GET /api/itemrequests/{id} to learn the outcome.

For the in-app side of the workflow, see Inward Service and Item Requests (Approval Queue).

---

Authentication

All endpoints require an API key in the Finance HTTP header:

Finance: <your-api-key>

API keys are issued in the HMIS Admin panel under API Key Management. The key must be active (not retired), activated, and not expired. Missing or invalid keys return 401.

---

Response Envelope

{"status": "success", "code": 200, "data": { ... }}
{"status": "error", "code": 400, "message": "..."}

---

Endpoints

1. Submit a Request

POST /api/itemrequests

Request body:

{
  "bhtNo": "RH/2026/001234",
  "targetDepartmentId": 42,
  "comments": "Patient requested via mobile app",
  "lines": [
    {"itemId": 1001, "qty": 1},
    {"itemId": 2002, "qty": 2}
  ]
}

A single request may mix service lines and stock item lines. Validation rules:

• bhtNo must be an active admission (not discharged, final bill not settled)
• targetDepartmentId must be an active department
• At least one line; every itemId must be an active item; every qty must be greater than 0

Response 201 — the request in PENDING state:

{
  "status": "success",
  "code": 201,
  "data": {
    "id": 98765,
    "requestNo": "IR/2026/000123",
    "bhtNo": "RH/2026/001234",
    "targetDepartmentId": 42,
    "targetDepartmentName": "Ward Kitchen Store",
    "status": "PENDING",
    "comments": "Patient requested via mobile app",
    "rejectionReason": null,
    "createdAt": "2026-07-02 09:15:00",
    "createdBy": "api-user",
    "approvalBillId": null,
    "decidedAt": null,
    "decidedBy": null,
    "lines": [
      {"billItemId": 111, "itemId": 1001, "itemName": "Breakfast", "itemType": "SERVICE", "qty": 1.0},
      {"billItemId": 112, "itemId": 2002, "itemName": "Water Bottle", "itemType": "INVENTORY", "qty": 2.0}
    ]
  }
}

2. Poll a Request's Status

GET /api/itemrequests/{id}

Returns the same structure as above. Once the department decides, status becomes APPROVED or REJECTED, and approvalBillId, decidedAt, decidedBy (and rejectionReason on rejection) are filled in. Unknown ids return 404.

3. List / Search Requests

GET /api/itemrequests?targetDepartmentId=&status=&fromDate=&toDate=&limit=

All query parameters are optional:

Parameter	Format	Meaning
targetDepartmentId	number	Only requests for this department
status	PENDING | APPROVED | REJECTED | CANCELLED	Filter by status
fromDate / toDate	yyyy-MM-dd	Filter by submission date
limit	number	Maximum rows returned

Returns a list of lightweight rows: id, requestNo, bhtNo, targetDepartmentName, status, createdAt.

4. Cancel a Pending Request

PUT /api/itemrequests/{id}/cancel

Request body:

{"reason": "Duplicate submission"}

Withdraws the request while it is still PENDING. Returns the updated request with status: "CANCELLED". If the department has already approved or rejected it (or it was already cancelled), the call returns 409.

---

Status Lifecycle

PENDING --(department approves in HMIS)--> APPROVED
PENDING --(department rejects in HMIS)-->  REJECTED
PENDING --(this API, cancel)-->            CANCELLED

• APPROVED — the BHT has been charged; stock item lines were deducted from the target department's stock (earliest-expiry batch first) and charged at the batch retail sale rate; service lines were charged per the item's configured fees. Approval is atomic — if any line fails (e.g. insufficient stock) the whole approval fails and the request stays PENDING.
• REJECTED — closed with a rejectionReason; no charge, no stock change.
• CANCELLED — withdrawn by the requesting system before a decision; no charge, no stock change.

---

Error Codes

Code	Meaning
400	Validation error — unknown/retired item, quantity ≤ 0, invalid/discharged/settled BHT, unknown department, malformed JSON
401	Missing or invalid Finance API key
404	Unknown request id
409	Cancelling a request that has already been approved, rejected, or cancelled
500	Unexpected server error

Error responses carry a human-readable message explaining what to fix.

---

Setup Prerequisites

Before integrating, the hospital must configure the requestable items:

1. Service items (Breakfast, Lunch, Dinner, …) — created as inward services with fees configured, so approval charges the correct amount.
2. Stock items (Water Bottle, Tea, Milk, Sugar, …) — created as stock-tracked items and stocked into each target department through the normal GRN flow. Approval deducts that department's stock and charges the batch retail sale rate.
3. Privileges — department users who will approve/reject need the Inward Service Item Request Approval / Rejection privileges.
4. API key — issued to the integrating system via Admin → API Key Management.

The external system needs the HMIS item ids and department ids to build requests; the hospital administrator supplies these after creating the master data.

---

Related Pages

• Inward Service and Item Requests (Approval Queue) — the in-app approval workflow for department staff
• Inward Online Payment API — companion API for online inpatient payments