# 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: ```json { "status": "success", "code": 200, "data": { ... } } ``` Error responses include a descriptive message: ```json { "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](Pharmacy) - [Virtual Therapeutic Moieties (VTMs)](Virtual-Therapeutic-Moieties-(VTMs)) - [Actual Medicinal Products (AMPs)](Actual-Medicinal-Products-(AMPs))