19.10. mSupply legacy REST APIs
What is it?
This document describes an application programming interface for communicating with mSupply.
Basics
- Communication is over HTTP protocol
- All data is submitted and returned as JSON
- HTTPS supported- you should use it. If you want to restrict to only HTTPS, then block the HTTP port mSupply is using on your router.
Authentication
- All requests must have standard HTTP basic authentication headers
- You must use SSL to secure your communications unless you want to tell the world your password.
GET - Getting data from mSupply
For all calls
- The basic syntax
http://server_ip_address/type/resource/id_of_resource e.g. http://example.com/mobile/name/524 will retrieve the complete record for name whose ID=524
- or
http://server_ip_address/resource?field=blah,field2=blah2&sortby=+foo,-bar e.g. http://example.com/mobile/name?name=foo@,customer=true&sortby=+name will retrieve all names whose name starts with "foo" and who are customers, sorted by name in ascending order (a to z) Note that a "/" is also allowed before the "?" in the URL e.g. http://example.com/mobile/name/?name=foo@,customer=true&sortby=+name
- Method: GET
- Note that all price data will be returned rounded to 2 decimal places.
Paging
- If you want a range of items, pass an HTTP header named “range” with a “from” and “to” value separated with a hyphen. See the following example to find out the right format for the “range” header.
- e.g. to return the first 15 items:
range bytes=1-15
- The server will reply with a header containing the item range and the total number of items found:
items 1-15/568
Query notes
- For string searches you can use “@” as a wildcard, as in the example above
- ?name=@foo@ will return all names containing “foo”
- ?name=foo@bah will return all names starting with “foo” and ending with “bah”
- Allowed query operators are:
- =
- # (not equal to)
- >=
- <=
- <
- >
- A query operator must be followed by a query value
- All resources returned are first filtered by the server to only return valid results for the store the user is logged in to.
Available resources
mobile/Items
Resource name | item |
---|---|
Fields you can query | any |
Returns by default JSON array containing: | id code item_name stock_on_hand_tot |
When a single item ID is requested | department category category2 stock_on_hand stock_available An array with a key of “lines” containing pack_size, available_quantity, batch, expiry_date, sell_price |
mobile/Transactions
Resource name | transaction |
---|---|
Fields you can query | any |
Returns a JSON array containing: | id name (i.e. the name of the customer/supplier the transaction is to/from) entry_date confirm_date status (a two letter code denoting the status of the transaction) comment (the user-entered comment) |
If you only request a single ID (e.g example.com/mobile/transaction/558 | A JSON object containing every field for that record |
Special case one: Getting An ID to use when submitting a new transaction; submit example.com/mobile/transaction/new_id Returns: | JSON object containing: new_transaction_id |
mobile/Names
Resource name | name (a name can be a customer, a supplier, a manufacturer or a donor or a combination of these) |
---|---|
Fields you can query | any |
Returns by default JSON array containing | id code name bill_address1 |
mobile/Invoice
Resource name: | invoice |
---|---|
Fields you can query | none. Just call the ID number like this http://example.com/mobile/invoice/578 |
Returns by default JSON array containing | id name_id name_name (The actual name of the customer or supplier) total their_ref type entry_date confirm_date comment entered_by (username not ID) store (name not ID) hold lines: contains an array containing the lines on the invoice. Each array row contains: item_id item_name quantity (no. of individual items i.e. pack size x quantity in a pack) stock: contains an array of all stock lines used on the invoice, and also any other stock lines for items on the invoice whose quantity is greater than zero. This means that for a “normal” invoice line editing operation (where you are not changing the item) you already have all the information that you need without a further call to the REST server when a line is edited) |
Example | { "id" : 587, "name_id" : 79, "invoice_num" : 256, "status" : "fn", "total" : 824.5, "their_ref" : "GIZ05", "type" : "ci", "entry_date" : "2012-09-30", "confirm_date" : "2012-10-30", "name_name" : "ZIGO HOSPITAL", "lines" : [ { "id" : 6396, "item_key" : 973, "item_line_key" : 960, "item_name" : "CLOXACILLIN TABS 250MG BOT/1000", "quantity" : 5, "pack_size" : 1000, "sell_price" : 161.61, "price_extension" : 808.05 }, { "id" : 6397, "item_key" : 120, "item_line_key" : 14, "item_name" : "ATENOLOL TABLETS 50MG BOT/100", "quantity" : 5, "pack_size" : 100, "sell_price" : 3.29, "price_extension" : 16.45 } ], "stock" : [ { "id" : 22126, "quantity" : 162, "batch" : "AD 1002", "expiry_date" : "2014-09-30", "pack_size" : 1000, "sell_price" : 147.09 }, { "id" : 22307, "quantity" : 12, "batch" : "3026844", "expiry_date" : "2014-03-30", "pack_size" : 1000, "sell_price" : 139.3 } ] } |
mobile/Stock
Resource name | stock |
---|---|
Fields you can query | any in the items table or for all the items of a particular invoice with the field “trans_id” |
Typically, having located an item to add to an invoice you will want to locate the total stock available for that item | http://example.com/mobile/stock?ID=123 // stock for item.ID 123
http://example.com/mobile/stock?trans_id=123 // stock for transaction.ID 123 |
Returned: an array of match records containing the item ID and the total stock quanitity like this | [ { "id" : 5265, "quantity" : 30, }, { "id" : 5275, "quantity" : 100, }, { "id" : 5274, "quantity" : 50, } ] |
Stocktakes
Resource name | stocktake |
---|---|
Fields you can query | any |
Fields returned from a query | ID description stocktake created date status |
You can filter on type of stocktake by querying the status e.g. | http://example.com/mobile/stocktake?status=sg |
Requesting a particular stocktake returns the following fields for the stocktake itself | description stocktake created date stocktake entered date status comment An array whose key is “lines” containing an these fields for each item in the stocktake: item code item name quantity (the pack size is assumed to be one) snapshot quantity |
Example | the following request would return the information for the stocktake with an id of 123: http://example.com/mobile/stocktake/123 |
Special Case: Creating a stocktake | First you need to get a stocktake id that you can use by requesting the resource “new_id” http://127.0.0.1:8081/stocktake/new_id |
A note on creating stocktakes: the recommended process is:
- Get a new stocktake id
- Get items- this will also return the current stock on hand.
- Display this, along with a column for the user to enter current stock on hand
- When ready to save, post the data (below). Wasn't so hard!
Categories
Use this resource to return lists of different types of categories in mSupply.
Resource name | category |
---|---|
Fields you can query | any |
Fields returned from a query | id - the id of this category (unique only among categories of the same level) description - the descriptive name of the category type - the category's type. Can be one of 1level1, 1level2, 1level3, 2 or 3 parent_id - the id of the category which is the parent of this one. 0 means the category has no parent |
You can filter on type of category by querying the type (which can take the values “item”, purchase_order“, “transaction” and “name”) | The following query will return all the categories for items http://example.com/mobile/category?type=item |
catalogue/Catalogue Items
Resource name | catalogueItem |
---|---|
First URI segment | catalogue |
Fields you can query | any |
Fields returned from a query for each item | id - the item's unique id code Item - the item's code item_name - the item's descriptive name indic_price - the catalogue price of the item description - the lowest level category (category 1, level 3) that the item belongs to units - the units the item is provided in e.g. Amp (ampule) Tab (tablet), report_quantity - the pack size of the item in the catalogue, e.g. the following query would return all items with an id greater than -1 and a name beginning with “a” |
* You can filter on the category that items belong to by querying the category number and level. There are 3 categories (1-3) but please note that category 1 is hierarchical; it has 3 levels - level 1 is the parent, level 2 categories are children of level 1s and level 3 categories are children of level 2s. So, altogether you can query category1level1id, category1level2id, category1level3id, category2id and category3id. Note that all queries by category will return items that belong to that category and those which belong to all its child categories e.g. this query will return all items assigned to the level 2 category 1 which has an id of 4 and all items belonging to category 1 level 3 categories that are children of it:
Example | http://example.com/catalogue/catalogueItem?category1level2id=4 |
---|
Customer Stock History Items
Resource name | customerstockhistory |
---|---|
Fields you can query | any |
Fields returned from a mulitple query | id, date_entered |
Fields returned from a single id | id, date_entered,stock_take_date, lines (array) |
The lines object array contains: id (the id of the line, [name_s_h_line]id) item_id (the id of the item, [name_s_h_line]item_id) item_name (the name of the item - [item]item_name using [name_s_h_line]item_id) item_code ([item]code using [name_s_h_line]item_id) store_stock (the amount of stock (number of items not packs) the supplying store has of this item) stock_on_hand (the stock on hand entered by the user, [name_s_h_line]stock_on_hand) usage (this store's daily usage of this item. Calculated as (stock on hand last stocktake + stock received last stocktake - stock on hand this stocktake)/number of days between this and the previous stocktake. Use new [name_s_h_line]previous_stock_on_hand and [name_s_h_line]previous_received_from_us fields in the calculation) comment (the line's comment - [name_s_h_line]comment) |
Version
Resource name | version |
---|---|
Fields you can query | none |
Returned | the current mSupply mobile version |
Example: | http://example.com/mobile/version |
mobile/masterlist
Resource name | masterlist |
---|---|
Fields you can query | name_id, type (the type of list to return) |
Returned | JSON containing the items for the associated masterlist belonging to the name of the specified type |
Example | http://example.com/mobile/masterlist/name_id="123"&type=weborder |
Settings
Resource name | settings |
---|---|
Fields you can query | none. Precisely. |
Returned | A JSON object with three entities: timeout, name_id, name- This is the id and name of the customer or supplier or store |
Example | http://example.com/mobile/settings |
mobile/Purchase orders
Resource name | po |
---|---|
Fields you can query | id |
Returned | JSON containing the Purchase Order details for the ID you queried |
Example | http://example.com/mobile/po/id="123" |
Reports
Resource name | report |
---|---|
Query | type with one of three options: type=currentstock or type=expiringstock or type=orderedvsreceived |
Query parameters | type=currentstock: none type=expiringstock&nummonths=xx where nummonths is the number of months in advance of the current date to compare expiry dates with type=orderedvsreceived&from=yyyymmdd&to=yyyymmdd where the from and to dates in yymmdd format are entered. |
Returned | JSON containing the “Successfully sent” or any errors encounters |
Example | http://example.com/mobile/report/type=currentstock |
Patients
Resource name | patient |
---|---|
Query parameters | first_name: first name of patient last_name: last name of patient dob: patient date of birth (DD:MM:YY) policy_number: patient insurance policy number |
Returned | JSON array of patient objects matching query parameters: [{ "ID":, "name", "phone", "customer", "bill_address1", "supplier", "email", "code", "last", "first", "date_of_birth", "type", "manufacturer", "bill_address3", "bill_address4", "bill_postal_zip_code", "supplying_store_id", "nameNotes": ["note1","note2", ...], "nameInsuranceJoin": [{ "ID", "insuranceProviderID", "nameID", "isActive", "policyNumberFamily", "policyNumberPerson", "type", "discountRate", "expiryDate", "policyNumberFull", "enteredByID" }, ... ], }, ... ] |
Example | http://example.com/api/v4/patient?first_name=j@&last_name=doe&dob=01/01/1960 |
Prescribers
Resource name | prescriber |
---|---|
Query parameters | first_name: first name of prescriber last_name: last name of prescriber code: prescriber code |
Returned | JSON array of prescriber objects matching query parameters: [{ "ID", "code", "first_name", "last_name", "initials", "registration_code", "category", "address1", "address2", "phone", "mobile", "email", "female", "active", "store_ID" }, ... ] |
Example |
The Stock Endpoint
This API is used by the mSupply stock web app.
POST/PUT - Sending data to mSupply
- Must include authentication header
- Data in HTTP body as JSON
- Two types of POST/PUT: New and Update
- For New records:
- Must use POST method without 'If-Match: *' header.
- Append the id of the record to be created to the resource: e.g. POST http://example.com/mobile/transaction/134
- For Updates to an existing record:
- Must use either POST method with 'If-Match: *' header or PUT method (headers ignored). e.g. PUT http://example.com/mobile/transaction/134
Transactions
- Resource name: transaction
- Create a transaction
- Submit a JSON object containing:
- new_transaction_id (you must have already requested this from the server - see above )
- comment
- name_id
- lines (contains a JSON array:)
- item_id
- quantity
- directions (new in v3.84)
- Payload.
{"id": 34592,"comment":"test 1","name_id":3, "lines":[ {"item_id": 19697,"quantity":10,"directions":"1t tid uf"}, {"item_id": 22845,"quantity":5,"directions":"Take 5 tablets at 9 a.m. tomorrow"} ] }
- successful completion returns a JSON object with “invoice_num” and a number
- Assumed data: The following data is assumed and can not be submitted (will be ignored if you try)
- The transaction type: it's a customer invoice (“ci”)
- The store ID: it's the store you're logged in to.
- The user: it’s the user who is logged in.
- The entry_date: it's today.
- The confirm_date: it's today.
- The status: will always be “cn” (confirmed).
- Updating a transaction:
- for supplier invoice we are editing only hold status for now. So json payload would be:
{"id":1002,"hold": "true"}
- for customer invoice we can also update line quantity
{"id": 34592,"comment":"test 2", "lines":[ {"transline_id": 19697,"quantity":20}, {"transline_id": 22845,"quantity":10} ] }
- Delete transaction lines:
{"id": 34592,"comment":"test 2","lines":[<all_lines>]
Stocktakes
Resource name | stocktake |
---|---|
Method | POST |
Submit a JSON object containing | id (you must have already requested this from the server - see above ) |
Finalising a stocktake | body: include an item “status” with value “fn” |
Assumed fields | stock_take_created_date created_by_id finalised_by_id store_id |
example 1 | Submit a stocktake and finalise http://example.com/mobile/stocktake/123{"status": "fn", id:123, stock_take_date:2013-02-08, description:8/2/2013 Stocktake, Comment: "test", "lines":[ {"id": 123,"item_id":234,"item_line_id":345,"item_name";"test_item1";"snapshot_qty":300,"stock_take_qty":310}, {"id": 222,"item_id":232,"item_line_id":212,"item_name";"test_item2";"snapshot_qty":400,"stock_take_qty":300} ] } if the previous status was “sg”, the mSupply server will now create the appropriate inventory adjustments, as well as changing the status of the stocktake. |
---|---|
example 2 | Submit a stocktake with status “sg” http://example.com/mobile/stocktake/123 {"new_stocktake_id": 34592,"description":"stocktake test", "status":"sg", "lines":[ {"item_id": 19697,"stock_take_qty":100}, {"item_id": 22845,"stock_take_qty":80} ] } |
example 3 | Finalise an existing stocktake http://example.com/mobile/stocktake/123 {"status":"fn"} |
Customer Stock History
Resource name | customerstockhistory |
---|---|
Method | POST |
Submit a JSON object containing an array with 3 fields | id requested_quantity user_comment |
DELETE - Delete Records
Available resources
Stocktake
- Deleting a stocktake
- Method: DELETE
- Returns a JSON object containing a Description field with the value “stock take id xxx is deleted.” where xxx is the id of the stocktake deleted.
Invoice
- <add here>
Item
- <add here>
Errors
- Errors are returned as a JSON object with one item “error” whose text content is the error message
- e.g.
{"error":"we can't take you seriously while you insist on wearing that cardy"}
- Here is a list of error messages you might see. Most are self-explanatory:
- “No search parameter specified”
- “No query parameter specified”
- “Invalid resource specified”
- “Invalid sort field specified”
- “Invalid range header specified”
- “No transaction with that ID found”
- “Invalid transaction ID specified” (Different to above, in that you specified a non-numeric or negative ID)
- “Yikes! Multiple transactions with same ID found” (you'll never see this error, or we'll be eating hats).
Previous: 19.09. mSupply REST API | | Next: 19.11. mSupply sync API |