Barcode Scanning

Providing barcode scanning functionality to your drivers through our mobile applications requires that you be familiar with two key actions: requesting barcodes and capturing barcodes.

πŸ””

Barcode scanning is a premium feature which can be enabled by the organization administrator from the dashboard settings. In addition to this documentation, you may find this support center article helpful.

Requesting

To request a barcode means to create a task with barcode data that will inform the driver that one or more barcodes should be scanned prior to completing a task. You can optionally block task completion on a per barcode basis, effectively turning your barcode request into a barcode requirement.

In order to request barcodes for a task, you can create a new task or update an existing task while providing the barcodes object array, top-level task property.

The structure of the object members of this array property is as follows:

NameTypeDescription
datastringOptional. Base64 representation of the data encoded within the barcode to be captured, max length of 500 characters
blockCompletionbooleanOptional. Whether the worker must capture this data prior to task completion, defaults to false

Requesting a barcode will ensure that your driver can see the barcodes requested when they are about to complete a task. The driver will be prevented from completing the task unless all requested barcodes with blockCompletion set to true have been captured.

If you would like to request that any barcode be scanned, regardless of data, you may simply omit the data property in your request.

Barcode Requirement Scenarios

❗️ Barcode Best Practices

Before you start developing barcode requirements, please read through each scenario to determine the best fit for your use case.

There are 4 different supported scenarios.

(1) Allow All Barcodes

  • Behavior: Allows workers (drivers) to provide any number of barcodes or no barcodes. This is the least restrictive method.
  • Implementation: Provide no object members inside the barcodes array

(2) Restrict to a fixed number of Barcodes

  • Behavior: Any barcodes can be scanned and the number of barcodes scanned must match what's configured. This is moderately restrictive.
  • Implementation: Provide object members inside the barcodes array containing no data variables, and enforce the number of barcodes by using "blockCompletion":true

    πŸ”” Note

    blockCompletion default value is false, so it may be used to customize this scenario further. For example, require 2 scans but allow up to 4 scans.

(3) Restrict to included Barcodes, don’t block task completion if missing

  • Behavior: ONLY matching barcodes will be accepted, but all included barcodes do not need to be scanned to complete the task. This is more restrictive, but gives the worker (driver) the ability to move on to the next task without outside intervention.
  • Implementation: Provide object members inside the barcodes array containing data.

(4) Restrict to included Barcodes, block task completion if missing

  • Behavior: ONLY matching barcodes will be accepted and all included barcodes must be scanned to complete the task. This is the most restrictive method, and requires a dispatcher to Force Complete if the driver is unable to complete all scans.
  • Implementation: Provide object members inside the barcodes array containing data and enforce the barcodes by using "blockCompletion":true

    🚧 Invalid barcode data

    Invalid barcode data provided (a 400 error) will be returned if any non-array barcode data is passed in. This is considered invalid data.

Creating a new task with requested barcodes

The following request creates a new task with one mandatory and one optional barcode.

curl -X POST "https://store.bponi.com/api/v2/tasks" \
       -u "cd3b3de84cc1ee040bf06512d233719c:" \
       -d '{"destination":{...},
            "recipients":[...],
            "scanOnlyRequiredBarcodes": true,
            "barcodes":[
                {"data":"aGVsbG8gd29ybGQh","blockCompletion":true},
                {"data":"aG93IGFyZSB5b3U/"}
             ]
            }'
1
2
3
4
5
6
7
8
9
10
{
  "id": "0VuO6yDq5YrGeZ7NVwUqK8hu",
  //...,
  "barcodes": {
    "required": [ 
      { "data": "aGVsbG8gd29ybGQh", "blockCompletion": true },
      { "data": "aG93IGFyZSB5b3U/", "blockCompletion": false }
    ],
    "captured": [ ]
  },
  //... 
}
1
2
3
4
5
6
7
8
9
10
11
12

❗️ What you see is NOT what you get

If your request was successful, the API will respond with your barcodes under the property of barcodes.required, it does not mean that you can set the barcode properties the same way it's provided by the API.

πŸ”” Use of scanOnlyRequiredBarcodes

Use the boolean flag of scanOnlyRequiredBarcodes upon task creation to restrict the scanning of non-required barcodes. Learn more about the usage here.

Updating an existing task with requested barcodes

The following request will update an existing task containing no barcode requirements such that it requires one non-blocking barcode to be scanned by the driver. Note that updating a task’s barcodes property will entirely overwrite any previously existing values.

curl -X PUT "https://store.bponi.com/api/v2/tasks/0VuO6yDq5YrGeZ7NVwUqK8hu" \
       -u "cd3b3de84cc1ee040bf06512d233719c:" \
       -d '{"barcodes":[{"data":"bXkgc25lYWt5IHVwZGF0ZQ=="}]}'
1
2
3
{
  "id": "0VuO6yDq5YrGeZ7NVwUqK8hu",
  //...,
  "barcodes": {
    "required": [ 
      { "data": "bXkgc25lYWt5IHVwZGF0ZQ==", "blockCompletion": false }
    ],
    "captured": [ ]
  },
  //... 
}
1
2
3
4
5
6
7
8
9
10
11

❗️ Removing barcodes

When removing barcode requirements, remember to send in an empty array for the barcodes field instead of nil/NULL values.

Capturing

Barcodes can be only be captured via the Bponi Storeopen in new window iOS or Android driver app.

Note that capturing barcodes can be done for any task, regardless of barcode request status, provided the organization has the feature enabled. You only need to use the requesting functionality if you wish to inform the driver about barcodes to be scanned or enforce their collection.

Once a task is completed for which barcodes have been captured, you may access the details of these barcodes by fetching the task via API, using any of the relevant methods from the Tasks section of the docs.

Each object member of the barcodes.captured array property returned for completed tasks will have the following properties:

NameTypeDescription
idstringThe ID of the captured barcode.
symbologystringThe symbology that was captured. You can read more about these here.
datastringThe base64 string of the data contained in the captured barcode.
locationnumber arrayThe [ lon, lat ] coordinates where the barcode capture took place.
timenumberThe time at which the barcode capture happened.
wasRequestedbooleanWhether the barcode was captured as a result of a barcode request.

Here is an example of the barcodes property for a completed task with no required barcodes:

{
  "id": "9I4cmNGtVTm5VRcq7B*lymEA",
  //...
  "barcodes": {
    "required": [],
    "captured": [
      {
        "symbology": "CODE39",
        "data": "QkMzMjE=",
        "wasRequested": false,
        "time": 1498500964205,
        "location": [
          -122.42855072021484,
          37.78808138412046
        ],
        "id": "ku0fpiCqJPC25h3W0cnfgqNn"
      },
      {
        "symbology": "UPCA",
        "data": "MDEyMzQ1Njc4OTA1",
        "wasRequested": false,
        "time": 1498500964205,
        "location": [
          -122.49481201171875,
          37.75307256315459
        ],
        "id": "leElaPdbWobzlwDoP5MuHA~h"
      }
    ]
  },
  //...
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
Last Updated: 11/29/2021, 10:25:26 PM