Differences

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

--- web_interface:sync_api [2020/04/24 13:37] – lou
+++ web_interface:sync_api [2025/01/21 23:18] (current) – [Basics] Mark Glover
@@ Line 1: / Line 1: @@
 {{indexmenu_n>100}}
-====== 18.10. mSupply sync API ======
+====== 19.11. mSupply sync API ======
 ===== What is it? =====
 There are multiple ways to configure an mSupply installation. Where the internet is good, or you are using a local area network, you can have real-time communication with an mSupply server. Where internet access is poor or non-existent, we have mSupply sync. You can have a local application that saves all the changes the user makes to a local database - this can be a mobile app, a single user application on a PC or a tablet, or a client-server application on a local LAN.
-The machine on which the data is stored, which we call a //satellite//, then periodically communicates with a central mSupply server, which we call the //primary// - this may be in a central location in the country, or it may be a cloud-based server. The REST API described here is used to send and receive data from the primary server to keep both satellite and primary sites up to date with data additions, modifications and deletions. See [[other_stuff:remote_sync|Remote Synchronisation]] for more details on how sync works.
+The machine on which the data is stored, which we call a //satellite//, then periodically communicates with a central mSupply server, which we call the //primary// - this may be in a central location in the country, or it may be a cloud-based server. The REST API described here is used to send and receive data from the primary server to keep both satellite and primary sites up to date with data additions, modifications and deletions. See [[synchronisation:introduction|]] for more details on how sync works.
 ===== Basics =====
 You might want to read about our [[web_interface:apis|mSupply Mobile API]], as the basics are the same. That is:
-  - The SYNC API is a subset of the mSupply REST API.
+  - The SYNC API is a subset of the [[web_interface:rest_api|mSupply REST API]].
   - All calls to the sync API use a pseudo-resource of "sync".
   - The second URI segment is the API version. Allowable values:
@@ Line 100: / Line 100: @@
 <code>https://example.com/sync/v2/site/?site_name=Satellite4</code>
-will retrieve the site ID (integer) and the corresponding store ID (UUID) and store-name ID (UUID) for the sync satellite site with name=Satellite4 on the primary sync site.
+will retrieve the site ID (integer) and the corresponding store ID (UUID) and store-name ID (UUID) for the sync satellite site with name=Satellite4 on the primary sync site. Used by mobile during login to lookup the store for the site.
 <code>https://example.com/sync/v2/user/?store=CVCBNXNSHHSH</code>
-will retrieve the user ID (UUID) for the sync satellite site having store ID=CVCBNXNSHHSH (UUID, returned by the above REST call) on the primary sync site.
+will retrieve the user ID (UUID) for the sync satellite site having store ID=CVCBNXNSHHSH (UUID, returned by the above REST call) on the primary sync site. Used by mobile during login to lookup the user for the store.
 === HTTP POST ===
@@ Line 132: / Line 132: @@
 ]
 </code>
+===== Available calls (v4) =====
+=== HTTP POST ===
+<code>https://example.com/sync/v4/name_store_join</code>
+will tell the server to create a name_store_join record for the store and name records defined in the body. Used to make a patient visible when their first prescription has been processed in a store.
+== Body ==
+<code>
+{
+    "name_ID": "xxx",
+    "store_ID": "xxx"
+}
+</code>
+== Response ==
+If all is well, 200 OK and the payload:
+<code>
+{
+  "name_ID": "6F0EA445B35F479AA1020BD2D24B9755",
+  "store_ID": "8D967C2618BE4D78B3A6FAD6C1C8FF25",
+  "inactive": false,
+  "ID": "C6C0A32C1E9841FF93735144F0114290",
+}
+</code>
+A 400 will be returned if either of the payload elements are missing or the IDs are not present.
+A 401 will be returned if authentication fails.
+\\
+\\
+=== HTTP GET ===
+<code>https://example.com/sync/v4/patient_history?id=[name id]</code>
+Requests patient dispensing history for the specified name record
+== Response ==
+If all is well, 200 OK and the payload:
+<code>
+[
+    {
+        "confirm_date": "2019-02-22",
+        "store": {
+            "name": "Hogwarts Dispensary"
+        },
+        "transLines": [
+            {
+                "quantity": 5,
+                "item_name": "Amoxicillin 250mg tabs",
+                "ID": "4C8C08880A20490A9F2B9EC6EC9700A1",
+                "itemLine": {
+                    "item": {
+                        "code": "030453",
+                        "doses": 0,
+                        "is_vaccine": false
+                    }
+                }
+            }
+        ]
+    },
+    {
+        "confirm_date": "2021-05-07",
+        "store": {
+            "name": "Hogwarts Dispensary"
+        },
+        "transLines": [
+            {
+                "quantity": 0.16666666666667,
+                "item_name": "Pfizer/BioNTech COVID-19 vaccine",
+                "ID": "a53a3350aec411eba43c6dc4a1371348",
+                "itemLine": {
+                    "item": {
+                        "code": "C19PB",
+                        "doses": 6,
+                        "is_vaccine": true
+                    }
+                },
+                "medicineAdministrator": {
+                    "first_name": "Melaia",
+                    "last_name": "Baleinausori"
+                }
+            }
+        ]
+    }
+]
+</code>
+An empty array will be returned if the ID does not match a name record or there is no history to return.
+A 401 will be returned if authentication fails.
+===== Available calls (v5) =====
+==== HTTP GET ====
+=== central_records ===
+<code>https://example.com/sync/v5/central_records?cursor=0&limit=1000</code>
+Requests sync change log records for the sync site matching the authentication sent in the header.
+== Attributes ==
+  * **cursor**: the record number to return from. e.g. ''cursor=10'' means start returning from the 10th record onwards.
+  * **limit**: the maximum number of records that can be returned. If omitted, the //limit// is set to 1000. If a //limit// value above 1000 is used, the //limit// is set to 1000.
+=== queue ===
+<code>https://example.com/sync/v5/queue?limit=[number of records]</code>
+Requests sync records that require processing for the sync site which matches the authentication passed in the header.
+== Attributes ==
+  * **limit**: the maximum number of records that can be returned. If ommitted, the //limit// is set to 1000. If a //limit// value above 1000 is used, the //limit// is set to 1000.
 \\
 \\
-|  //  Previous:  **[[web_interface:apis]]** | | Next: **[[mobile:]]** //  |
+|  //  Previous:  **[[web_interface:apis]]** | | Next: **[[web_interface:unfpa_reports_app]]** //  |
 ---- struct data ----
+pagestatus.status    :
 ----