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:
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:
Error responses include a descriptive message:
Examples¶
Search for AMPs¶
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¶
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 itemsStore- Store itemsLab- Laboratory items