Integrating Skublox API – Workflows

Every API endpoint requires authentication. Read more

Ensuring Subscription is Enabled

For the purpose of keeping statistics (roll out and adoption of the product), we would like to limit usage of the Skublox functionality to clients who have the subscription enabled.

Enabling the subscription does not cost anything. The pricing of the product is directly related to the number of slots a client uses on a monthly basis.

You can determine if the subscription is enabled by calling GET /subscriptions/skublox resulting in true or false.

If the response HTTP code is 404 Not Found this means the client’s server is outdated and does not have this particular API – we cannot determine if the subscription is already added or not.

We can assume that the client has the subscription and allow usage of Skublox functionality. After their next server update, this check will result in a proper true or false value, and your application will react correctly to it.

Setting up a Wall

Before any sorting operations can commence, a wall must be added to the client’s database, and it must have at least one slot (light device) attached to it.

  1. Create a wall by calling POST /walls
    • Choose a suitable name, e.g. Jackson St Warehouse – it must be unique across all walls for the current client.
    • Make sure the isActive flag is set to true (default)
    • You can choose how many sorters can connect to a wall simultaneously. 1..6, defaults to 6.
  2. “Attach” at least one slot serial number to the wall by calling PUT /walls/{id}/sort-boxes
    • Slots are also known as light devices or sort boxes
    • The serial numbers are also known as hardware IDs
    • The PUT response will include meta data about each slot, including what is known as a CRC
    • This is a short-hand, fixed-length version of the serial number of the format ######## where # is a hex digit A..F or 0..9
    • It is also the barcode printed on each light device an used to guide sorters
    • e.g. 0x004e4c38534713100105648e is transformed to 73F43055

The wall should now be ready for employees to connect to it as sorters.

Real-world serial numbers (hardware IDs) are of the format 0x123456780abcdef but the API will accept dummy values like fake-id-12345678.

The API will return an error if it detects that any slot serial number is already associated with another wall for the same client. This can happen when testing with different walls and reusing the slots, or after “wall reconstruction” or “moving.”

Ways to mitigate the include removing the slot serial number from the other wall, or deleting the whole altogether (if it is no longer in use).

Connecting as a Sorter

Connecting as a sorter to a given wall results in a user session entity represented by a session token and a user color.

When connecting, a picklist # may be included. This will result in a more “scoped” sorting session, only working with orders included in that pick list.

The picklist must be with an open status. Closed picklists are not supported.

The session token is included with each barcode scan request or when swapping slots. Similarly, the slot (light device) lights up in the respective color, guiding the sorter where to put the product they have scanned.

Attempt to connect to the wall by calling POST /walls/{id}/sessions

  • If unsuccessful, the error message will cite the actual reason in a verbose way.
  • The most common reason is that there are too many sorters connected already. Sorters may disconnect manually via the Mobile app or administrators can use the Hub app to disconnect them.

The session token can now be used to sort products on the wall.

A given user can only be connected once to a given wall. When calling the POST endpoint, any existing session for the same user, for the same wall will be invalidated. Similarly, inactive sessions are automatically terminated after 8 hours.

If you would like to renew an existing session, call PUT /walls/{id}/sessions/{token}

Sorting Products

Sorting a product requires two components: a session token, and a barcode.

Note that the wall or picklist # (if any) are not specified in scan requests – these are “known” through the wall session represented by the token.

The barcode may be any valid product identifier such as a SKU, UPC, shadow SKU or an alias.

Submit a barcode scan

Submit a barcode scan by calling POST /sort-box-items

  • An optional barcodeInputMethod may be specified, noting how the barcode was sent by the client app (e.g. manually typed in, keyed in, scanned with an embedded scanner). This is used for logging and statistics.

A barcode scan may fail for a number of reasons. These include unrecognized barcode, no fulfillable order found for the product, no empty slots available on the wall, etc. The error message will cite the exact reason in a verbose way.

If the system finds a relevant, fulfillable order for the given product, and an appropriate slot to sort it in, the call will result in meta data for the new sort box item.

The meta data includes the unique id of this scanned product, the crc (barcode) of the slot it must be put in, and other details.

Note that the status of the item will be pending confirmation.

On the “real” wall, the Hub application will receive an instant notification about this event, and will make this slot light up in the user’s color, guiding them through the next step of the process: confirming the scan.

Confirm a barcode scan

Ideally, a sorter should scan the barcode that has lit up in their color in order to confirm that they have put the product in the right place expected by the system.

The sorter barcode is of the format A-######## where ######## is the CRC (barcode) of the slot assigned by the system.

Note that barcodes of the format B-######## are shipper barcodes and should not be accepted (they have the same CRC of the slot but are usually located on the reverse side of the wall, for shipping staff).

When your software determines that the proper slot barcode was scanned (i.e. that the product was placed in the correct slot), confirm the barcode scan by calling PATCH /sort-box-items/{id}/confirm

  • When a product is scanned, the sort box item is created for 1 unit. You can optionally specify the number of units being confirmed at once by including the query string ?units={units}.
  • The number of units being confirmed cannot be greater than the remaining quantity expected by that slot/order, i.e. (units required by order) – (units already confirmed in previous scans). Defaults to 1.

A barcode scan (sort box item) cannot be confirmed more than once. If such a request is sent, it will result in an error.

Cancel a barcode scan

A sorter may decide to cancel a pending barcode scan for a number of reasons. e.g. this may happen if they damage the goods after scanning the barcode or while putting the goods in the slot.

Clients would like protect this operation with a PIN code (if there is one configured/enabled). Please consult the PIN Code section below for good practices involving PIN codes.

Cancel a barcode scan by calling PATCH /sort-box-items/{id}/cancel

A barcode scan (sort box item) cannot be canceled more than once. If such a request is sent, it will result in an error.

Swapping a Slot

Not all slots on a wall are made equal. Various slots may be of different size.

While the system employs an algorithm that decides on a slot based on user color and availability, a sorter may decide that the automatically chosen slot is not appropriate for a given order or product.

Swapping a slot requires two components: a session token, and a target slot barcode.

The barcode may be the slot CRC ######## or a sorter barcode of the format A-########. The user of the application should scan the real-world sorter barcode in order to confirm their slot preference.

Swap the slot of a pending product scan by calling b

Note that the slot can be swapped only if this is the very first product being sorted in this slot. Swapping a slot “after the fact” is not supported and will result in a relevant error.

Ending a Sorter Session

When a sorter has finished sorting products (or needs to stop their work), it is recommended that their session be stopped. This will allow other sorters to connect to the same wall in the meantime.

Stop a session by calling DELETE /walls/{id}/sessions/{token}

If a session has been stopped by another connection by the same user on another device (or terminated automatically by the system), a relevant error message will be returned.

It is recommended that errors received while stopping a session not be shown in the UI, in order to avoid unnecessary confusion by users.

Cross-Cutting Concern: PIN Code

We have decided to protect certain functionality with a PIN code, if configured. This is the same PIN code used by Skustack.

Such functionality includes cancelling a barcode scan or keying in a product manually (if scanning does not work).

When performing such actions, only continue if there is no PIN code required, or if the PIN code provided by the user is correct.

Check if a PIN code is required by calling GET /security/pin/length hinting at the length of the PIN code

  • 0 means the PIN code is not configured/required
  • Not required but can be used for better UX: This integer can be used to show the same number of boxes for individual characters/input
  • Remember that a PIN code might contain any alphanumerical character

If a PIN code is required, show an appropriate PIN code entry modal.

Validate the PIN code by calling POST /security/pin/validate?pin={pin}

Was this article helpful?

Yes No