| Both sides previous revision Previous revision Next revision | Previous revision |
| web_interface:rest_api [2023/06/26 15:10] – [API definition] Gary Willetts | web_interface:rest_api [2024/02/13 11:40] (current) – [Authentication] Adrian Boone |
|---|
| {{indexmenu_n>90}} | {{indexmenu_n>90}} |
| ====== 19.09. mSupply REST API ====== | ====== 19.09. mSupply REST API ====== |
| UNDER CONSTRUCTION, INFORMATION COMING SOON! | |
| |
| ===== What is it? ===== | ===== What is it? ===== |
| mSupply has a REST API that enables certain actions to be carried out externally, by external applications for example. This API allows you to: | mSupply has a REST API that enables certain actions to be carried out externally, by external applications for example. This API allows you to: |
| Logins (user name and password) are set up per store as contacts of store names. This uses exactly the same mechanism as customer web ordering. See the [[web_interface:msupply_customer_setup|]] page for details. | Logins (user name and password) are set up per store as contacts of store names. This uses exactly the same mechanism as customer web ordering. See the [[web_interface:msupply_customer_setup|]] page for details. |
| |
| | <WRAP info center round 90%> |
| ===== Create a customer order (response requisition) ===== | All requests relate to transactions, stock and orders **only** in the store that the user used to authenticate with is a contact of. The customer and supplier's details are derived from the log-in details i.e. the customer will be the store the logged in user is a contact of and the supplier will be the supplying store of that store. |
| * The customer and supplier's details are derived from the log-in details i.e. the customer will be the store the logged in user is a contact of and the supplier will be the supplying store of that store. | </WRAP> |
| * An order (serial) number will be automatically assigned by mSupply (unique per store). | |
| * Item codes must match the codes (the mSupply item code or the catalogue code) of items already existing in mSupply. | |
| * Quantities are specified in number of packs and pack size. | |
| * Customer orders are created as response (customer) requisitions in mSupply. These are then processed manually in the supplying store to generate one or more customer invoices to fulfil the order (see the [[issuing_goods:stock_control_methods#response_internal_requisitions|8.07. Stock control methods for your customers (requisitions)]] page for details). | |
| * Customer invoice numbers will also be automatically assigned by mSupply (unique per store). | |
| * Generated customer invoices will be linked back to the original customer order via the order number. | |
| * Customer invoices are confirmed when the stock has been picked and packed for shipment. | |
| * Comments can be entered for the order and also for individual lines. | |
| | |
| | |
| ===== Receive customer invoice(s) ===== | |
| * Vesalius polls mSupply for confirmed customer invoices which haven't yet been received | |
| * Invoices are linked to the original order via the order number | |
| * Quantities are specified in number of packs and pack size | |
| * Prices are per-pack and a line total, with an invoice total which includes any extras (e.g. shipping) | |
| | |
| | |
| ===== Confirm receipt ===== | |
| * Mark a specified customer invoice as received in mSupply, so it will no longer be included in the invoice list | |
| | |
| | |
| ===== Get stock of an item ===== | |
| * Return stock details for all items in the customer's master list (s). | |
| * Optionally filter by item name and/or item code. | |
| * Quantities are specified in number of packs and pack size. | |
| * Separate lines for each different batch, expiry date or pack size. | |
| | |
| |
| |
| |
| ^ URL ^ HTTP Verb ^Description| | ^ URL ^ HTTP Verb ^Description| |
| | /login | POST | Login with username and password setup in mSupply. Returns a JWT cookie to be used in following requests. Include the ''loginType = "invoice"'' element in the request body. | | | /login | POST | Login with username and password setup in mSupply. Returns a JWT cookie to be used in following requests (send it in an Authorization header with scheme Bearer i.e. ''Authorization: Bearer <jwt_token>''). Include the ''loginType = "invoice"'' element in the request body. | |
| | /stock | GET | Returns an array of stock details for all items in the customer's master list(s). \\ * Quantities are specified in number of packs and pack size. \\ * Separate lines for each different batch, expiry date or pack size. | | | /stock | GET | Returns an array of stock details for all items in the customer's master list(s). \\ * Quantities are specified in number of packs and pack size. \\ * Separate lines for each different batch, expiry date or pack size. | |
| | /stock?code=xxx&name=yyy | GET | Returns an array of stock details for all visible items, optionally restricted to those starting with the specified code/name. \\ * Quantities are specified in number of packs and pack size. \\ * Separate lines for each different batch, expiry date or pack size. | | | /stock?code=xxx&name=yyy | GET | Returns an array of stock details for all visible items, optionally restricted to those starting with the specified code/name. \\ * Quantities are specified in number of packs and pack size. \\ * Separate lines for each different batch, expiry date or pack size. | |
| | /customerOrder | POST | Create a new customer order with the supplied array of order lines. Returns the ID of the order created. | | | /customerOrder | POST | Create a new customer order with the supplied array of order lines. Returns the ID of the order created. \\ * The customer and supplier's details are derived from the log-in details i.e. the customer will be the store the logged in user is a contact of and the supplier will be the supplying store of that store. \\ * An order (serial) number will be automatically assigned by mSupply (unique per store). \\ * Item codes must match the codes (the mSupply item code or the catalogue code) of items already existing in mSupply. \\ * Quantities are specified in number of packs and pack size. \\ * Customer orders are created as response (customer) requisitions in mSupply. These are then processed manually in the supplying store to generate one or more customer invoices to fulfil the order (see the [[issuing_goods:stock_control_methods#response_internal_requisitions|8.07. Stock control methods for your customers (requisitions)]] page for details). \\ * Customer invoice numbers will also be automatically assigned by mSupply (unique per store). \\ * Generated customer invoices will be linked back to the original customer order via the order number. \\ * Customer invoices are confirmed when the stock has been picked and packed for shipment. \\ * Comments can be entered for the order and also for individual lines. | |
| | /customerOrder/{order number} | GET | Return the details of the specified order number. | | | /customerOrder/{order number} | GET | Return the details of the specified order number. | |
| | /customerInvoice | GET | Returns an array of customer invoices which have been confirmed but not yet received or cancelled. | | | /customerInvoice | GET | Returns an array of customer invoices which have been confirmed but not yet received or cancelled. \\ * Invoices are linked to the original order via the order number. \\ * Quantities are specified in number of packs and pack size. \\ * Prices are per-pack and a line total, with an invoice total which includes any extras (e.g. shipping). | |
| | /customerInvoice/{invoice number} | GET | Returns a particular customer invoice. | | | /customerInvoice/{invoice number} | GET | Returns a particular customer invoice. \\ * Invoices are linked to the original order via the order number. \\ * Quantities are specified in number of packs and pack size. \\ * Prices are per-pack and a line total, with an invoice total which includes any extras (e.g. shipping). | |
| | /customerInvoiceReceived/{invoice number} | PATCH | Set the specificed customer invoice's received date to the date specified. | | | /customerInvoiceReceived/{invoice number} | PATCH | Set the specificed customer invoice's received date to the date specified (in ISO format). | |
| |
| |
| "userJobTitle": "Boss", | "userJobTitle": "Boss", |
| "userType": "contact", | "userType": "contact", |
| "service": "vesalius", | "service": "invoice", |
| "storeName": "General Warehouse" | "storeName": "General Warehouse" |
| } | } |
| "error": "JWT token/user ID/store ID not found" | "error": "JWT token/user ID/store ID not found" |
| } | } |
| </code> Returns all customer invoices for the logged in customer in their supplying store which have been created from response requisitions created by Vesalius (i.e. have "vesalius" somewhere in their comment field) and confirmed, but which haven't yet been received or cancelled. Note that a single customer order can be split into multiple customer invoices | | </code> Returns all customer invoices for the logged in customer in their supplying store and confirmed, but which haven't yet been received or cancelled. Note that a single customer order can be split into multiple customer invoices | |
| | api/v4/customerInvoiceReceived/8567546 | PATCH | Request: <code=javascript> | | api/v4/customerInvoiceReceived/8567546 | PATCH | Request: <code=javascript> |
| { | { |