Differences

This shows you the differences between two versions of the page.

--- web_interface:rest_api [2025/01/21 15:57] – Adrian Boone
+++ web_interface:rest_api [2025/09/10 11:28] (current) – [API definition] Gary Willetts
@@ Line 8: / Line 8: @@
   * Mark a customer invoice as acknowledged (shipped)
   * Mark a customer invoice as received (arrived)
+  * Retrieve stock information
 Response requisitions will be processed in mSupply as normal in the supplying store, and can be fulfilled by generating and processing one or more customer invoices, depending on stock availability.
@@ Line 20: / Line 21: @@
 ===== Authentication =====
+=== For all endpoints except /storeCustomerInvoice ===
 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.
@@ Line 27: / Line 28: @@
 </WRAP>
+=== For the /storeCustomerInvoice endpoint ===
+Logins are setup as normal mSupply users. A search for matching customer invoices will be made in the user's default store.
 ===== API definition =====
@@ Line 34: / Line 37: @@
 ^ URL ^ HTTP Verb ^Description|
-| /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 or, for the /storeCustomerInvoice endpoint, include the ''loginType = "storeInvoice"'' element. |
+| /login | POST | Login with username and password setup in mSupply. For the ''/storeCustomerInvoice'' endpoint, the username and password must be for an mSupply user. For all other endpoints the username and password must be for a contact of a store name.\\ \\ 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 or, for the ''/storeCustomerInvoice'' endpoint, include the ''loginType = "storeInvoice"'' element. |
 | /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. |
@@ Line 43: / Line 46: @@
 | /customerInvoiceReceived/{invoice number} | PATCH | Set the specified customer invoice's received (arrival) date to the date specified (in ISO format). |
 | /customerInvoiceAcknowledged/{invoice number} | PATCH | Set the specified customer invoice's acknowledged (shipped) date to the date specified (in ISO format). |
-| /storeCustomerInvoice?startDate=YYYY-MM-DD&endDate=YYYY-MM-DD | GET | Return all confirmed (and not cancelled) customer invoices in the default store of the user logged in with, which were confirmed between the startDate and endDate. |
+| /storeCustomerInvoice?startDate=YYYY-MM-DD&endDate=YYYY-MM-DD | GET | **Note: This endpoint has a different authentication method to the others. You must login as an mSupply user (see the [[web_interface:rest_api#authentication|Authentication]] section above), not a contact of a store and you must use a different **''loginType''** value.**\\ Returns all confirmed (and not cancelled) customer invoices in the default store of the user logged in with, which were confirmed between the startDate and endDate. |
 ===== Examples =====
@@ Line 224: / Line 227: @@
         "confirmedDate": "2020-12-29T12:45:00.000Z",
         "receivedDate": "",
+        "acknowledgedDate": "",
         "cancelledDate": "", // blank unless the invoice has been manually cancelled after it has been confirmed
         "invoiceReference": "REF222",
@@ Line 254: / Line 258: @@
     "error": "JWT token/user ID/store ID not found"
 }
-</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 |
+</code> Returns all customer invoices for the logged in customer in their supplying store and confirmed, but which haven't yet been acknowledged, received or cancelled. Note that a single customer order can be split into multiple customer invoices |
 | api/v4/customerInvoiceReceived/8567546 | PATCH | Request: <code=javascript>
 {
@@ Line 306: / Line 310: @@
 }
 </code> Updates the received date for the specified customer invoice -> it will no longer appear in the GET response above |
+| api/v4/customerInvoiceAcknowledged/8567546 | PATCH | Request: <code=javascript>
+{
+    "acknowledgedDate": "2020-12-31T09:23:00.000Z"
+}
+</code> Response: <code=javascript>
+// success (HTTP status 200)
+{
+    "status": "success",
+    "numberOfRecordsUpdated": 1
+}
+// failure (HTTP status 404)
+{
+    "status": "error",
+    "error": "Invoice not found"
+}
+// failure (HTTP status 409)
+{
+    "status": "error",
+    "error": "More than one invoice found"
+}
+// failure (HTTP status 503)
+{
+    "status": "error",
+    "error": "Unable to update invoice"
+}
+// failure (HTTP status 503)
+{
+    "status": "error",
+    "error": "acknowledgedDate is invalid"
+}
+// failure (HTTP status 403)
+{
+    "status": "error",
+    "error": "Invoice is not yet ready for dispatch"
+}
+// failure (HTTP status 403)
+{
+    "status": "error",
+    "error": "Invoice has been already been acknowledged/cancelled"
+}
+// failure (HTTP status 400)
+{
+    "status": "error",
+    "error": "Invoice number/acknowledged date missing"
+}
+// failure (HTTP status 401)
+{
+    "status": "error",
+    "error": "JWT token/user ID/store ID not found"
+}
+</code> Updates the acknowledged date for the specified customer invoice -> it will no longer appear in the GET response above |
 | api/v4/customerInvoice/8567546 | GET | Response: <code=javascript>
 // success (HTTP status 200)