Overview

The Lok API is organized around REST, having resource-oriented URLs, accepts and returns JSON-encoded bodies, and uses standard HTTP response codes, authentication and verbs. Dates are in UTC time standard.

This API allows the integration of your company systems with the rental of lockers:

• Get lockers locations and its availability
• Manage reservations on your lockers
• Get usage reports
• Manage notifications settings

Authentication

Lok API uses OAuth scheme, using access tokens to authenticate requests. When you request access to Lok API, you will get a client_id and a client_secret. With these credentials you can get an access token which should be included in each request:

GET /api/v2/some_resource HTTP/2
Host: api.clicknbox.com
Authorization: Bearer youraccesstoken 

Your client credentials grant access for a trusted entity, so make sure you store them securely.

All API requests must be made over HTTPS. Calls made over plain HTTP will fail. API requests without authentication will also fail.

User scopes

An access token has the scope of it's user. Each route has the following security scheme:

Every scope has the following allowed actions:

• admin is the Lok administrator. Has read access to all reservations and lockers.
• owner is the top-level user of the company. This scope grants access to all the lockers that are managed by your company.
• employee grants access to one location only.
• reporter grants read access to the lockers and reservations managed by your company.
• seller similarly as an owner, is a top-level user who has access to Lok public network.

Errors

Lok uses conventional HTTP response codes to indicate the success or failure of an API request. However, the field status_code is always returned for redundancy.

Responses with status other than 2xx are error responses:

• codes in the 4xx range indicate an error related to information provided
• codes in the 5xx range indicate an error with Lok servers.

Whenever you get an error response, it will have the following properties:

• type (string): The type of error returned.
• message (string): A human-readable message providing more details about the error.
• data (object): Some error types include additional details of the error.

Response example

{
  "status_code": 404,
  "type": "ENTITY_NOT_FOUND",
  "message": "Location not found",
  "data": {
     "id": "11446958822f"
  }
}

Error Types

Request errors

Authorization errors

Reservation errors

Logistic errors

Lok server errors

Third-party errors

Webhook

A Webhook is a callback URL to which our systems send the different events related to your reservations. On each call you can notify your user or operations team and create reports of events.

You can manage your company's webhook settings and subscribe to specific events only or enable/disable it. When adding your webhook for the first time, a secret will be generated that you can use later to validate incoming requests.

Set up a webhook

Data will be sent via HTTP POST method in JSON format and UTF-8 encoding. To confirm that you received a notification successfully, your server must return a 200 (OK) HTTP status code, any other status will be treated as an error and the request will be retried up to 50 times in increasing intervals.

Example with javascript:

var data = typeof req.body == 'string' ? JSON.parse(req.body) : req.body;

if (data.status == 'picked_up') {
var reservation_id = data.reservation_id;
//...
}

Notification payload

The information of the notification will have the following structure:

{
  "reservation_id": "5ccc9e33a97e2f8226ba36d2",
  "shipment_id": "Order 557",
  "status": “delivered”,
  "status_message": "Package received in the locker",
  "t": 1614202849096,
}

reservation_id

• Type: String
• Description: The reservation identifier that should be used in subsequent API calls

shipment_id

• Type: String
• Description: Identifier that the company assigned to the reservation

status

• Type: String
• Description: Current status of the reservation. Possible values are:
  • reserved: Reservation creation confirmation. This event is triggered whenever a new reservation is created or a pre-reservation is confirmed.
  • undelivered: Package waiting to be delivered
  • delivered: Package delivered in the locker
  • unpicked: Package waiting to be picked up
  • reopened: Package first alteration in the locker
  • reopened2: Second package alteration in the locker
  • cancelled: Reservation cancelled confirmation. This event is triggered either with an API cancellation or by using the cancellation token.
  • picked_up: Package was picked up

status_message

• Type: String
• Description: Human-readable description of the status

t

• Type: Number
• Description: Event triggered timestamp

The undelivered and unpicked events are notified daily until the package is delivered or picked up, respectively.

Notification signature

To verify that the request came from our servers, you can validate the body using the secret granted upon webhook creation:

const crypto = require('crypto');

const hmac = crypto.createHmac('sha256', YOUR_WEBHOOK_SECRET);

hmac.update(req.body);
const signature = hmac.digest('base64');

and compare signature against Lok-Signature header.