Bloq.It Partner API (1.35.0)

Download OpenAPI specification:Download

E-mail: hello@bloq.it License: Apache 2.0

Introduction

The Bloq.It API is organized around REST. Our API has resource-oriented URLs following the CRUD standard by applying the HTTP methods POST, GET, PUT and DELETE respectively. It returns JSON-encoded responses and uses the standard HTTP response codes and authentication.

To use our API freely you must be one of our partners, where in our dashboard you can create and manage your API Key that must be present in the header of every request to perform Authentication and Authorization. All the request to our API must be perform over HTTPS (HTTP + TLS).

Changelog

You can checkout the changelog of our API here

Important Concepts

In this API some words will be thrown around which can have several meanings. In this section it is specified what each term means.

The Bloq is a group of Lockers. The Locker or door is the small unit and they can have different sizes. Their size ranges from XS to XL.

Let's now move on to the types of operations that we offer. There are 4 pre established ways using a Locker, new ways can also be added on demand depending on your requirements. The four operations are:

  • Store operations - Allows an item to be stored and then collected by the same person. This can be used to keep your items safe when you are not there. An example of an use case for this operation is if you want to provide your customers with a safe and secure space where they can store their belongings.

  • Send operations - Allows a person to store an item which can then be retrieved by another user. The user that is allowed to retrieve the object is chosen at the start of the operation by the person storing the item. An example of an use case for this operation is if you want to provide a way that your customers can exchange items between them without them to be in the same place at the same time.

  • Delivery operations - Allows your company to leave a package in one of the Lockers/Doors and then warn one of your customers that their delivery is ready for pick-up! This is the operation that you must choose if you are doing last mile deliveries. For each of your items create a delivery choosing the door where the customer will pick up the item, send the notification with the pick up code for your customers and they will be able to pick up the item in the locker and you will be able to track the entire process. It can also be used for fist mile deliveries when the customers select the locker they want to use to place the item they are sending.

  • Return operations - Allows a customer to return a package to your company using one of the Lockers/Doors. Your customers must have a way of choosing the Bloq and the Locker/Door and then they will be able to return the item on that Locker. Together with the delivery operations this can also be used for first mile deliveries, the diference is that using returns you choose the Locker that your customers must use to drop the item. If you are using deliveries you can give that liberty to the customers and they will choose the Locker. There is also an integration between Deliveries and Returns. If a customers picked up an item from one of your Bloqs using a Delivery and wants to return the item you can generate a Return for the previous Delivery.

These are the 4 pre established ways that you use a Locker/Door. These are already implemented and ready to be used and we believe will cover most of your use case. However, if you have a very specific use case that required a diferent operation talk with our team, our system is implemented in a way that allows to create new operations very easily and fast.

All these operations follow a similar structure dispite their flow being different, so all operations are a type of a Rent. A Rent is the base structure to all operations and is nothing more than all the information necessary to track your items and the interactions with the Locker and the customers.

drawing

Talking about customers, we allow you to create a representation of your customers in our system. This is specially usefull if you want to send notifications to the customers with the pick up codes and if you want to keep track of the rents that a customer had over a period of time and in which lockers they had rents. This can also be useful in your application since allows your to show the complete history of rents for a customer. On the other hand, if you don't need this features you can always create new rents without a customer since it's always an optional argument.

Demo Server - All operations can be tested without a Bloq using the demo server, in the endpoint api.demo.bloq.it. You will have to mock up the interactions with the Bloqs by using the virtual endpoints that we provide. In every endpoint you can choose the server that you want to use in the dropdown.

Authentication

In order to authenticate, first login in your admin account to our backoffice. There you will be allowed to generate an API KEY with which it is possible to make API Requests.

Errors Description

Status Code Description
400 - Bad Request The request was unacceptable, often due to a missing required parameter or an invalid parameter format.
401 - Unauthorized Api Key is either non-existent or invalid.
403 - Forbidden The client does not have the necessary permissions to access the resource.
404 - Not Found The requested resource doesn't exist.
409 - Conflict The current state of the object is not compatible with the request. The request can be retried after the state has changed.
429 - Too Many Requests The client has sent too many requests in a given amount of time.
500 - Internal Server Error Something went wrong on our side.
502 - Bad Gateway Your request interacts with a Bloq or a Locker and they responded with some unexpected error
504 - Gateway Timeout Your request interacts with a Bloq or a Locker and they are not responding to our requests

Bloqs

This is an object representing your Bloqs. A Bloq is the main unit that controls and contains all of your Lockers. You can retrieve all of your Bloqs or you can simply query one Bloq informations by specifying the Bloq ID. Also, you can search for the available Bloqs near a location and open or close a specific Locker.

List all Bloqs

Lists the Bloqs associated with your account.

By using this endpoint you can retrieve any number of Bloqs, that can be limited and paginated by using the parameters described below.

Authorizations:
api_key
query Parameters
page
integer
Default: 1

A cursor to use in pagination. Page is an integer that defines the required page from the list.

limit
integer
Default: 10

A limit in the number of objects returned.

active
string
Default: "all"
Enum: "all" "active" "inactive"

Filter to search for all Bloqs, only active ones or only inactive

lockerType
string
Enum: "XS" "S" "M" "L" "XL"

When this parameter exists only bloqs that have this type of lockers will be shown

rentType
string
Enum: "store" "send" "delivery" "return"

When this parameter exists only bloqs that allow this type of rent will be shown

Responses

Request samples

const request = require('request');

const options = {
  method: 'GET',
  url: 'https://api.bloq.it/api/v1/public/bloqs',
  qs: {
    page: 'SOME_INTEGER_VALUE',
    limit: 'SOME_INTEGER_VALUE',
    active: 'SOME_STRING_VALUE',
    lockerType: 'SOME_STRING_VALUE',
    rentType: 'SOME_STRING_VALUE'
  },
  headers: {'X-API-KEY': 'REPLACE_KEY_VALUE'}
};

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

Response samples

Content type
application/json
{
  • "totalDocs": 2,
  • "page": 1,
  • "limit": 10,
  • "docs": [
    ]
}

Retrieve a Bloq

Retrieves a specific bloq by passing its ID as a parameter.

Authorizations:
api_key
path Parameters
bloqID
required
string

Pass the bloq ID necessary for the lookup query

Responses

Request samples

const request = require('request');

const options = {
  method: 'GET',
  url: 'https://api.bloq.it/api/v1/public/bloqs/%7BbloqID%7D',
  headers: {'X-API-KEY': 'REPLACE_KEY_VALUE'}
};

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

Response samples

Content type
application/json
{
  • "_id": "5e5fbcebd1195468b647aa02",
  • "active": true,
  • "details": {
    },
  • "code": "T1",
  • "createdAt": "2020-03-04T14:36:27.826Z",
  • "updatedAt": "2020-04-28T13:38:50.339Z",
  • "maxRentTimeHour": 2,
  • "supports": [
    ],
  • "location": {
    },
  • "price": {
    },
  • "lockersMeasures": {
    },
  • "status": {
    },
  • "lockers": [
    ]
}

Get Free Lockers

Lists all the lockers that are free (active and without a rent) for a given Bloq.

Authorizations:
api_key
path Parameters
bloqID
required
string

Pass the bloq ID necessary for the lookup query

Responses

Request samples

const request = require('request');

const options = {
  method: 'GET',
  url: 'https://api.bloq.it/api/v1/public/bloqs/%7BbloqID%7D/free-lockers',
  headers: {'X-API-KEY': 'REPLACE_KEY_VALUE'}
};

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

Response samples

Content type
application/json
[
  • {
    }
]

Get Bloqs by Locations

Using a latitude and longitude as parameters, all the Bloqs within maxDistance of the position are listed in the response.

Authorizations:
api_key
query Parameters
latitude
required
number <double>
Example: latitude=6.166201

The latitude of the center point

longitude
required
number <double>
Example: longitude=46.661362

The longitude of the center point

maxDistance
required
integer <int32> >= 1
Example: maxDistance=500

The maximum distance (in meters) from the center point until which the Bloqs are going to be returned

page
integer
Default: 1

A cursor to use in pagination. Page is an integer that defines the required page from the list.

limit
integer
Default: 10

A limit in the number of objects returned.

active
string
Default: "all"
Enum: "all" "active" "inactive"

Filter to search for all Bloqs, only active ones or only inactive

lockerType
string
Enum: "XS" "S" "M" "L" "XL"

When this parameter exists only bloqs that have this type of lockers will be shown

rentType
string
Enum: "store" "send" "delivery" "return"

When this parameter exists only bloqs that allow this type of rent will be shown

Responses

Request samples

const request = require('request');

const options = {
  method: 'GET',
  url: 'https://api.bloq.it/api/v1/public/bloqs/geoSearch',
  qs: {
    latitude: '6.166201',
    longitude: '46.661362',
    maxDistance: '500',
    page: 'SOME_INTEGER_VALUE',
    limit: 'SOME_INTEGER_VALUE',
    active: 'SOME_STRING_VALUE',
    lockerType: 'SOME_STRING_VALUE',
    rentType: 'SOME_STRING_VALUE'
  },
  headers: {'X-API-KEY': 'REPLACE_KEY_VALUE'}
};

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

Response samples

Content type
application/json
{
  • "totalDocs": 2,
  • "page": 1,
  • "limit": 10,
  • "docs": [
    ]
}

Update Bloq

Updates the Bloq with the id given in the parameters. Only the fields that are passed in the request body will be updated.

Authorizations:
api_key
path Parameters
bloqID
required
string

Pass the Bloq id that you wish to update

Request Body schema: application/json
active
boolean

Bloq Status in the system

title
string

This is how the Bloq can be identified

city
string

The city where the Bloq is located

code
string

The code that identifies a Bloq

address
string

Physical address of the Bloq

postalCode
string

Postal code of the Bloq

object

The location of the Bloq in the map

maxRentTimeHour
integer >= 1

The maximum rent time in hours

maxRentDeliveryTimeHour
integer >= 1

The maximum rent delivery time in hours

maxRentCollectTimeHour
integer >= 1

The maximum rent collect time in hours

metadata
object

The metadata of the Bloq, can be used to store any aditional information

Responses

Request samples

Content type
application/json
{
  • "active": true,
  • "title": "Discriptive title",
  • "city": "Lisbon",
  • "code": "ABC123",
  • "address": "string",
  • "postalCode": "1234-567",
  • "location": {
    },
  • "maxRentTimeHour": 2,
  • "maxRentDeliveryTimeHour": 2,
  • "maxRentCollectTimeHour": 2,
  • "metadata": { }
}

Response samples

Content type
application/json
{
  • "_id": "5e5fbcebd1195468b647aa02",
  • "active": true,
  • "details": {
    },
  • "code": "T1",
  • "createdAt": "2020-03-04T14:36:27.826Z",
  • "updatedAt": "2020-04-28T13:38:50.339Z",
  • "maxRentTimeHour": 2,
  • "supports": [
    ],
  • "location": {
    },
  • "price": {
    },
  • "lockersMeasures": {
    },
  • "status": {
    },
  • "lockers": [
    ]
}

Opens a Locker

Opens the Locker with the id given in the parameters. The Locker must not be allocated to any rent. If the Locker is allocated to a rent, then you must use the corresponding endpoint (In the rents, store, send or delivery, accordingly).

Authorizations:
api_key
path Parameters
bloqID
required
string

Pass the Bloq id where the locker you want to open is.

lockerID
required
string

Pass the Locker id that you wish to open

Responses

Request samples

const request = require('request');

const options = {
  method: 'PUT',
  url: 'https://api.bloq.it/api/v1/public/bloqs/%7BbloqID%7D/lockers/%7BlockerID%7D/open',
  headers: {'X-API-KEY': 'REPLACE_KEY_VALUE'}
};

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

Response samples

Content type
application/json
{
  • "_id": "5d5a6e83d1682b7194fc5f9c",
  • "rent": null,
  • "charger": true,
  • "objectDetection": false,
  • "isOpen": true,
  • "lastDoorOpeningTimestamp": "null",
  • "lockerTitle": "A1",
  • "bloq": "5d5a6e83d1682b7194fc5f91",
  • "type": "S",
  • "active": true
}

Open several Lockers

Opens several Lockers at once with the array of lockers ids given in the body. The given lockers must not be allocated to any rent, neither already open, neither from other bloqs. If the Locker is allocated to a rent, then you must use the corresponding endpoint (In the rents, store, send or delivery, accordingly).

Authorizations:
api_key
path Parameters
bloqID
required
string

Pass the Bloq id where the locker you want to open is.

Request Body schema: application/json
lockers
Array<string>

Pass the Lockers ids that you wish to open

Responses

Request samples

Content type
application/json
{
  • "lockers": [
    ]
}

Response samples

Content type
application/json
[
  • "5d5a6e83d1682b7194fc5f9c",
  • "5d5a6e83d1682b7194fc5f7g"
]

Close a Locker (virtual)

Changes the status of the Locker with the id given in the parameters to CLOSED. This operation is used for testing purposes, to simulate closing door behavior response from a real Locker.

Authorizations:
api_key
path Parameters
bloqID
required
string

Pass the Bloq id where the locker you want to open is.

lockerID
required
string

Pass the Locker id to which you want to close

Responses

Request samples

const request = require('request');

const options = {
  method: 'PUT',
  url: 'https://api.bloq.it/api/v1/public/bloqs/%7BbloqID%7D/lockers/%7BlockerID%7D/close',
  headers: {'X-API-KEY': 'REPLACE_KEY_VALUE'}
};

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

Response samples

Content type
application/json
{
  • "_id": "5d5a6e83d1682b7194fc5f9c",
  • "rent": null,
  • "charger": true,
  • "objectDetection": false,
  • "isOpen": false,
  • "lastDoorOpeningTimestamp": "null",
  • "lockerTitle": "A1",
  • "bloq": "5d5a6e83d1682b7194fc5f91",
  • "type": "S",
  • "active": true
}

Change a locker availability (enable or disable)

Changes the status of a locker, to disabled or enabled depending on the value sent on the request. Disabled lockers are not avaialable for new rents.

Authorizations:
api_key
path Parameters
bloqID
required
string

Pass the Bloq id which the locker belongs to.

lockerID
required
string

Pass the Locker id to which you to update.

Request Body schema: application/json
active
required
boolean

Flag with the new locker state, true -> enabled, false -> disabled

Responses

Request samples

Content type
application/json
{
  • "active": true
}

Response samples

Content type
application/json
{
  • "_id": "5d5a6e83d1682b7194fc5f9c",
  • "rent": null,
  • "charger": true,
  • "objectDetection": false,
  • "isOpen": false,
  • "lastDoorOpeningTimestamp": "null",
  • "lockerTitle": "A1",
  • "bloq": "5d5a6e83d1682b7194fc5f91",
  • "type": "S",
  • "active": true
}

Open or Collect

This endpoint will perform a normal collect item action if the door passed has an associated rent (the rent must pass the same conditions of when calling the collect item endpoint), or, if the door is free just opens it.

Authorizations:
api_key
path Parameters
bloqID
required
string

Pass the Bloq id which the locker belongs to.

lockerID
required
string

Pass the Locker id to which you to update.

Responses

Request samples

const request = require('request');

const options = {
  method: 'PUT',
  url: 'https://api.bloq.it/api/v1/public/bloqs/%7BbloqID%7D/lockers/%7BlockerID%7D/open-or-collect',
  headers: {'X-API-KEY': 'REPLACE_KEY_VALUE'}
};

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

Response samples

Content type
application/json
{
  • "_id": "5d5a6e83d1682b7194fc5f9c",
  • "rent": null,
  • "charger": true,
  • "objectDetection": false,
  • "isOpen": true,
  • "lastDoorOpeningTimestamp": "null",
  • "lockerTitle": "A1",
  • "bloq": "5d5a6e83d1682b7194fc5f91",
  • "type": "S",
  • "active": true
}

Bloq Locations

This is an object representing your Bloq Locations. A Bloq Location is a place where you can find a Bloq. You can retrieve all of your Bloq Locations or you can simply query one Bloq Location informations by specifying the Bloq Location ID.

Create Bloq Location

Creates a Bloq Location. A Bloq Location is a location that can be used as a reference for a future Bloq placement.

Authorizations:
api_key
Request Body schema: application/json
address
required
string

The address of the new Location for the Bloq

latitude
required
number <double>

The latitude of the Location

longitude
required
number <double>

The longitude of the Location

externalID
string

The external ID, is the Partner ID that they want to associate with this Location - can then be passed to the bloq external ID

name
string

The name of the Location

metadata
object

The metadata of the Location, can be used to store any additional information in the Key-Value format

Responses

Request samples

Content type
application/json
{
  • "address": "Street 123, 1100-123 Lisbon",
  • "latitude": 38.707163,
  • "longitude": -9.135517,
  • "externalID": "externalID-1",
  • "name": "Supermarket Locker 01",
  • "metadata": {
    }
}

Response samples

Content type
application/json
{
  • "address": "Street 123, 1100-123 Lisbon",
  • "externalID": "externalID-1",
  • "name": "Supermarket Locker 01",
  • "location": {
    },
  • "state": "created",
  • "metadata": {
    }
}

List Bloq Locations

Lists the Bloq Locations associated with your account. By using this endpoint you can retrieve any number of Bloq Locations, that can be limited and paginated by using the parameters described below.

Authorizations:
api_key
query Parameters
page
integer
Default: 1

A cursor to use in pagination. Page is an integer that defines the required page from the list.

limit
integer
Default: 10

A limit in the number of objects returned.

externalID
string

The external ID of the Bloq Location to filter for

name
string

The name of the Bloq Location to filter for

address
string

The address of the Bloq Location to filter for

state
string
Enum: "created" "deployed" "churned"

The state of the Bloq Location to filter for

Responses

Request samples

const request = require('request');

const options = {
  method: 'GET',
  url: 'https://api.bloq.it/api/v1/public/bloq-locations',
  qs: {
    page: 'SOME_INTEGER_VALUE',
    limit: 'SOME_INTEGER_VALUE',
    externalID: 'SOME_STRING_VALUE',
    name: 'SOME_STRING_VALUE',
    address: 'SOME_STRING_VALUE',
    state: 'SOME_STRING_VALUE'
  },
  headers: {'X-API-KEY': 'REPLACE_KEY_VALUE'}
};

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

Response samples

Content type
application/json
{
  • "totalDocs": 2,
  • "page": 1,
  • "limit": 15,
  • "docs": [
    ]
}

Get Bloq Location

Gets the Bloq Location with the id given in the parameters.

Authorizations:
api_key
path Parameters
bloqLocationID
required
string

Pass the Bloq Location id that you wish to retrieve

Responses

Request samples

const request = require('request');

const options = {
  method: 'GET',
  url: 'https://api.bloq.it/api/v1/public/bloq-locations/%7BbloqLocationID%7D',
  headers: {'X-API-KEY': 'REPLACE_KEY_VALUE'}
};

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

Response samples

Content type
application/json
{
  • "address": "Street 123, 1100-123 Lisbon",
  • "externalID": "externalID-1",
  • "name": "Supermarket Locker 01",
  • "location": {
    },
  • "state": "created",
  • "metadata": {
    }
}

Update Bloq Location

Updates the Bloq Location with the id given in the parameters. Only the fields that are passed in the request body will be updated.

Authorizations:
api_key
path Parameters
bloqLocationID
required
string

Pass the Bloq Location id that you wish to update

Request Body schema: application/json
address
string

The address of the new Location for the Bloq

latitude
number <double>

The latitude of the Location

longitude
number <double>

The longitude of the Location

externalID
string

The external ID, is the Partner ID that they want to associate with this Location - can then be passed to the bloq external ID

name
string

The name of the Location

metadata
object

The metadata of the Location, can be used to store any additional information in the Key-Value format

state
string
Value: "churned"

The state of the Bloq Location (For now we only accept the value "churned")

Responses

Request samples

Content type
application/json
{
  • "address": "Street 123, 1100-123 Lisbon",
  • "latitude": 38.707163,
  • "longitude": -9.135517,
  • "externalID": "externalID-1",
  • "name": "Supermarket Locker 01",
  • "metadata": {
    },
  • "state": "churned"
}

Response samples

Content type
application/json
{
  • "address": "Street 123, 1100-123 Lisbon",
  • "externalID": "externalID-1",
  • "name": "Supermarket Locker 01",
  • "location": {
    },
  • "state": "created",
  • "metadata": {
    }
}

Get Bloq Location by External ID

Gets the Bloq Location with the external ID given in the parameters.

Authorizations:
api_key
path Parameters
externalID
required
string

Pass the Bloq Location external ID that you wish to retrieve

Responses

Request samples

const request = require('request');

const options = {
  method: 'GET',
  url: 'https://api.bloq.it/api/v1/public/bloq-locations/external-id/%7BexternalID%7D',
  headers: {'X-API-KEY': 'REPLACE_KEY_VALUE'}
};

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

Response samples

Content type
application/json
{
  • "address": "Street 123, 1100-123 Lisbon",
  • "externalID": "externalID-1",
  • "name": "Supermarket Locker 01",
  • "location": {
    },
  • "state": "created",
  • "metadata": {
    }
}

Update Bloq Location by External ID

Updates the Bloq Location with the external ID given in the parameters. Only the fields that are passed in the request body will be updated.

Authorizations:
api_key
path Parameters
externalID
required
string

Pass the Bloq Location external ID that you wish to update

Request Body schema: application/json
address
string

The address of the new Location for the Bloq

latitude
number <double>

The latitude of the Location

longitude
number <double>

The longitude of the Location

externalID
string

The external ID, is the Partner ID that they want to associate with this Location - can then be passed to the bloq external ID

name
string

The name of the Location

metadata
object

The metadata of the Location, can be used to store any additional information in the Key-Value format

state
string
Value: "churned"

The state of the Bloq Location (For now we only accept the value "churned")

Responses

Request samples

Content type
application/json
{
  • "address": "Street 123, 1100-123 Lisbon",
  • "latitude": 38.707163,
  • "longitude": -9.135517,
  • "externalID": "externalID-1",
  • "name": "Supermarket Locker 01",
  • "metadata": {
    },
  • "state": "churned"
}

Response samples

Content type
application/json
{
  • "address": "Street 123, 1100-123 Lisbon",
  • "externalID": "externalID-1",
  • "name": "Supermarket Locker 01",
  • "location": {
    },
  • "state": "created",
  • "metadata": {
    }
}

Printer

All the endpoints that perform some action over the printers on the physical Bloqs.

Get amount of labels available (Bulk)

Get the amount of labels available on all the Bloqs. It's a bulk request that fetches the amount of labels left for each bloq

Authorizations:
api_key
query Parameters
page
integer
Default: 1

A cursor to use in pagination. Page is an integer that defines the required page from the list. If 0 is passed to both limit and page then all the bloqs are returned.

limit
integer
Default: 10

A limit in the number of objects returned. If 0 is passed to both limit and page then all the bloqs are returned.

Responses

Request samples

const request = require('request');

const options = {
  method: 'GET',
  url: 'https://api.bloq.it/api/v1/public/bloqs/labels-amount-available',
  qs: {page: 'SOME_INTEGER_VALUE', limit: 'SOME_INTEGER_VALUE'},
  headers: {'X-API-KEY': 'REPLACE_KEY_VALUE'}
};

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

Response samples

Content type
application/json
{
  • "totalDocs": 2,
  • "page": 1,
  • "limit": 15,
  • "docs": [
    ]
}

Get amount of labels available

Get the amount of labels available for a given bloq.

Authorizations:
api_key
path Parameters
bloqID
required
string

Pass the Bloq id to which to want to retrieve the amount of labels available.

Responses

Request samples

const request = require('request');

const options = {
  method: 'GET',
  url: 'https://api.bloq.it/api/v1/public/bloqs/%7BbloqID%7D/labels-amount-available',
  headers: {'X-API-KEY': 'REPLACE_KEY_VALUE'}
};

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

Response samples

Content type
application/json
{
  • "remainingLabels": "120"
}

Print a Label

Makes a resquest to a Bloq asking to print a label based on the data passed. This endpoint can only be called for the Bloqs that have a printer.

Authorizations:
api_key
path Parameters
bloqID
required
string

Pass the Bloq id where the locker you want to open is.

query Parameters
templateID
string

The identifier of the template you wish to print. The template must be associated with the Bloq to which you are doing the request. Required if you want to print based on a template.

Request Body schema:
content
object

The content that will be used to fill the template. When the content is sent a templateID is required.

Responses

Request samples

Content type
{
  • "content": { }
}

Response samples

Content type
application/json
{
  • "_id": "5d5a6e83d1682b7194fc5f9c",
  • "rent": null,
  • "charger": true,
  • "objectDetection": false,
  • "isOpen": false,
  • "lastDoorOpeningTimestamp": "null",
  • "lockerTitle": "A1",
  • "bloq": "5d5a6e83d1682b7194fc5f91",
  • "type": "S",
  • "active": true
}

Notify Labels Roll Replacement

Endpoint to be called end the process of changing the printer labels roll is finished. Pass the bloq ID for the bloq that has been changed.

Authorizations:
api_key
path Parameters
bloqID
required
string

Pass the Bloq id where the locker you want to open is.

Responses

Request samples

const request = require('request');

const options = {
  method: 'PUT',
  url: 'https://api.bloq.it/api/v1/public/bloqs/%7BbloqID%7D/notify-label-replacement',
  headers: {'X-API-KEY': 'REPLACE_KEY_VALUE'}
};

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

Response samples

Content type
application/json
{
  • "code": "bloqIDInvalid",
  • "message": "Invalid bloqID. bloqID is either missing or has a wrong format."
}

Rents

This is an object representing your Rents. A Rent can have four types: Store, Send, Delivery and Return. For each type of rent there are specific methods that you can call. In this section are the general methods that are for all types of rents.

List all rents

Lists the rents associated with your account.

By using this endpoint you can retrieve any number of rents, that can be limited and paginated by using the parameters described below.

Authorizations:
api_key
query Parameters
page
integer
Default: 1

A cursor to use in pagination. Page is an integer that defines the required page from the list.

limit
integer
Default: 10

A limit in the number of objects returned.

customerID
string

The ID of the Customer to filter for

bloqID
string

The ID of the Bloq to filter for

rentType
string
Enum: "store" "send" "delivery"

The type of rents to filter for

rentStates
Array<string>
Enum: "created" "starting" "in_progress" "locker_opened" "collect_item" "price_calculation" "payment_attempt" "expired" "finished" "reserved" "cancelled" "in_transit" "ready_for_pickup"

Array of states of rent to filter for

customerQuery
string

The customerQuery allows to filter rents by Email or PhoneNumber

startDate
string <date-time>

The starting date filter

endDate
string <date-time>

The ending date filter

externalID
string

Rent's external ID

Responses

Request samples

const request = require('request');

const options = {
  method: 'GET',
  url: 'https://api.bloq.it/api/v1/public/rents',
  qs: {
    page: 'SOME_INTEGER_VALUE',
    limit: 'SOME_INTEGER_VALUE',
    customerID: 'SOME_STRING_VALUE',
    bloqID: 'SOME_STRING_VALUE',
    rentType: 'SOME_STRING_VALUE',
    rentStates: 'SOME_ARRAY<STRING>_VALUE',
    customerQuery: 'SOME_STRING_VALUE',
    startDate: 'SOME_STRING_VALUE',
    endDate: 'SOME_STRING_VALUE',
    externalID: 'SOME_STRING_VALUE'
  },
  headers: {'X-API-KEY': 'REPLACE_KEY_VALUE'}
};

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

Response samples

Content type
application/json
{
  • "docs": [
    ],
  • "totalDocs": 50,
  • "limit": 10,
  • "page": 1
}

List all active rents

Lists the active rents associated with your account. An active rent is a rent that has not finished.

By using this endpoint you can retrieve any number of active rents, that can be limited and paginated by using the parameters described below.

Authorizations:
api_key
query Parameters
page
integer
Default: 1

A cursor to use in pagination. Page is an integer that defines the required page from the list.

limit
integer
Default: 10

A limit in the number of objects returned.

customerID
string

The ID of the Customer to filter for

bloqID
string

The ID of the Bloq to filter for

rentType
string
Enum: "store" "send" "delivery"

The type of rents to filter for

rentStates
Array<string>
Enum: "created" "starting" "in_progress" "locker_opened" "collect_item" "price_calculation" "payment_attempt" "expired" "reserved" "cancelled" "in_transit" "ready_for_pickup"

Array of states of rent to filter for

customerQuery
string

The customerQuery allows to filter rents by Email or PhoneNumber

startDate
string <date-time>

The starting date filter

externalID
string

Rent's external ID

Responses

Request samples

const request = require('request');

const options = {
  method: 'GET',
  url: 'https://api.bloq.it/api/v1/public/rents/active',
  qs: {
    page: 'SOME_INTEGER_VALUE',
    limit: 'SOME_INTEGER_VALUE',
    customerID: 'SOME_STRING_VALUE',
    bloqID: 'SOME_STRING_VALUE',
    rentType: 'SOME_STRING_VALUE',
    rentStates: 'SOME_ARRAY<STRING>_VALUE',
    customerQuery: 'SOME_STRING_VALUE',
    startDate: 'SOME_STRING_VALUE',
    externalID: 'SOME_STRING_VALUE'
  },
  headers: {'X-API-KEY': 'REPLACE_KEY_VALUE'}
};

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

Response samples

Content type
application/json
{
  • "docs": [
    ],
  • "totalDocs": 50,
  • "limit": 10,
  • "page": 1
}

List all rents with state

Lists the rents associated with your account that reached a given state within the given time frame.

By using this endpoint you can retrieve any number of rents, that can be limited and paginated by using the parameters described below.

Authorizations:
api_key
query Parameters
page
integer
Default: 1

A cursor to use in pagination. Page is an integer that defines the required page from the list.

limit
integer
Default: 10

A limit in the number of objects returned.

state
required
string
Enum: "created" "starting" "in_progress" "locker_opened" "collect_item" "price_calculation" "payment_attempt" "expired" "reserved" "cancelled" "in_transit" "ready_for_pickup"

The state of the rent to filter for.

from
required
date-time

The date with the format YYYY-MM-DDTHH:MM:SS to search the rents that reached the state from the specified date.

until
required
date-time

The date with the format YYYY-MM-DDTHH:MM:SS to search the rents that reached the state until the specified date.

Responses

Request samples

const request = require('request');

const options = {
  method: 'GET',
  url: 'https://api.bloq.it/api/v1/public/rents/reached-state',
  qs: {
    page: 'SOME_INTEGER_VALUE',
    limit: 'SOME_INTEGER_VALUE',
    state: 'SOME_STRING_VALUE',
    from: 'SOME_DATE-TIME_VALUE',
    until: 'SOME_DATE-TIME_VALUE'
  },
  headers: {'X-API-KEY': 'REPLACE_KEY_VALUE'}
};

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

Response samples

Content type
application/json
{
  • "docs": [
    ],
  • "totalDocs": 50,
  • "limit": 10,
  • "page": 1
}

Retrieve a rent (External ID)

Endpoint to retrieve information about a rent through its external ID.

Authorizations:
api_key
path Parameters
externalID
required
string

Pass the external rent ID to retrieve all the information about its status

Responses

Request samples

const request = require('request');

const options = {
  method: 'GET',
  url: 'https://api.bloq.it/api/v1/public/rents/external/%7BexternalID%7D',
  headers: {'X-API-KEY': 'REPLACE_KEY_VALUE'}
};

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

Response samples

Content type
application/json
{
  • "_id": "5f85c02704d61b14f47c78a0",
  • "type": "delivery",
  • "state": "finished",
  • "states": [
    ],
  • "customer": {
    },
  • "startDate": "2020-10-13T14:56:39.561Z",
  • "endDate": "2020-10-13T14:57:47.007Z",
  • "details": {
    },
  • "locker": {
    },
  • "pricing": {
    }
}

Rent History

Retrieve the history of a rent.

By using this endpoint you can retrieve a rent history, that is represented by an array of events, anything that happens to the rent was registered (more about events in webhooks section).

Authorizations:
api_key
query Parameters
rentID
required
string

The rent identifier - rentID

Responses

Request samples

const request = require('request');

const options = {
  method: 'GET',
  url: 'https://api.bloq.it/api/v1/public/rents/%7BrentID%7D/history',
  qs: {rentID: 'SOME_STRING_VALUE'},
  headers: {'X-API-KEY': 'REPLACE_KEY_VALUE'}
};

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

Response samples

Content type
application/json
[
  • {
    },
  • {
    },
  • {
    }
]

Retrieve a rent

Endpoint to retrieve information about a rent through its ID.

Authorizations:
api_key
path Parameters
rentID
required
string

Pass the rent ID to retrieve all the information about its status

Responses

Request samples

const request = require('request');

const options = {
  method: 'GET',
  url: 'https://api.bloq.it/api/v1/public/rents/%7BrentID%7D',
  headers: {'X-API-KEY': 'REPLACE_KEY_VALUE'}
};

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

Response samples

Content type
application/json
{
  • "_id": "5f85c02704d61b14f47c78a0",
  • "type": "delivery",
  • "state": "finished",
  • "states": [
    ],
  • "customer": {
    },
  • "startDate": "2020-10-13T14:56:39.561Z",
  • "endDate": "2020-10-13T14:57:47.007Z",
  • "details": {
    },
  • "locker": {
    },
  • "pricing": {
    }
}

Update Rent

Update a specific Rent by passing its ID.

You can update an already created rent by passing some fields that you want to update.

Some updates can only be made before the rent reaches a specific state: deliveryDateLimit, dropOffCode, labelTemplateID, labelContent, desiredLockerType and pickUpCodes can only be updated while the rent is on the CREATED or Reserved state, while expiryDate, externalID and collectTimeLimit while the rent has not been collected.

Authorizations:
api_key
path Parameters
rentID
required
string

Pass the rent ID to retrieve all the information about its status

Request Body schema: application/json
expiryDate
string <date-time>

Determined date after which the rent can not be picked up. This field can't be updated after the pick up phase.

deliveryDateLimit
string <date-time>

Date limit to place an item in the locker. This field can't be updated after the drop off phase.

collectTimeLimit
number <integer>

Amount of hours a client has to collect the item from the locker. This field can't be updated after the pick up phase.

externalID
string

String used to identify the rent externally. You can save your own local identifier for the rent here. This field can't be updated after the pick up phase.

dropOffCode
string

String used to verify the user on the Bloq during the drop off process. This field can't be updated after the drop off phase.

desiredLockerType
string

If you already know what type of locker should be used on this delivery then send the desiredLockerType with the desired locker type (XS, S, ..., XL). This field can't be updated after the drop off phase.

labelContent
object

If you send the labelTemplateID then you must send the labelContent with an object that can be used to send the label content that can be printed from the Bloq for this rent. This field can't be updated after the pick up phase.

labelTemplateID
String

If you send the labelContent then you must send the labelTemplateID with the template ID that will be used as template for the label. This template will then be filled with the label content. This field can't be updated after the pick up phase.

pickUpCodes
object

This is a dynamic object that allows you to use multiple pick up codes for the same rent. It's a JSON object where the key is the name of the code and the value is the code, for instance { 'user' : '2121' }. This field can't be updated after the pick up phase.

operationType
string
Enum: "firstMile" "lastMile"

You can specify if a delivery is a First Mile or Last Mile delivery. Indicating the operation type will distinguish between rents that should be picked up by the courier or by the final user.

prePickUpActions
Array of arrays
Items Value: "mfa"

Set of actions, validations and/or flows that need to be done during the pick up process but before opening the door

carrier
string

An identifier for the carrier responsabible for this delivery operation, can be used to differentiate rents that need to be picked up by a courier associated with a specific carrier

Responses

Request samples

Content type
application/json
{
  • "expiryDate": "2019-08-24T14:15:22Z",
  • "deliveryDateLimit": "2019-08-24T14:15:22Z",
  • "collectTimeLimit": 0,
  • "externalID": "string",
  • "dropOffCode": "string",
  • "desiredLockerType": "string",
  • "labelContent": { },
  • "labelTemplateID": null,
  • "pickUpCodes": {
    },
  • "operationType": "firstMile",
  • "prePickUpActions": [
    ],
  • "carrier": "string"
}

Response samples

Content type
application/json
{
  • "docs": [
    ],
  • "totalDocs": 50,
  • "limit": 10,
  • "page": 1
}

Extends a rent expiry date

Endpoint to extend the rent expiry date by giving the new expiry date.

Authorizations:
api_key
path Parameters
rentID
required
string

Pass the rent ID to that will be updated

Request Body schema: application/json
expiryDate
string <date-time>

The new expiry date

Responses

Request samples

Content type
application/json
{
  • "expiryDate": "2019-08-24T14:15:22Z"
}

Response samples

Content type
application/json
{
  • "_id": "5f85c02704d61b14f47c78a0",
  • "type": "delivery",
  • "state": "finished",
  • "states": [
    ],
  • "customer": {
    },
  • "startDate": "2020-10-13T14:56:39.561Z",
  • "endDate": "2020-10-13T14:57:47.007Z",
  • "details": {
    },
  • "locker": {
    },
  • "pricing": {
    }
}

Open a Locker

Opens the Locker associated with a Rent by its ID and changes its state to OPEN.

Authorizations:
api_key
path Parameters
rentID
required
string

Pass the rentID to which the customer want to open the locker.

Responses

Request samples

const request = require('request');

const options = {
  method: 'PUT',
  url: 'https://api.bloq.it/api/v1/public/rents/%7BrentID%7D/lockers/open',
  headers: {'X-API-KEY': 'REPLACE_KEY_VALUE'}
};

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

Response samples

Content type
application/json
{
  • "_id": "5f85c02704d61b14f47c78a0",
  • "type": "store",
  • "state": "locker_opened",
  • "states": [
    ],
  • "customer": "5f7dc9fc04d61b14f47c6f00",
  • "startDate": "2020-10-13T14:56:39.561Z",
  • "expiryDate": "2020-10-13T14:57:47.007Z",
  • "details": {
    },
  • "locker": "5d5a6e83d1682b7194fc5f9c",
  • "pricing": {
    }
}

Cancels a Rent

Endpoint to cancel an existing rent (store, send delivery, return). Given the rentID our application will change its state to CANCELED.

IMPORTANT: Cancelling the rent will not make it finish. The locker will still be allocated to the rent. In order to finish it either use "Collect an Item" or "Finish a Rent". The former allows you to retrieve any item that would still be in the locker, whilst the latter finishes the rent without opening the locker.

Authorizations:
api_key
path Parameters
rentID
required
string

Rent ID

Responses

Request samples

const request = require('request');

const options = {
  method: 'PUT',
  url: 'https://api.bloq.it/api/v1/public/rents/%7BrentID%7D/cancel',
  headers: {'X-API-KEY': 'REPLACE_KEY_VALUE'}
};

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

Response samples

Content type
application/json
{
  • "_id": "5f85c02704d61b14f47c78a0",
  • "type": "send",
  • "state": "cancelled",
  • "states": [
    ],
  • "customer": "5f7dc9fc04d61b14f47c6f00",
  • "startDate": "2020-10-13T14:56:39.561Z",
  • "endDate": "2020-10-13T14:57:47.007Z",
  • "details": {
    },
  • "locker": "5d5a6e83d1682b7194fc5f9c",
  • "pricing": {
    }
}

Collect an Item

Endpoint to collect an item from a locker. It will open the locker such that the user can retrieve the item from inside it. To call this endpoint the rent must be in the In Progress, Expired or Cancelled state.

Authorizations:
api_key
path Parameters
rentID
required
string

Rent ID

Responses

Request samples

const request = require('request');

const options = {
  method: 'PUT',
  url: 'https://api.bloq.it/api/v1/public/rents/%7BrentID%7D/collect',
  headers: {'X-API-KEY': 'REPLACE_KEY_VALUE'}
};

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

Response samples

Content type
application/json
{
  • "_id": "5f85c02704d61b14f47c78a0",
  • "type": "delivery",
  • "state": "collect_item",
  • "states": [
    ],
  • "customer": "5f7dc9fc04d61b14f47c6f00",
  • "startDate": "2020-10-13T14:56:39.561Z",
  • "endDate": "2020-10-13T14:57:47.007Z",
  • "details": {
    },
  • "locker": "5d5a6e83d1682b7194fc5f9c",
  • "pricing": {
    }
}

Finish a Rent

Endpoint to finish the rent without collecting any item after the rent was cancelled or expired.

Authorizations:
api_key
path Parameters
rentID
required
string

Rent ID

Responses

Request samples

const request = require('request');

const options = {
  method: 'PUT',
  url: 'https://api.bloq.it/api/v1/public/rents/%7BrentID%7D/finish',
  headers: {'X-API-KEY': 'REPLACE_KEY_VALUE'}
};

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

Response samples

Content type
application/json
{
  • "_id": "5f85c02704d61b14f47c78a0",
  • "type": "delivery",
  • "state": "finished",
  • "states": [
    ],
  • "customer": "5f7dc9fc04d61b14f47c6f00",
  • "startDate": "2020-10-13T14:56:39.561Z",
  • "endDate": "2020-10-13T14:57:47.007Z",
  • "details": {
    },
  • "locker": "5d5a6e83d1682b7194fc5f9c",
  • "pricing": {
    }
}

Rents Testing

These group of endpoints are used for testing purposes only, in order to simulate responses from a real Bloq or Locker. When calling endpoints in this group we recommend leaving an interval of time between requests to make sure they are processed in the correct order.

Simulates open w/ keypad

Sends a signal simulating that the pickup code was used in the keypad in order to open the locker and that it was correct. Used only for testing.

Authorizations:
api_key
path Parameters
rentID
required
string

Pass the rentID to which the customer want to open the locker.

Responses

Request samples

const request = require('request');

const options = {
  method: 'PUT',
  url: 'https://api.bloq.it/api/v1/public/rent-sims/%7BrentID%7D/lockers/keypad',
  headers: {'X-API-KEY': 'REPLACE_KEY_VALUE'}
};

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

Response samples

Content type
application/json
{
  • "_id": "5f85c02704d61b14f47c78a0",
  • "type": "store",
  • "state": "collect_item",
  • "states": [
    ],
  • "customer": "5f7dc9fc04d61b14f47c6f00",
  • "startDate": "2020-10-13T14:56:39.561Z",
  • "expiryDate": "2020-10-13T14:57:47.007Z",
  • "details": {
    },
  • "locker": "5d5a6e83d1682b7194fc5f9c",
  • "pricing": {
    }
}

Simulates closing a Locker

Sends a signal simulating that the locker was physically closed. Used only for testing.

Authorizations:
api_key
path Parameters
rentID
required
string

Pass the rentID to which the customer want to open the locker.

Responses

Request samples

const request = require('request');

const options = {
  method: 'PUT',
  url: 'https://api.bloq.it/api/v1/public/rent-sims/%7BrentID%7D/lockers/close',
  headers: {'X-API-KEY': 'REPLACE_KEY_VALUE'}
};

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

Response samples

Content type
application/json
{
  • "_id": "5f85c02704d61b14f47c78a0",
  • "type": "store",
  • "state": "in_progress",
  • "states": [
    ],
  • "customer": "5f7dc9fc04d61b14f47c6f00",
  • "startDate": "2020-10-13T14:56:39.561Z",
  • "expiryDate": "2020-10-13T14:57:47.007Z",
  • "details": {
    },
  • "locker": "5d5a6e83d1682b7194fc5f9c",
  • "pricing": {
    }
}

Store Operations

This is an object representing your Store operations. A Store is a type of rent, together with Send, Delivery and Return. You can retrieve all your Store operations or you can query one Store informations by specifying its ID. Additionally, you can start a new Store and also end a Store operation. drawing

Start a Store operation

Start a Store operation on the Locker with the given ID. The server creates a new store and associates it with the client, using the apikey to detect the correct client, and with the Locker using the passed Locker id to find the correct Locker.

Authorizations:
api_key
query Parameters
lockerID
required
string

Locker id of the locker that the customer wish to start a rent.

customerID
string

Customer id of the customer starting a rent.

Request Body schema: application/json
pickUpCodes
object

This is a dynamic object that allows you to use multiple pick up codes for the same rent. It's a JSON object where the key is the name of the code and the value is the code, for instance { 'user' : '2121' }

Responses

Request samples

Content type
application/json
{
  • "pickUpCodes": {
    }
}

Response samples

Content type
application/json
{
  • "_id": "5f85c02704d61b14f47c78a0",
  • "type": "store",
  • "state": "starting",
  • "states": [
    ],
  • "customer": "5f7dc9fc04d61b14f47c6f00",
  • "locker": "5d5a6e83d1682b7194fc5f9c",
  • "startDate": "2019-08-19T09:40:19.343+00:00",
  • "expiryDate": "2019-08-19T11:40:19.343+00:00",
  • "details": {
    },
  • "pricing": {
    }
}

Ends a Store operation

Ends the Store operation identified by the ID passed in the parameters.

Authorizations:
api_key
path Parameters
rentID
required
string

Pass the ID of the Store operation being finished.

Request Body schema: application/json
openLocker
boolean
Default: false

Flag to use in the case that is necessary to open the locker when the store ends

Responses

Request samples

Content type
application/json
{
  • "openLocker": false
}

Response samples

Content type
application/json
{
  • "_id": "5f85c02704d61b14f47c78a0",
  • "type": "store",
  • "state": "finished",
  • "states": [
    ],
  • "customer": "5f7dc9fc04d61b14f47c6f00",
  • "locker": "5d5a6e83d1682b7194fc5f9c",
  • "startDate": "2019-08-19T09:40:19.343+00:00",
  • "endDate": "2019-08-19T10:40:19.343+00:00",
  • "details": {
    },
  • "pricing": {
    }
}

Send Operations

This is an object representing your Send operations. A Send is a type of rent, together with Store, Delivery and Return. You can retrieve all your Sends operations or you can query one Send informations by specifying its ID. Additionally, you can start a new Send and also end a Send operation. drawing

Start a Send operation

Start a rent on the Locker with the ID passed in the parameters The server creates a new rent of type Store and associates it with the client, using the apiKey to detect the correct client, and with the Locker using the lockerID provided.

Authorizations:
api_key
query Parameters
lockerID
required
string

Pass the lockerID of the Locker that is going to be used

customerID
string

Customer id of the customer starting a rent.

Request Body schema: application/json
phoneNumber
required
string

The phone number for notification.

pickUpCodes
object

This is a dynamic object that allows you to use multiple pick up codes for the same rent. It's a JSON object where the key is the name of the code and the value is the code, for instance { 'user' : '2121' }

Responses

Request samples

Content type
application/json
{
  • "phoneNumber": "+351919090909",
  • "pickUpCodes": { }
}

Response samples

Content type
application/json
{
  • "_id": "5f85c02704d61b14f47c78a0",
  • "type": "send",
  • "state": "starting",
  • "states": [
    ],
  • "startDate": "2019-08-19T09:40:19.343+00:00",
  • "expiryDate": "2019-08-19T11:40:19.343+00:00",
  • "customer": "5f7dc9fc04d61b14f47c6f00",
  • "locker": "5d5a6e83d1682b7194fc5f9c",
  • "details": {
    },
  • "pricing": {
    }
}

Delivery Operations

This is an object representing your Deliveries operations. A Delivery is a type of rent, together with Store, Send and Return. You can retrieve all your Delivery operations or you can query one Delivery informations by specifying its ID. Additionally, you can create a new Delivery by reserving a Locker to it, and also cancel an existing Delivery. drawing When you cancel a delivery the locker is still reserved to it, so you have two options to complete the delivery: A) You need to open the locker because there is an item placed inside it, so you should call the retrieve item endpoint that will open the locker, move the delivery to the Collect Item state, and then to the Finished State. B) The locker is empty, so to free it (make it available to other rents) you must call the End Rent Endpoint that passes the delivery to the Finished state. The figure bellow illustrate the transitions in both cases, A and B. drawing

A Delivery has a special parameter, the expiry date. The expiry date is the limit date until which the client can pickup the delivery. When a delivery passes the expiry date the delivery progresses to the Expired State. Once in the Expired State you have the same two options as in the cancelled state. The figure bellow illustrate the transitions in both cases, A and B. drawing

Create Delivery Operation

When a user makes a purchase, and after choosing in which Bloq it should be delivered, the application creates a new rent of type Delivery and associates this new rent with the specified Locker.

Warning: after verion 1.17.0 there is the possibility to send pickUpCode and pickUpCodes, however when the request has both a 400 error will be return as you should only use one of them.

Authorizations:
api_key
query Parameters
lockerID
string

If you want to reserve at an early stage a specific locker pass the ID of the Locker being reserved.

bloqID
string

If you want to reserve at an early stage a specific locker pass the ID of the Bloq being reserved.

customerID
string

Customer id of the customer starting a rent.

Request Body schema: application/json
expiryDate
string <date-time>

Determined date after which the rent can not be picked up. In case you want to create a delivery withou a Bloq you must send an expiry date or a delivery date limit such that we can have a limit for the delivery. Otherwise we would have a pending delivery forever.

deliveryDateLimit
string <date-time>

Date limit to place an item in the locker. In case you want to create a delivery withou a Bloq you must send an expiry date or a delivery date limit such that we can have a limit for the delivery. Otherwise we would have a pending delivery forever.

collectTimeLimit
number <integer>

Amount of hours a client has to collect the item from the locker.

notificationOptions
Array of arrays
Items Enum: "sms" "email"

List of methods used to deliver a notification to the client.

externalID
string

String used to identify the rent externally. You can save your own local identifier for the rent here.

object

Optional object that can be used instead of customerID to create a customer on the go.

pickUpCode
string <= 14

String used to verify the user on the Bloq during the pick up process

dropOffCode
string

String used to verify the user on the Bloq during the drop off process

desiredLockerType
string

If you already know what type of locker should be used on this delivery then send the desiredLockerType with the desired locker type (XS, S, ..., XL)

labelContent
object

Optional object that can be used to send the label content that can be printed from the Bloq for this rent. It's required if you send the labelTemplateID.

labelTemplateID
String

If you send the labelContent then you must send the labelTemplateID with the template ID that will be used as template for the label. This template will then be filled with the label content.

pickUpCodes
object

This is a dynamic object that allows you to use multiple pick up codes for the same rent. It's a JSON object where the key is the name of the code and the value is the code, for instance { 'user' : '2121' }

operationType
string
Enum: "firstMile" "lastMile"

You can specify if a delivery is a First Mile or Last Mile delivery. Indicating the operation type will distinguish between rents that should be picked up by the courier or by the final user.

carrier
string

An identifier for the carrier responsabible for this delivery operation, can be used to differentiate rents that need to be picked up by a courier associated with a specific carrier

prePickUpActions
Array of arrays
Items Value: "mfa"

Set of actions, validations and/or flows that need to be done during the pick up process but before opening the door

Responses

Request samples

Content type
application/json
{
  • "expiryDate": "2019-08-24T14:15:22Z",
  • "deliveryDateLimit": "2019-08-24T14:15:22Z",
  • "collectTimeLimit": 0,
  • "notificationOptions": [
    ],
  • "externalID": "string",
  • "customer": {
    },
  • "pickUpCode": "string",
  • "dropOffCode": "string",
  • "desiredLockerType": "string",
  • "labelContent": { },
  • "labelTemplateID": null,
  • "pickUpCodes": {
    },
  • "operationType": "firstMile",
  • "carrier": "string",
  • "prePickUpActions": [
    ]
}

Response samples

Content type
application/json
{
  • "_id": "5f85c02704d61b14f47c78a0",
  • "type": "delivery",
  • "state": "reserved",
  • "states": [
    ],
  • "customer": "5f7dc9fc04d61b14f47c6f00",
  • "startDate": "2020-10-13T14:56:39.561Z",
  • "expiryDate": "2020-10-13T16:57:47.007Z",
  • "details": {
    },
  • "notificationOptions": [
    ],
  • "locker": "5d5a6e83d1682b7194fc5f9c",
  • "pricing": {
    }
}

Make Delivery (Place Delivery Item)

Launches the process to start the delivery process. Changes the delivery to the starting state and opens the locker reserved for the delivery such that the item can be placed inside it.

Authorizations:
api_key
path Parameters
rentID
required
string

Pass the ID of the Rent that you wish to start

query Parameters
lockerID
string

Pass the ID of the Locker that you wish to select (required if the Locker was not selected in the Reserve step). Note that if a lockerID is passed it replaces the Locker selected during the Reserve phase

Responses

Request samples

const request = require('request');

const options = {
  method: 'PUT',
  url: 'https://api.bloq.it/api/v1/public/deliveries/%7BrentID%7D/make',
  qs: {lockerID: 'SOME_STRING_VALUE'},
  headers: {'X-API-KEY': 'REPLACE_KEY_VALUE'}
};

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

Response samples

Content type
application/json
{
  • "_id": "5f85c02704d61b14f47c78a0",
  • "type": "delivery",
  • "state": "starting",
  • "states": [
    ],
  • "customer": "5f7dc9fc04d61b14f47c6f00",
  • "startDate": "2020-10-13T14:56:39.561Z",
  • "expiryDate": "2020-10-13T16:57:47.007Z",
  • "details": {
    },
  • "locker": "5d5a6e83d1682b7194fc5f9c",
  • "pricing": {
    }
}

Notify Client

Sends a notification to the client saying that the delivery is ready for pick-up. Can only be called when the rent is in the InProgress Rent State.

Authorizations:
api_key
path Parameters
rentID
required
string

Pass the ID of the Rent that you wish to start

Responses

Request samples

const request = require('request');

const options = {
  method: 'PUT',
  url: 'https://api.bloq.it/api/v1/public/deliveries/%7BrentID%7D/notify',
  headers: {'X-API-KEY': 'REPLACE_KEY_VALUE'}
};

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

Response samples

Content type
application/json
{
  • "_id": "5f85c02704d61b14f47c78a0",
  • "type": "delivery",
  • "state": "in_progress",
  • "states": [
    ],
  • "customer": "5f7dc9fc04d61b14f47c6f00",
  • "startDate": "2020-10-13T14:56:39.561Z",
  • "expiryDate": "2020-10-13T16:57:47.007Z",
  • "details": {
    },
  • "locker": "5d5a6e83d1682b7194fc5f9c",
  • "pricing": {
    }
}

Ready For Pickup

Signals this delivery as being ready to be pickup up. This feature is limited depending on your plan.

Authorizations:
api_key
path Parameters
rentID
required
string

Pass the ID of the Rent that you wish to signal as ready for pickup

Responses

Request samples

const request = require('request');

const options = {
  method: 'PUT',
  url: 'https://api.bloq.it/api/v1/public/deliveries/%7BrentID%7D/ready-for-pickup',
  headers: {'X-API-KEY': 'REPLACE_KEY_VALUE'}
};

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

Response samples

Content type
application/json
{
  • "_id": "5f85c02704d61b14f47c78a0",
  • "type": "delivery",
  • "state": "ready_for_pickup",
  • "states": [
    ],
  • "customer": "5f7dc9fc04d61b14f47c6f00",
  • "startDate": "2020-10-13T14:56:39.561Z",
  • "expiryDate": "2020-10-13T16:57:47.007Z",
  • "details": {
    },
  • "locker": "5d5a6e83d1682b7194fc5f9c",
  • "pricing": {
    }
}

In Transit

Signals this delivery as being in transit. This is the operation that comes after the ready for pickup action, signaling that this delivery is in transit and was picked up. This feature is limited depending on your plan.

Authorizations:
api_key
path Parameters
rentID
required
string

Pass the ID of the Rent that you wish to signal as in transit.

Responses

Request samples

const request = require('request');

const options = {
  method: 'PUT',
  url: 'https://api.bloq.it/api/v1/public/deliveries/%7BrentID%7D/in-transit',
  headers: {'X-API-KEY': 'REPLACE_KEY_VALUE'}
};

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

Response samples

Content type
application/json
{
  • "_id": "5f85c02704d61b14f47c78a0",
  • "type": "delivery",
  • "state": "in_transit",
  • "states": [
    ],
  • "customer": "5f7dc9fc04d61b14f47c6f00",
  • "startDate": "2020-10-13T14:56:39.561Z",
  • "expiryDate": "2020-10-13T16:57:47.007Z",
  • "details": {
    },
  • "locker": "5d5a6e83d1682b7194fc5f9c",
  • "pricing": {
    }
}

Select Locker

You can use this endpoint to select a locker for a delivery after is created. You can create a delivery without a locker and latter call this endpoint for that delivery and select the locker for it.

Authorizations:
api_key
path Parameters
rentID
required
string

Pass the ID of the Rent that you wish to signal as in transit.

query Parameters
bloqID
string

the ID of the Bloq being reserved (conditionally required, if the rent does not have a bloq yet then is mandatory)

lockerID
string

the ID of the Locker being reserved (conditionally required, either lockerID or lockerType must be sent). Note, if you send lockerID and lockerType only lockerID will be used

lockerType
string

The type of locker requested for this rent, based on this type we will alocate automatically a locker (conditionally required, either lockerID or lockerType must be sent)

Responses

Request samples

const request = require('request');

const options = {
  method: 'PUT',
  url: 'https://api.bloq.it/api/v1/public/deliveries/%7BrentID%7D/select-locker',
  qs: {
    bloqID: 'SOME_STRING_VALUE',
    lockerID: 'SOME_STRING_VALUE',
    lockerType: 'SOME_STRING_VALUE'
  },
  headers: {'X-API-KEY': 'REPLACE_KEY_VALUE'}
};

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

Response samples

Content type
application/json
{
  • "_id": "5f85c02704d61b14f47c78a0",
  • "type": "delivery",
  • "state": "in_transit",
  • "states": [
    ],
  • "customer": "5f7dc9fc04d61b14f47c6f00",
  • "startDate": "2020-10-13T14:56:39.561Z",
  • "expiryDate": "2020-10-13T16:57:47.007Z",
  • "details": {
    },
  • "locker": "5d5a6e83d1682b7194fc5f9c",
  • "pricing": {
    }
}

Return a delivery

Endpoint to return the delivery. Given expired rentID this endpoint will transform this delivery into a return with a given expiry date.

Authorizations:
api_key
path Parameters
rentID
required
string

Pass the rent ID to that will be updated

Request Body schema: application/json
expiryDate
string <date-time>

The new expiry date

Responses

Request samples

Content type
application/json
{
  • "expiryDate": "2019-08-24T14:15:22Z"
}

Response samples

Content type
application/json
{
  • "_id": "5f85c02704d61b14f47c78a0",
  • "type": "delivery",
  • "state": "finished",
  • "states": [
    ],
  • "customer": {
    },
  • "startDate": "2020-10-13T14:56:39.561Z",
  • "endDate": "2020-10-13T14:57:47.007Z",
  • "details": {
    },
  • "locker": {
    },
  • "pricing": {
    }
}

Return Operations

This is an object representing your Return operations. A Return is a type of rent, together with Store, Send and Delivery. You can retrieve all your Return operations or you can query one Return information by specifying its ID. Additionally, you can create a new Return by reserving a Locker to it, signal that a return was collected or finished and also cancel an existing Return.

Create a Return

When a user wants to return an item by using one of your bloqs you can create a return in four ways: 1) By specifying the bloq where the return will be and the type of the locker needed, based on this type we will alocate a locker automatically; 2) Alternatively you can create a return by specifying the bloq where the return will be and the order ID from the previous rent that the user wants to return; 3) By specifying the bloq and locker where the return will be; 4) Without specifying the bloq or the locker, creating only this return for a customer and later set the locker using the return reserve endpoint.

Authorizations:
api_key
query Parameters
lockerID
string

the ID of the Locker being reserved (If lockerID and lockerType are sent, only the lockerID will be used)

bloqID
string

the ID of the Locker being reserved.

customerID
string

Customer id of the customer starting a rent.

lockerType
string

The type of locker where the return will be.

rentID
string

The ID of the previous rent that the user want to return.

Request Body schema: application/json
expiryDate
string <date-time>

Determined date after which the rent can not be picked up.

deliveryDateLimit
string <date-time>

Date limit to place an item in the locker.

collectTimeLimit
string <date-time>

Date limit to collect the item from the locker.

notificationOptions
Array of arrays
Items Enum: "sms" "email"

List of methods used to deliver a notification to the client.

externalID
string

String used to identify the rent externally. You can save your own local identifier for the rent here.

object

Optional object that can be used instead of customerID to create a customer on the go.

pickUpCodes
object

This is a dynamic object that allows you to use multiple pick up codes for the same rent. It's a JSON object where the key is the name of the code and the value is the code, for instance { 'user' : '2121' }

Responses

Request samples

Content type
application/json
{
  • "expiryDate": "2019-08-24T14:15:22Z",
  • "deliveryDateLimit": "2019-08-24T14:15:22Z",
  • "collectTimeLimit": "2019-08-24T14:15:22Z",
  • "notificationOptions": [
    ],
  • "externalID": "string",
  • "customer": {
    },
  • "pickUpCodes": {
    }
}

Response samples

Content type
application/json
{
  • "_id": "5f85c02704d61b14f47c78a0",
  • "type": "return",
  • "state": "reserved",
  • "states": [
    ],
  • "customer": "5f7dc9fc04d61b14f47c6f00",
  • "startDate": "2020-10-13T14:56:39.561Z",
  • "expiryDate": "2020-10-13T16:57:47.007Z",
  • "details": {
    },
  • "notificationOptions": [
    ],
  • "locker": "5d5a6e83d1682b7194fc5f9c",
  • "pricing": {
    }
}

Reserve Locker

You can use this endpoint to select the locker for a return when previously used the create endpoint but without specifying the Bloq and/or the Locker. When you invoke the create return endpoint without specifying a Bloq and a Locker the return will stay on the created state and when you want to alocate a locker to it you must use this endpoint specifying the locker (all the different ways of selecting a locker explained in the create endpoint are also available on this endpoint) and the rent will move to the reserved state.

Authorizations:
api_key
path Parameters
rentID
string

the rent ID

query Parameters
bloqID
required
string

the ID of the Bloq being reserved

lockerID
string

the ID of the Locker being reserved (If lockerID and lockerType are sent, only the lockerID will be used)

lockerType
string

The type of locker where the return will be (conditionally required, need either lockerID or lockerType).

customerID
string

Customer id of the customer starting a rent.

Request Body schema: application/json
object

Optional object that can be used instead of customerID to create a customer on the go.

Responses

Request samples

Content type
application/json
{
  • "customer": {
    }
}

Response samples

Content type
application/json
{
  • "_id": "5f85c02704d61b14f47c78a0",
  • "type": "return",
  • "state": "reserved",
  • "states": [
    ],
  • "customer": "5f7dc9fc04d61b14f47c6f00",
  • "startDate": "2020-10-13T14:56:39.561Z",
  • "expiryDate": "2020-10-13T16:57:47.007Z",
  • "details": {
    },
  • "notificationOptions": [
    ],
  • "locker": "5d5a6e83d1682b7194fc5f9c",
  • "pricing": {
    }
}

Finish a Return

Ends a return. Changes the return to the finish state and frees the locker associated with the return. This feature might not be available depending on your plan.

Authorizations:
api_key
path Parameters
rentID
required
string

Pass the ID of the Return that you wish to end.

Responses

Request samples

const request = require('request');

const options = {
  method: 'PUT',
  url: 'https://api.bloq.it/api/v1/public/returns/%7BrentID%7D/finish',
  headers: {'X-API-KEY': 'REPLACE_KEY_VALUE'}
};

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

Response samples

Content type
application/json
{
  • "_id": "5f85c02704d61b14f47c78a0",
  • "type": "return",
  • "state": "reserved",
  • "states": [
    ],
  • "customer": "5f7dc9fc04d61b14f47c6f00",
  • "startDate": "2020-10-13T14:56:39.561Z",
  • "expiryDate": "2020-10-13T16:57:47.007Z",
  • "details": {
    },
  • "notificationOptions": [
    ],
  • "locker": "5d5a6e83d1682b7194fc5f9c",
  • "pricing": {
    }
}

Customers

This is an object representing your Customers. A customer is represented by an ID and optional information like contact information.

Customers are specially usefull if you want to send notifications to the customers with the pick up codes and if you want to keep track of the rents that a customer had over a period of time and in which lockers they had rents. This can also be useful in your application since allows your to show the complete history of rents for a customer. On the other hand, if you don't need this features you can always create new rents without a customer since it's always an optional argument.

Create a Customer

Endpoint to create a Customer.

Authorizations:
api_key
Request Body schema: application/json
name
string
email
string
phoneNumber
string

Responses

Request samples

Content type
application/json
{
  • "name": "John Doe",
  • "email": "happy_user9236@gmail.com",
  • "phoneNumber": "+351912345678"
}

Response samples

Content type
application/json
{
  • "_id": "23d4bcebd23c5468b647bd42",
  • "partner": "6169a0a732452574e5e247ea",
  • "name": "John Doe",
  • "email": "happy_customer325@company.com",
  • "phoneNumber": "+351912345678",
  • "externalID": "externalID",
  • "createdAt": "2022-03-30T17:08:48.812Z",
  • "updatedAt": "2022-03-30T17:08:48.812Z"
}

List all Customers

Lists the Customers associated with your account. By using this endpoint you can retrieve any number of Customers, that can be limited and paginated by using the parameters described below.

Authorizations:
api_key
query Parameters
page
integer
Default: 1

A cursor to use in pagination. Page is an integer that defines the required page from the list.

limit
integer
Default: 10

A limit in the number of objects returned.

withActiveRents
string
Default: "all"
Enum: "all" "with" "without"

Filter for customers that have active rents

Responses

Request samples

const request = require('request');

const options = {
  method: 'GET',
  url: 'https://api.bloq.it/api/v1/public/customers',
  qs: {
    page: 'SOME_INTEGER_VALUE',
    limit: 'SOME_INTEGER_VALUE',
    withActiveRents: 'SOME_STRING_VALUE'
  },
  headers: {'X-API-KEY': 'REPLACE_KEY_VALUE'}
};

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

Response samples

Content type
application/json
{
  • "totalDocs": 2,
  • "page": 1,
  • "limit": 10,
  • "docs": [
    ]
}

Retrieve a Customer

Retrieve a customer by their ID.

Authorizations:
api_key
path Parameters
customerID
required
string

Pass the ID of the customer to retrieve all the information about its status

Responses

Request samples

const request = require('request');

const options = {
  method: 'GET',
  url: 'https://api.bloq.it/api/v1/public/customers/%7BcustomerID%7D',
  headers: {'X-API-KEY': 'REPLACE_KEY_VALUE'}
};

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

Response samples

Content type
application/json
{
  • "_id": "23d4bcebd23c5468b647bd42",
  • "partner": "6169a0a732452574e5e247ea",
  • "name": "John Doe",
  • "email": "happy_customer325@company.com",
  • "phoneNumber": "+351912345678",
  • "externalID": "externalID",
  • "createdAt": "2022-03-30T17:08:48.812Z",
  • "updatedAt": "2022-03-30T17:08:48.812Z"
}

Update a Customer

Update some information about one of your Customers identified by its customerID, like their phone number or email.

Authorizations:
api_key
path Parameters
customerID
required
string

Pass the ID of the customer to retrieve all the information about its status

Request Body schema: application/json
name
string
email
string
phoneNumber
string

Responses

Request samples

Content type
application/json
{
  • "name": "John Doe",
  • "email": "happy_user9236@gmail.com",
  • "phoneNumber": "+351912345678"
}

Response samples

Content type
application/json
{
  • "_id": "23d4bcebd23c5468b647bd42",
  • "partner": "6169a0a732452574e5e247ea",
  • "name": "John Doe",
  • "email": "happy_customer325@company.com",
  • "phoneNumber": "+351912345678",
  • "externalID": "externalID",
  • "createdAt": "2022-03-30T17:08:48.812Z",
  • "updatedAt": "2022-03-30T17:08:48.812Z"
}

Delete a Customer

Delete a Customer by passing their ID as a parameter.

Authorizations:
api_key
path Parameters
customerID
required
string

Pass the ID of the customer to retrieve all the information about its status

Responses

Request samples

const request = require('request');

const options = {
  method: 'DELETE',
  url: 'https://api.bloq.it/api/v1/public/customers/%7BcustomerID%7D',
  headers: {'X-API-KEY': 'REPLACE_KEY_VALUE'}
};

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

Response samples

Content type
application/json
{
  • "_id": "23d4bcebd23c5468b647bd42",
  • "partner": "6169a0a732452574e5e247ea",
  • "name": "John Doe",
  • "email": "happy_customer325@company.com",
  • "phoneNumber": "+351912345678",
  • "externalID": "externalID",
  • "createdAt": "2022-03-30T17:08:48.812Z",
  • "updatedAt": "2022-03-30T17:08:48.812Z"
}

Couriers

Couriers represent a person from a partner or organization whose responsibility is to collect and deliver packages on the bloqs. All couriers that need to interact with the bloqs must be authenticated and there is two methods of courier authentication.

Courier Authentication Methods

  1. Internal - We, Bloq.It, provide an authentication token to the partners and their couriers must use that token to authenticate themselves in the partner bloqs. To get this token the partner must call the Get Courier Auth Token endpoint.
  2. External - The couriers enter their credentials directly in the bloq and we forward those credentials to the partner service which should in turn respond with a valid or invalid authentication.

Get Courier Auth Token

Endpoint to retrieve a JWT token that can be used by couriers to authenticate themselves in the bloqs.

Authorizations:
api_key
query Parameters
courierID
required
string

Pass the ID of the courier that will be using the courier authentication token

expirationDate
string
Default: "1day"

Token expiration date. Eg: 60, "2 days", "10h", "7d". A numeric value is interpreted as a milliseconds count. If you use a string be sure you provide the time units (days, hours, etc).

bloqIDs
Array of strings

An optional array containing the bloq IDs for which the token is valid. If none is passed the token will be valid in the entire bloqs network.

metadata
object

An optional object passed to the token payload. Can contain any information that the partner needs, it will be passed to the bloq FE and to the Bloq.It cloud for traceability.

Responses

Request samples

const request = require('request');

const options = {
  method: 'GET',
  url: 'https://api.bloq.it/api/v1/public/couriers/courier-auth/create-token',
  qs: {
    courierID: 'SOME_STRING_VALUE',
    expirationDate: 'SOME_STRING_VALUE',
    bloqIDs: 'SOME_ARRAY_VALUE',
    metadata: 'SOME_OBJECT_VALUE'
  },
  headers: {'X-API-KEY': 'REPLACE_KEY_VALUE'}
};

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

Response samples

Content type
application/json
{
  • "token": "eyJhbGciOiJFUzUxMiIsInR5cCI6IkpXVCJ9.eyJjb3VyaWVyX2lkIjoiRFJJVkVSSUQxIiwiaWF0IjoxNzAwNTg5MjI3LCJleHAiOjE3MDExOTQwMjd9.ALXBtytYWuh5KACz8IJMFTKnEhxvAhIFFQalJnfI1p7fx1fXZLmM4y4ujo9OeOI_a3hJHZCEoh_TGnhgVqzn_U4kASX8qDYnxFMpT-V0i-Y34VBVYLCbEnhP5aGkNCEsyTkz5crl6dyEEyvT6QlVNFC_3aXKX_AOkKQxuTvH1ZJtZZ5x"
}

Webhooks

This is an object representing your Webhooks. Webhooks can be used to reveived events that happened to your Bloq.It account - events related with yours lockers, rents and customers. You can create a webhook, list only one webhook or several, update a specific webhook and cancel a specific webhook. It is possible to split the events through different endpoints on your end by creating several webhooks. For example, you could have an endpoint receiving all rent related events by subscribing to all event types that start with "rent." and also have another endpoint receiving all information related to customers by subscribing to all the events that start with "customer.". Any set of events is valid in a webhook enabledEvents list. Berent.offline_dropofflow you can see a table with all the accepted Event Types.

Event Type Description
locker.locker_opened This event will be triggered when a Locker is opened.
locker.locker_closed This event will be triggered when a Locker is closed.
locker.locker_timeout This event will be triggered when a request to a locker fails due to timeout in the request.
locker.open_warning This event will be triggered when a Locker is left open for too long.
locker.locker_active This event will be triggered when a Locker is activated.
locker.locker_inactive This event will be triggered when a Locker is inactivated.
locker.created This event will be triggered when a Locker is created.
locker.open_locker_error This event will be triggered when a Locker had some problem opening or closing the door.
locker.spontaneous_locker_opening This event will be triggered when a Locker was open spontaneously, outside the scope of any request
locker.maintenance_status_update This event will be triggered when there is a change in the Locker maintenance status, having in each event the previous and the new state associated with the Locker.
rent.created This event will be triggered when a rent (store, send or delivery) is created - transits to the created state.
rent.started This event will be triggered when a rent (store, send or delivery) starts - transits to the starting state. Happens when the locker associated with the rent is opened.
rent.in_progress This event will be triggered when a rent (store, send or delivery) transits to the in_progress state. Happens when the locker is closed after the client has placed the item inside the locker.
rent.locker_opened This event will be triggered when a rent (store, send or delivery) transits to the locker_opened state. Happens when the locker associated with a rent is opened while the rent is in progress.
rent.collect_item This event will be triggered when a rent (store, send or delivery) transits to the collect_item state. Happens when the the client asked to end the store and is retrieving the item from the locker.
rent.price_calculation This event will be triggered when a rent (store, send or delivery) transits to the price_calculation state. Happens immediately after the locker closes when the rent is ending.
rent.finished This event will be triggered when a rent (store, send or delivery) transits to the finished state. Happens after the price_calculation state calculations
rent.reserved This event will be triggered when a delivery transits to the reserved state, when the reserve locker endpoint is called.
rent.cancelled This event will be triggered when a rent (store, send or delivery) transits to the cancelled state, when the cancel rent endpoint is called.
rent.expired This event will be triggered when a rent (store, send or delivery) transits to the expired state.
rent.extended This event will be triggered when a rent (store, send or delivery) has the expire date extended.
rent.in_transit This event will be triggered when a rent (store, send or delivery) transits to the in_transit state.
rent.ready_for_pickup This event will be triggered when a rent (store, send or delivery) transits to the ready_for_pickup state.
rent.automatic_notification_sent This event will be triggered when the notification is sent to the customer.
rent.drop_off_confirmation This event will be triggered when the drop off process on the Bloq finishes, i.e. when the user gets to the thank you page on the Bloq.
rent.drop_off_cancellation This event will be triggered when a client, during the drop off process on the Bloq, decides that it wants to cancel it. In the message there will be the justification message.
rent.drop_off_code_check This event will be triggered when a client starts the drop off process on the Bloq.
rent.drop_off_code_check_offline This event will be triggered when a client tries to start the drop off process on an offline Bloq.
rent.pin_attempt This event will be triggered when a client tries to open a locker using a wrong pin.
rent.offline_dropoff This event will be triggered when a user does a drop off while the locker is disconnected/offline. This event is created when the drop off information is synched with the cloud.
rent.waiting_offline_dropoff_sync This event will be triggered when a user does a drop off while the locker is disconnected/offline and the cloud receives this information but couldn't update the locker with the rent info. The rent is marked as not synced and we retry the sync later
bloq.label_printed This event will be triggered when a client asks to print a label in the Bloq. The event also has the associated rent.
bloq.print_label_error This event will be triggered when an error occured when printing a label. The error reason will be passed in the event message field.
bloq.reconnected This event will be triggered when a bloq becomes online after being offline.
bloq.created This event will be triggered when a Bloq is created
bloq.active This event will be triggered when a Bloq is enabled
bloq.inactive This event will be triggered when a Bloq is disabled
bloq.courier_authentication This event will be triggered when there is courier log in attempt in the bloq. If the login was successful the event will contain the courier data passed during the login, if the login was not successful will contain the authentication code rejected
bloq.courier_logout This event will be triggered when a couriers logs out.
customer.customer_created This event will be triggered when a customer is created.
customer.customer_updated This event will be triggered when a customer is updated.
customer.customer_deleted This event will be triggered when a customer is deleted.

Extra info

Each event can have the field actionInitiatedBy which describes who and where the event originates. This field can have up to 3 subfields:

  • role: This field contains the model who originated the event, for instance, a partner admin, a super admin, a customer or a user.
  • id: The id to the model document of whom originated the event
  • source: The place where the action started - it can have one of four values: bloq_it_admin, locker, public_api, expiration.
    • If the value is bloq_it_admin the event results from an action that started on the Bloq.It admin page.
    • If the value is locker the event results from an action that started directly on the locker.
    • If the value is public_api the event results from an action that started on a request made to the Bloq.It public API.
    • If the value is expiration the event results from the automatic process of rent expirations.

For the events with type "locker.locker_inactive" it's important to have in consideration the field metadata. In these events the metadata field might contain extra info that justifies why the locker was disabled:

  • Offline dropoff - when an offline dropoff happens there are some cases when we disable preventively the locker. In those cases the metadata object will have two field, the code field will contain the dropoff code used and a reason field with a brief explaination why the locker was disabled:
    • invalid_offline_dropoff - the dropoff code used is invalid, doesn't match a valid code in our system
    • offline_drop_off_on_inactive_bloq - an offline dropoff happened in a disabled bloq
    • offline_drop_off_on_wrong_bloq - an offline dropoff happened in a bloq different from the one reserved for the rent
      metadata: {
        code: "<dropoff_code_used>",
        reason: "offline_drop_off_on_wrong_bloq" | "offline_drop_off_on_inactive_bloq" | "invalid_offline_dropoff"
      }
      

Security

To make sure the call on the registered webhook it's made from us and the integrity of the request is maintained, we sign the request with a shared secret that can be provided to us when creating the webhook.

Note: This field isn't mandatory so if there's no secret provided we'll not sign the request

Validate the request signature

  1. Get the body of the request, the signature and timestamp from headers of the request
  2. Using the provided fields of the step 1, generate the following string <timestamp>.<body>, by concatenating the timestamp with a string containing a dot ".", and the request body.
  3. Use the jwt.verify to get the value of the signature using the signature field from the request and the shared secret associated with the endpoint
  4. Compare the result of the jwt.verify with the resulting string from step 1
  5. (Optional) Validate that the timestamp is within a time frame you were expecting receiving it

Code example in NODEJS:

const jwt = require('jsonwebtoken');

validateSignature(body, signature, timestamp, secret) {
    const result = jwt.verify(signature, secret);
    return result === `${timestamp.toString()}.${JSON.stringify(body)}`;
}

Create a Webhook

Endpoint to create a new Webhook. By passing the client url and a list containing the events you want to subscribe our application will create a Webhook that connects to your application and sends the events that correspond to the subscribed events.

Authorizations:
api_key
Request Body schema: application/json
url
required
string
enabledEvents
required
Array of strings
description
string
secret
string

Responses

Callbacks

Request samples

Content type
application/json
{
  • "url": "/ourPartner/receiveWebhook",
  • "enabledEvents": [
    ],
  • "description": "Is called when a locker is opened or closed",
  • "secret": "Y2No6tuPrX"
}

Response samples

Content type
application/json
{
  • "_id": "23d4bcebd23c54bba647df6a",
  • "description": "Is called when a locker is opened or closed",
  • "url": "/ourPartner/receiveWebhook",
  • "updatedAt": "2020-10-27T10:35:24.557+00:00",
  • "enabledEvents": [
    ]
}

Callback payload samples

Callback
POST: The structure returned when an event is triggered
Content type
application/json
{
  • "_id": "string",
  • "admin": "string",
  • "customer": "string",
  • "rent": "string",
  • "bloq": "string",
  • "locker": "string",
  • "price": "string",
  • "codeName": "string",
  • "description": "string",
  • "message": "string",
  • "title": "string",
  • "metadata": {
    },
  • "actionInitiatedBy": {
    }
}

List all Webhooks

Lists the Webhooks associated with your account.

By using this endpoint you can retrieve any number of Webhooks, that can be limited and paginated by using the parameters described below.

Authorizations:
api_key
query Parameters
page
integer
Default: 1

A cursor to use in pagination. Page is an integer that defines the required page from the list.

limit
integer
Default: 10

A limit in the number of objects returned.

eventType
string

If set, then the query will only return Webhooks that are listening to the corresponding event

startDate
string <date-time>

The starting date filter

endDate
string <date-time>

The ending date filter

Responses

Request samples

const request = require('request');

const options = {
  method: 'GET',
  url: 'https://api.bloq.it/api/v1/public/webhooks',
  qs: {
    page: 'SOME_INTEGER_VALUE',
    limit: 'SOME_INTEGER_VALUE',
    eventType: 'SOME_STRING_VALUE',
    startDate: 'SOME_STRING_VALUE',
    endDate: 'SOME_STRING_VALUE'
  },
  headers: {'X-API-KEY': 'REPLACE_KEY_VALUE'}
};

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

Response samples

Content type
application/json
{
  • "totalDocs": 2,
  • "page": 1,
  • "limit": 15,
  • "docs": [
    ]
}

Retrieve a Webhook

Endpoint to get a Webhook. By passing the webhookID our application retrieves and sends all of its information

Authorizations:
api_key
path Parameters
webhookID
required
string

Pass the ID of a webhook to retrieve all its information

Responses

Request samples

const request = require('request');

const options = {
  method: 'GET',
  url: 'https://api.bloq.it/api/v1/public/webhooks/%7BwebhookID%7D',
  headers: {'X-API-KEY': 'REPLACE_KEY_VALUE'}
};

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

Response samples

Content type
application/json
{
  • "_id": "23d4bcebd23c54bba647df6a",
  • "description": "Is called when a locker is opened or closed",
  • "url": "/ourPartner/receiveWebhook",
  • "updatedAt": "2020-10-27T10:35:24.557+00:00",
  • "enabledEvents": [
    ]
}

Update a Webhook

Endpoint to update a Webhook. By passing the webhookID and the new list of events our application updates the list subscribed events.

Authorizations:
api_key
path Parameters
webhookID
required
string

Pass the ID of webhook to retrieve all of its information

Request Body schema: application/json
url
string
enabledEvents
Array of strings
description
string
secret
string

Responses

Request samples

Content type
application/json
{
  • "url": "/ourPartner/receiveWebhook",
  • "enabledEvents": [
    ],
  • "description": "Is called when a locker is opened or closed",
  • "secret": "Y2No6tuPrX"
}

Response samples

Content type
application/json
{
  • "_id": "23d4bcebd23c54bba647df6a",
  • "description": "Is called when a locker is opened or closed",
  • "url": "/ourPartner/receiveWebhook",
  • "updatedAt": "2020-10-27T10:35:24.557+00:00",
  • "enabledEvents": [
    ]
}

Delete a Webhook

Endpoint to delete a Webhook.

Authorizations:
api_key
path Parameters
webhookID
required
string

Pass the webhook id to retrieve all its information

Responses

Request samples

const request = require('request');

const options = {
  method: 'DELETE',
  url: 'https://api.bloq.it/api/v1/public/webhooks/%7BwebhookID%7D',
  headers: {'X-API-KEY': 'REPLACE_KEY_VALUE'}
};

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

Response samples

Content type
application/json
{
  • "_id": "23d4bcebd23c54bba647df6a",
  • "description": "Is called when a locker is opened or closed",
  • "url": "/ourPartner/receiveWebhook",
  • "updatedAt": "2020-10-27T10:35:24.557+00:00",
  • "enabledEvents": [
    ]
}

Retrieve the Event History

Endpoint to get the events history.

Authorizations:
api_key
query Parameters
eventTypes
string

Pass an array of event types to be filtered for, if not defined all types will be shown

startDate
string <date-time>

The starting date filter

endDate
string <date-time>

The ending date filter

Responses

Request samples

const request = require('request');

const options = {
  method: 'GET',
  url: 'https://api.bloq.it/api/v1/public/webhooks/history',
  qs: {
    eventTypes: 'SOME_STRING_VALUE',
    startDate: 'SOME_STRING_VALUE',
    endDate: 'SOME_STRING_VALUE'
  },
  headers: {'X-API-KEY': 'REPLACE_KEY_VALUE'}
};

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

Response samples

Content type
application/json
{
  • "totalDocs": 2,
  • "page": 1,
  • "limit": 15,
  • "docs": [
    ]
}