Konnect exposes a set of REST API endpoints for you to integrate with, which you can explore using our OpenAPI Specification.

Before you start

Contact your account manager for an API key to get started with ByBox Konnect Partner API. All our REST API's are secured using the OAuth standard and accessed over HTTP for private and secure access.

Once your API key is generated, you'll receive:

• Client ID (e.g. my_bybox_client_id)
• Client Secret (e.g.  XXXXXXXX-YYYY-ZZZZ-ABCDEFGHIJKL)

Step 1: Authentication

Perform the following HTTP request to receive an access token from our authentication endpoint:

When you make a request, it will return a JSON object containing your access token. The token will expire in a number of seconds. To authenticate, supply your access token with every request to our other endpoints.

/Auth/core/connect/token

grant_type:client_credentials
scope:StockonnectPartnerAPI
client_id:my_bybox_client_id
client_secret:XXXXXXXX-YYYY-ZZZZ-ABCDEFGHIJKL

{
"access_token": "abc...xyz",
"expires_in": 3600,
"token_type": "Bearer"
}

Step 2: Making your first request

Once you've received a valid access token you can use this by providing an authorisation header with your request to our API. For example, the following http request will return a list of all your locations:

/Api/locations

application/json

Authorization : "Bearer {access_token}"

{
  "name": "Birmingham",
  "identifier": "BH1",
  "latitude": 52.4777572,
  "longitude": -1.9011467,
  "address": {
    "address1": "Station Street",
    "address2": "Birmingham",
    "address3": "",
    "address4": "",
    "address5": "",
    "postalCode": "B2 4QA",
    "country": {
      "name": "United Kingdom",
      "code": "UK"
    }
  }
}

Step 3: Workflow integration

Most of our partners follow one of the following workflows:

• Pick up and drop off
• Replenishing inventory
• Collecting from inventory 

Pick up and drop off

This is best suited for partners who wish to deliver packages to a person for collection. There are 2 options:

• An allocated locker permanently assigned to a person.
• A locker allocated to a person until they collect a package.

Allocating a permanently assigned locker

This is achieved by assigning a locker to a user of your system using the following API endpoint:

/Api/users/{identifier}/door/{doorIdentifier}           

application/json

Authorization : "Bearer {access_token}"

Configure "Notifications" on the locker in Konnect HQ to alert your engineer of deliveries arriving to their allocated locker. They will receive a push notification or email when their package has been delivered.

Temporary Access

Alternatively, you may wish to limit access to your delivery locker until a package is collected. In this scenario, once the package has been delivered you can assign the package to the person who will be collecting it. They will receive a push notification or email to collect their package.

To assign a package for collection you can use the following API endpoint:

/Api/users/{userIdentifier}/packagecollectionassignments           

application/json

Authorization : "Bearer {access_token}"

{
  "barcode": "string" // The tracking number of the package
}

Replenishing inventory

Keeping stock data accurate is a critical part of Konnect. It includes the following parts:

• Stock Keeping Units (SKUs)
• Stock Locations: A location holding inventory stock

SKUs

Stock Keeping Unit is the type of part you wish to store in inventory. There are two types: serialised and non-serialised.

A serialised SKU is where each unit being stored has a unique identifier that can be used to track that particular part.
A non-serialised SKU has all its parts identified by the same tracking number.

To create a serialised SKU, use this endpoint:

/Api/skus/

application/json

Authorization : "Bearer {access_token}"

{
  "identifier": "string",
  "description": "string",
  "name": "string"
}

Or to create a non-serialised SKU, use this endpoint:

/Api/skus/nsi

application/json

Authorization : "Bearer {access_token}"

{
  "identifier": "string",
  "description": "string",
  "name": "string",
  "barcode": "string"
}

In order for Konnect to know what inventory is inside your package, you will need to Pre-Advise before the package arrives at the locker. For a non-serialised SKU this will happen automatically when the specified barcode is scanned by the driver.

For a serialised SKU, you need to call the below endpoint:

/Api/skus/{identifier}/preadvice           

application/json

Authorization : "Bearer {access_token}"

{
  "trackingNumber": "string" 
}

Once the carrier has made a delivery into your locker, create a Job Order for an engineer to move the part into an inventory locker. Once all the packages on the Job Order have been collected, the Job Order is complete and the engineer's access to the delivery locker will be revoked.

A Job Order can be created using the following endpoint:

/Api/orders/job     

application/json

Authorization : "Bearer {access_token}"

{
  "orderReference": "string", // A Unique reference for the order
  "user": "string", // the identifier of the user who will be assigned the job.
  "packages": [
    {
      "barcode": "string", // the tracking number of the package to be collected
      "location": "string", // the identifier of the location where the package is.
      "door": "string" // the identifier of the door which contains the package.
    }
  ],
}

Notify Konnect about the upcoming delivery by Locker Access Terminal or Konnect One

Sometimes you may want a delivery made by a user without access to the Konnect App, either using Locker Access Terminal or Konnect One.

In this situation, you must notify Konnect of the upcoming delivery using the below endpoint. This will create an access code for your driver to use, matching the package with the tracking number.

Please note:

1. Pre-Advice feature should be enabled for your client.
2. Location must have a unique identifier assigned in order to use this call. You can do this either programmatically, or using Konnect HQ.
3. Client, User and Delivery door should be enabled for the deliveries using Locker Access Terminal or Konnect One.

/Api​/goodsin

application/json

Authorization : "Bearer {access_token}"

{
  "locationIdentifier": "string",
  "skuIdentifier": "string",
  "trackingNumber": "string"
}

Collecting from inventory

For an engineer to collect a part from inventory, they need an inventory order. Before we can create one of those we need to allocate lockers to store your inventory in. To do this we can assign a locker as a stock location by using the below endpoint:

/Api/skus/{identifier}/doors

application/json

Authorization : "Bearer {access_token}"

{
  "doorIdentifier": "string", // the identifier of the door 
  "minimumStockLevel": 0
}

Now that the SKU is allocated to the locker, we have the ability to check the stock level at that location before we place an order.

/Api/locations/{locationIdentifier}/skus/{skuIdentifier}/summary

application/json

Authorization : "Bearer {access_token}"

{
  "totalNumberOfPackages": 10, // Total amount in the door
  "availableNumberOfPackages": 6 // The number available after all active orders are collected
}

As long as there is stock available in the locker you can now create an Inventory Order to be collected by your engineer.

/Api/orders/{locationIdentifier}/skus/{skuIdentifier}/summary

application/json

Authorization : "Bearer {access_token}"

{
  "orderReference": "string",
  "user": "string",
  "skus": [
    {
      "sku": "string",
      "quantity": 0,
      "location": "string",
      "locationIdentifier": "string",
      "barcodes": [
        "string"
      ]
    }
  ],
}