Pharmaceutical Item Management API

Pharmaceutical Item Management API

Overview

The Pharmaceutical Item Management API provides REST endpoints for managing the pharmaceutical master data in the HMIS system. This includes the full dm+d (dictionary of medicines and devices) hierarchy and supporting configuration entities.

API Endpoints

Base URLs

API	Base Path	Description
Pharmaceutical Items	/api/pharmaceutical_items	VTM, ATM, VMP, AMP, VMPP, AMPP management
Pharmaceutical Config	/api/pharmaceutical_config	Categories, dosage forms, measurement units

Authentication

All requests require a valid API key in the Finance HTTP header:

Finance: YOUR_API_KEY

Pharmaceutical Item Types

Type	URL Segment	Description	Example
VTM	vtm	Virtual Therapeutic Moiety (active ingredient)	Paracetamol
ATM	atm	Anatomical Therapeutic Material	Paracetamol (classified)
VMP	vmp	Virtual Medicinal Product (generic)	Paracetamol 500mg Tablet
AMP	amp	Actual Medicinal Product (branded)	Panadol 500mg Tablet
VMPP	vmpp	Virtual Medicinal Product Pack	Paracetamol 500mg x 100
AMPP	ampp	Actual Medicinal Product Package	Panadol 500mg x 100

Available Operations

For Pharmaceutical Items

Operation	Method	URL Pattern
Search	GET	/api/pharmaceutical_items/{type}/search?query=&departmentType=&limit=
Get by ID	GET	/api/pharmaceutical_items/{type}/{id}
Create	POST	/api/pharmaceutical_items/{type}
Update	PUT	/api/pharmaceutical_items/{type}/{id}
Retire (soft delete)	DELETE	/api/pharmaceutical_items/{type}/{id}?retireComments=
Restore (unretire)	PUT	/api/pharmaceutical_items/{type}/{id}/restore
Activate/Deactivate	PUT	/api/pharmaceutical_items/{type}/{id}/status?active=true

For Configuration Entities

Operation	Method	URL Pattern
Search	GET	/api/pharmaceutical_config/{type}/search?query=&limit=
Get by ID	GET	/api/pharmaceutical_config/{type}/{id}
Create	POST	/api/pharmaceutical_config/{type}
Update	PUT	/api/pharmaceutical_config/{type}/{id}
Retire	DELETE	/api/pharmaceutical_config/{type}/{id}?retireComments=
Restore	PUT	/api/pharmaceutical_config/{type}/{id}/restore

Config types: categories, dosage_forms, units

Understanding Retired vs Inactive

• Retired: Soft delete. Item is hidden from search results. Can be restored using the restore endpoint.
• Inactive: Temporarily disabled. Item still appears in search results but is marked inactive. Toggled via the status endpoint.

Response Format

All responses follow a standard JSON format:

{
  "status": "success",
  "code": 200,
  "data": { ... }
}

Error responses include a descriptive message:

{
  "status": "error",
  "code": 400,
  "message": "Name is required"
}

Examples

Search for AMPs

GET /api/pharmaceutical_items/amp/search?query=amoxicillin&departmentType=Pharmacy&limit=10

Create a new VTM

POST /api/pharmaceutical_items/vtm
Content-Type: application/json

{
  "name": "Amoxicillin",
  "departmentType": "Pharmacy",
  "descreption": "Beta-lactam antibiotic",
  "instructions": "Take as directed by physician"
}

Deactivate an AMP

PUT /api/pharmaceutical_items/amp/123/status?active=false

Create a Measurement Unit

POST /api/pharmaceutical_config/units
Content-Type: application/json

{
  "name": "Milligram",
  "code": "mg",
  "description": "Metric unit of mass",
  "strengthUnit": true,
  "packUnit": false,
  "issueUnit": false
}

Department Type Filter

When searching pharmaceutical items, you can filter by department type. Common values:

• Pharmacy - Pharmacy items
• Store - Store items
• Lab - Laboratory items

Related Documentation

• Pharmacy Module Overview
• Virtual Therapeutic Moieties (VTMs)
• Actual Medicinal Products (AMPs)