Skip to main content

API Contract

API requests#

The app is executing these API calls:

  • Submit Code - triggered each time when code is scanned (or after code is scanned and form data is provided)
  • Update Settings - optional setting. If a specific "updateUrl" is set, this an api call that checks server for newest settings is executed each time the application is opened.

API request - Submit Code#

After code is scanned a POST request is made to the specified URL using this JSON as body:

{  "deviceId": "someRandomId",  "scannedValue": "1234567890123",  "event": "codeScanned"}
  • deviceId - is a unique code that is generated when the app is installed on device. If application is updated, this code does not change. If application is removed and installed again, this code is changed.
  • scannnedValue - is the actual value, that is scanned by the scanner
  • event - optional information on event (codeScanned, applicationOpened)

API request - Submit Code with Form Data#

If the custom form data functionality is used, the API request includes also the entered form values:

{  "deviceId": "someRandomId",  "scannedValue": "1234567890123",  "event": "codeScanned",  "formValues": {    "length": 150,    "gender": "male"  }}

API response#

The application expects that your defined API url returns response in following format:

api minimal response:#

  • http status code 200 - displays green ok screen
  • http status cod !== 200 - displays red failed screen

api minimal response, alternative:#

It is possible to include JSON body to customize the status screen shown.

{  "title": "Some Title",  "message": "Some message",  "status": "ok"}

It is possible to provide title, or title and message that is displayed on screen. The status field can override http status code. If set to failed, the "failed" screen is shown and failed sound is played.

api response format, optional status-screen customizing features#

{  "title": "Title",  "message": "Some message",  "status": "ok",  "backgroundColor": [    0,    100,    0  ],  "autoScanTimeout": 9000}
  • backgroundColor - sets the color of the background on the statusScreen [r,g,b] value range is 0-255, e.g. [0,255,0]
  • autoScanTimeout - overrides the application setting for autoScanTimeout, see settings

api response format, optional updating of (some/all) application settings#

{  "title": "Title",  "message": "Some message",  "status": "ok",  "backgroundColor": [    0,    100,    0  ],  "autoScanTimeout": 9000,  "settings": {    "apiUrl": "https://3f3e6f3259e8.ngrok.io/scanner/",    "headers": {      "X-API-KEY": "NEW VALUE",      "X-CUSTOM-VALUE": "789101112"    }  }}
  • settings* - the values present in the settings JSON overwrite the application settings in the application

You can override all or just some settings in api response, e.g. update API key.

API request - Update Settings#

since app build #4

When application starts, an API request to the endpoint apiUrlOpened (if set) is sent to request if there is any change in settings. This is usually useful when the custom form functionality is used - to check if there is any update of the form is needed. See example settings qr code & try it out.

Settings update request body format#

{  "deviceId": "someStoredId",  "scannedCode": "",  "event": "applicationOpened",  "settings": { current_app_settings }}

Settings update request response format#

Is the same as scanned code response format. To display custom settings applied message and update just form data the response can look like this: 

{  "title": "Settings updated",  "message": "New fruits form!",  "status": "ok",  "backgroundColor": [    0,    0,    100  ],  "autoScanTimeout": -1,  "settings": {    "formData": {      "schema": {        "newFruitForm": {          "title": "New - Please choose",          "type": "string",          "enum": [            "Apple",            "Pear",            "Cherry"          ]        }      }    }  }}