Pharmacy

The Pharmacy module provides inventory management and medication dispensing capabilities. It tracks stock levels per medication and location, enforces stock checks at dispense time, and alerts when items run low or are nearing expiration.

Check Stock Levels

curl https://api.esus.health/pharmacy/stock \
  -H "Authorization: Bearer TOKEN"

Response:

[
  {
    "id": "cc33dd44-ee55-ff66-7788-990011223344",
    "organizationId": "11112222-3333-4444-5555-666677778888",
    "medicationId": "aa11bb22-cc33-dd44-ee55-ff6677889900",
    "locationId": "bb22cc33-dd44-ee55-ff66-778899001122",
    "quantity": 250,
    "minQuantity": 50,
    "maxQuantity": 1000,
    "lotNumber": "LOT-2024-001",
    "expirationDate": "2025-06-30",
    "lastRestockedAt": "2024-01-10T08:00:00Z",
    "createdAt": "2023-11-01T08:00:00Z",
    "updatedAt": "2024-01-10T08:00:00Z"
  }
]

Filter by Location or Medication

# Stock at a specific location
curl "https://api.esus.health/pharmacy/stock?locationId=bb22cc33-dd44-ee55-ff66-778899001122" \
  -H "Authorization: Bearer TOKEN"

# Stock for a specific medication
curl "https://api.esus.health/pharmacy/stock?medicationId=aa11bb22-cc33-dd44-ee55-ff6677889900" \
  -H "Authorization: Bearer TOKEN"

Restock Inventory

Add new stock when medication is received:

curl -X POST https://api.esus.health/pharmacy/restock \
  -H "Authorization: Bearer TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "medicationId": "aa11bb22-cc33-dd44-ee55-ff6677889900",
    "locationId": "bb22cc33-dd44-ee55-ff66-778899001122",
    "quantity": 500,
    "lotNumber": "LOT-2024-002",
    "expirationDate": "2026-01-31"
  }'

Dispense Medication

Dispenses medication and automatically deducts from stock after checking that enough is available. The body accepts medicationId, locationId, and quantity (required), plus optional patientId, encounterId, and note:

curl -X POST https://api.esus.health/pharmacy/dispense \
  -H "Authorization: Bearer TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "medicationId": "aa11bb22-cc33-dd44-ee55-ff6677889900",
    "locationId": "bb22cc33-dd44-ee55-ff66-778899001122",
    "quantity": 30,
    "patientId": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
  }'

Response: the updated stock row, with quantity already decremented:

{
  "id": "cc33dd44-ee55-ff66-7788-990011223344",
  "organizationId": "11112222-3333-4444-5555-666677778888",
  "medicationId": "aa11bb22-cc33-dd44-ee55-ff6677889900",
  "locationId": "bb22cc33-dd44-ee55-ff66-778899001122",
  "quantity": 220,
  "minQuantity": 50,
  "maxQuantity": 1000,
  "lotNumber": "LOT-2024-001",
  "expirationDate": "2025-06-30",
  "lastRestockedAt": "2024-01-10T08:00:00Z",
  "createdAt": "2023-11-01T08:00:00Z",
  "updatedAt": "2024-01-15T11:00:00Z"
}

If there is insufficient stock (or no stock row exists for that medication and location), the API returns 400 Bad Request:

{
  "resourceType": "OperationOutcome",
  "issue": [{
    "severity": "error",
    "code": "invalid",
    "diagnostics": "Insufficient stock or stock entry not found for the specified medication and location"
  }]
}

Manual Stock Adjustment

Use for inventory corrections, damaged stock, or expired medication write-offs:

curl -X POST https://api.esus.health/pharmacy/adjust \
  -H "Authorization: Bearer TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "medicationId": "aa11bb22-cc33-dd44-ee55-ff6677889900",
    "locationId": "bb22cc33-dd44-ee55-ff66-778899001122",
    "adjustment": -15,
    "reason": "Damaged stock disposal"
  }'

Use a positive adjustment value to add stock, negative to remove.

Low Stock Alerts

Get all items that have fallen below their minimum stock threshold:

curl https://api.esus.health/pharmacy/low-stock \
  -H "Authorization: Bearer TOKEN"

Response:

[
  {
    "id": "ee55ff66-7788-9900-1122-334455667788",
    "organizationId": "11112222-3333-4444-5555-666677778888",
    "medicationId": "e5f6a7b8-c9d0-1234-ef56-78901234abcd",
    "locationId": "bb22cc33-dd44-ee55-ff66-778899001122",
    "quantity": 8,
    "minQuantity": 50,
    "maxQuantity": 500,
    "lotNumber": "LOT-2024-010",
    "expirationDate": "2025-09-30",
    "lastRestockedAt": "2023-12-01T08:00:00Z",
    "createdAt": "2023-10-01T08:00:00Z",
    "updatedAt": "2024-01-14T09:00:00Z"
  }
]

Expiring Medications

Get medications expiring within a specified number of days (default: 30):

# Medications expiring in the next 30 days (default)
curl https://api.esus.health/pharmacy/expiring \
  -H "Authorization: Bearer TOKEN"

# Medications expiring in the next 90 days
curl "https://api.esus.health/pharmacy/expiring?days=90" \
  -H "Authorization: Bearer TOKEN"

Response:

[
  {
    "id": "ff66aa11-8899-0011-2233-445566778899",
    "organizationId": "11112222-3333-4444-5555-666677778888",
    "medicationId": "f6a7b8c9-d0e1-2345-f678-9012345bcdef",
    "locationId": "bb22cc33-dd44-ee55-ff66-778899001122",
    "quantity": 45,
    "minQuantity": 20,
    "maxQuantity": 200,
    "lotNumber": "LOT-2023-099",
    "expirationDate": "2024-02-01",
    "lastRestockedAt": "2023-11-15T08:00:00Z",
    "createdAt": "2023-09-01T08:00:00Z",
    "updatedAt": "2023-11-15T08:00:00Z"
  }
]

Integration with FHIR MedicationDispense

After dispensing via the Pharmacy API, create a FHIR MedicationDispense resource to maintain a complete medication history:

curl -X POST https://api.esus.health/fhir/MedicationDispense \
  -H "Authorization: Bearer TOKEN" \
  -H "Content-Type: application/fhir+json" \
  -d '{
    "resourceType": "MedicationDispense",
    "status": "completed",
    "medicationCodeableConcept": {
      "coding": [{ "system": "http://snomed.info/sct", "code": "372687004" }]
    },
    "subjectId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "authorizingPrescription": [{ "reference": "MedicationRequest/c1a2e3d4-5b6f-7890-abcd-ef1234567890" }],
    "quantity": { "value": 30, "unit": "capsule" },
    "whenHandedOver": "2024-01-15T11:00:00Z"
  }'