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",
    "medicationId": "aa11bb22-cc33-dd44-ee55-ff6677889900",
    "medicationCode": "372687004",
    "medicationDisplay": "Amoxicillin 500mg capsule",
    "locationId": "bb22cc33-dd44-ee55-ff66-778899001122",
    "quantity": 250,
    "unit": "capsule",
    "lotNumber": "LOT-2024-001",
    "expiresAt": "2025-06-30"
  }
]

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,
    "unit": "capsule",
    "lotNumber": "LOT-2024-002",
    "expiresAt": "2026-01-31"
  }'

Dispense Medication

Dispenses medication to a patient and automatically deducts from stock. Links to a FHIR MedicationRequest for full clinical traceability:

curl -X POST https://api.esus.health/pharmacy/dispense \
  -H "Authorization: Bearer TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "medicationRequestId": "c1a2e3d4-5b6f-7890-abcd-ef1234567890",
    "patientId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "medicationId": "aa11bb22-cc33-dd44-ee55-ff6677889900",
    "locationId": "bb22cc33-dd44-ee55-ff66-778899001122",
    "quantity": 30,
    "unit": "capsule",
    "dispensedBy": "a7b1c2d3-e4f5-6789-abcd-ef0123456789"
  }'

Response:

{
  "id": "d4e5f6a7-b8c9-0123-def4-567890abcdef",
  "medicationRequestId": "c1a2e3d4-5b6f-7890-abcd-ef1234567890",
  "patientId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "medicationId": "aa11bb22-cc33-dd44-ee55-ff6677889900",
  "quantity": 30,
  "dispensedAt": "2024-01-15T11:00:00Z",
  "remainingStock": 220
}

If there is insufficient stock, the API returns 409 Conflict:

{
  "resourceType": "OperationOutcome",
  "issue": [{
    "severity": "error",
    "code": "conflict",
    "diagnostics": "Insufficient stock: requested 30, available 12"
  }]
}

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:

[
  {
    "medicationId": "e5f6a7b8-c9d0-1234-ef56-78901234abcd",
    "medicationDisplay": "Lisinopril 10mg tablet",
    "locationId": "bb22cc33-dd44-ee55-ff66-778899001122",
    "currentQuantity": 8,
    "minimumThreshold": 50,
    "unit": "tablet"
  }
]

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:

[
  {
    "medicationId": "f6a7b8c9-d0e1-2345-f678-9012345bcdef",
    "medicationDisplay": "Insulin (rapid-acting) 100 units/mL",
    "lotNumber": "LOT-2023-099",
    "quantity": 45,
    "unit": "vial",
    "expiresAt": "2024-02-01",
    "daysUntilExpiry": 17
  }
]

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"
  }'