Download OpenAPI specification:Download
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).
You can checkout the changelog of our API here
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.
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.
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.
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 |
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.
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.
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 |
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); });
{- "totalDocs": 2,
- "page": 1,
- "limit": 10,
- "docs": [
- {
- "_id": "5ff43c53400d2f31cac40a45",
- "active": true,
- "code": "bloqTest1",
- "lockers": [
- "dd3ba400291a1cac40b67",
- "1a3ba40c2e4a1caceeb4a"
], - "supports": [
- "delivery",
- "return"
], - "location": {
- "type": "Point",
- "coordinates": [
- 51.495593,
- -0.10041
]
}, - "details": {
- "title": "Main Bloq",
- "city": "London",
- "address": "Some street name and number",
- "postalCode": "1031-560"
}, - "freeLockers": 2,
- "inactiveLockers": 1,
- "lockersOfType": 3
}, - {
- "_id": "5ff43c53400d2f31cac40b47",
- "active": true,
- "code": "bigBloq",
- "lockers": [
- "dd3ba400291a1cac40b66",
- "1a3ba40c2e4a1caceeb4b",
- "dd3ba400291a1cax40b66",
- "1a3ba40c2e4a5caceeb4b",
- "dd3ba400291a1c6h40b66",
- "b43ba40c2e4a1caceeb4b"
], - "supports": [
- "delivery",
- "store"
], - "location": {
- "type": "Point",
- "coordinates": [
- 51.495593,
- -0.100413
]
}, - "details": {
- "title": "Main Bloq",
- "city": "London"
}, - "freeLockers": 6,
- "inactiveLockers": 0,
- "lockersOfType": 6
}
]
}
Retrieves a specific bloq by passing its ID as a parameter.
bloqID required | string Pass the bloq ID necessary for the lookup query |
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); });
{- "_id": "5e5fbcebd1195468b647aa02",
- "active": true,
- "details": {
- "title": "Supermarket Locker 01",
- "city": "Lisbon",
- "address": "Some street name",
- "postalCode": "1230-345"
}, - "code": "T1",
- "createdAt": "2020-03-04T14:36:27.826Z",
- "updatedAt": "2020-04-28T13:38:50.339Z",
- "maxRentTimeHour": 2,
- "supports": [
- "store"
], - "location": {
- "coordinates": [
- 16.166201,
- 46.661362
], - "type": "Point"
}, - "price": {
- "_id": "5e5fbc79d1195468b647a9f6",
- "title": "Normal",
- "prices": {
- "XS": {
- "opening": 53,
- "perMinute": 32
}, - "S": {
- "opening": 62,
- "perMinute": 44
}, - "M": {
- "opening": 22,
- "perMinute": 30
}, - "L": {
- "opening": 100,
- "perMinute": 20
}, - "XL": {
- "opening": 80,
- "perMinute": 50
}
}, - "createdAt": "2020-03-04T14:34:33.413Z",
- "updatedAt": "2020-03-04T14:34:33.413Z"
}, - "lockersMeasures": {
- "XS": {
- "length": 53,
- "width": 32,
- "height": 20
}, - "S": {
- "length": 53,
- "width": 40,
- "height": 20
}, - "M": {
- "length": 53,
- "width": 50,
- "height": 20
}, - "L": {
- "length": 53,
- "width": 60,
- "height": 20
}, - "XL": {
- "length": 53,
- "width": 70,
- "height": 20
}
}, - "status": {
- "temperatureThresholdWarning": 25,
- "temperatureThresholdCritical": 35,
- "batteryVoltageWarning": 20,
- "batteryVoltageCritical": 30,
- "lastPowerState": true
}, - "lockers": [
- {
- "_id": "5e5gfhebd1195468b647aa65",
- "rent": "72yt62a23168u2cd55ac5f3r",
- "charger": false,
- "objectDetection": false,
- "isOpen": false,
- "lastDoorOpeningTimestamp": null,
- "lockerTitle": "B1",
- "type": "S",
- "active": true,
- "createdAt": "2020-03-04T14:36:27.825Z",
- "updatedAt": "2020-03-04T14:36:27.825Z"
}, - {
- "_id": "5e5fbcebd1195468b647aa05",
- "rent": "72yt62a23168u2cd55ac5f3r",
- "charger": false,
- "objectDetection": false,
- "isOpen": false,
- "lastDoorOpeningTimestamp": null,
- "lockerTitle": "B1",
- "type": "S",
- "active": true,
- "createdAt": "2020-03-04T14:36:27.825Z",
- "updatedAt": "2020-03-04T14:36:27.825Z"
}, - {
- "_id": "5e5fbcebd1195468b647aa08",
- "rent": "72yt62a23168u2cd55aabc32",
- "charger": true,
- "objectDetection": false,
- "isOpen": false,
- "lastDoorOpeningTimestamp": null,
- "lockerTitle": "C2",
- "type": "L",
- "active": true,
- "createdAt": "2020-03-04T14:36:27.825Z",
- "updatedAt": "2020-03-04T14:36:27.825Z"
}
]
}
Lists all the lockers that are free (active and without a rent) for a given Bloq.
bloqID required | string Pass the bloq ID necessary for the lookup query |
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); });
[- {
- "_id": "string",
- "rent": "string",
- "charger": true,
- "objectDetection": true,
- "isOpen": true,
- "lastDoorOpeningTimestamp": "2019-08-24T14:15:22Z",
- "lockerTitle": "string",
- "bloq": "string",
- "type": "string",
- "active": true,
- "createAt": "2019-08-24T14:15:22Z",
- "updateAt": "2019-08-24T14:15:22Z"
}
]
Using a latitude and longitude as parameters, all the Bloqs within maxDistance of the position are listed in the response.
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 |
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); });
{- "totalDocs": 2,
- "page": 1,
- "limit": 10,
- "docs": [
- {
- "_id": "5ff43c53400d2f31cac40a45",
- "active": true,
- "code": "bloqTest1",
- "lockers": [
- "dd3ba400291a1cac40b67",
- "1a3ba40c2e4a1caceeb4a"
], - "supports": [
- "delivery",
- "return"
], - "location": {
- "type": "Point",
- "coordinates": [
- 51.495593,
- -0.10041
]
}, - "details": {
- "title": "Main Bloq",
- "city": "London",
- "address": "Some street name and number",
- "postalCode": "1031-560"
}, - "freeLockers": 2,
- "inactiveLockers": 1,
- "lockersOfType": 3
}, - {
- "_id": "5ff43c53400d2f31cac40b47",
- "active": true,
- "code": "bigBloq",
- "lockers": [
- "dd3ba400291a1cac40b66",
- "1a3ba40c2e4a1caceeb4b",
- "dd3ba400291a1cax40b66",
- "1a3ba40c2e4a5caceeb4b",
- "dd3ba400291a1c6h40b66",
- "b43ba40c2e4a1caceeb4b"
], - "supports": [
- "delivery",
- "store"
], - "location": {
- "type": "Point",
- "coordinates": [
- 51.495593,
- -0.100413
]
}, - "details": {
- "title": "Main Bloq",
- "city": "London"
}, - "freeLockers": 6,
- "inactiveLockers": 0,
- "lockersOfType": 6
}
]
}
Updates the Bloq with the id given in the parameters. Only the fields that are passed in the request body will be updated.
bloqID required | string Pass the Bloq id that you wish to update |
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 |
{- "active": true,
- "title": "Discriptive title",
- "city": "Lisbon",
- "code": "ABC123",
- "address": "string",
- "postalCode": "1234-567",
- "location": {
- "coordinates": [
- 51.495593,
- -0.10041
]
}, - "maxRentTimeHour": 2,
- "maxRentDeliveryTimeHour": 2,
- "maxRentCollectTimeHour": 2,
- "metadata": { }
}
{- "_id": "5e5fbcebd1195468b647aa02",
- "active": true,
- "details": {
- "title": "Supermarket Locker 01",
- "city": "Lisbon",
- "address": "Some street name",
- "postalCode": "1230-345"
}, - "code": "T1",
- "createdAt": "2020-03-04T14:36:27.826Z",
- "updatedAt": "2020-04-28T13:38:50.339Z",
- "maxRentTimeHour": 2,
- "supports": [
- "store"
], - "location": {
- "coordinates": [
- 16.166201,
- 46.661362
], - "type": "Point"
}, - "price": {
- "_id": "5e5fbc79d1195468b647a9f6",
- "title": "Normal",
- "prices": {
- "XS": {
- "opening": 53,
- "perMinute": 32
}, - "S": {
- "opening": 62,
- "perMinute": 44
}, - "M": {
- "opening": 22,
- "perMinute": 30
}, - "L": {
- "opening": 100,
- "perMinute": 20
}, - "XL": {
- "opening": 80,
- "perMinute": 50
}
}, - "createdAt": "2020-03-04T14:34:33.413Z",
- "updatedAt": "2020-03-04T14:34:33.413Z"
}, - "lockersMeasures": {
- "XS": {
- "length": 53,
- "width": 32,
- "height": 20
}, - "S": {
- "length": 53,
- "width": 40,
- "height": 20
}, - "M": {
- "length": 53,
- "width": 50,
- "height": 20
}, - "L": {
- "length": 53,
- "width": 60,
- "height": 20
}, - "XL": {
- "length": 53,
- "width": 70,
- "height": 20
}
}, - "status": {
- "temperatureThresholdWarning": 25,
- "temperatureThresholdCritical": 35,
- "batteryVoltageWarning": 20,
- "batteryVoltageCritical": 30,
- "lastPowerState": true
}, - "lockers": [
- {
- "_id": "5e5gfhebd1195468b647aa65",
- "rent": "72yt62a23168u2cd55ac5f3r",
- "charger": false,
- "objectDetection": false,
- "isOpen": false,
- "lastDoorOpeningTimestamp": null,
- "lockerTitle": "B1",
- "type": "S",
- "active": true,
- "createdAt": "2020-03-04T14:36:27.825Z",
- "updatedAt": "2020-03-04T14:36:27.825Z"
}, - {
- "_id": "5e5fbcebd1195468b647aa05",
- "rent": "72yt62a23168u2cd55ac5f3r",
- "charger": false,
- "objectDetection": false,
- "isOpen": false,
- "lastDoorOpeningTimestamp": null,
- "lockerTitle": "B1",
- "type": "S",
- "active": true,
- "createdAt": "2020-03-04T14:36:27.825Z",
- "updatedAt": "2020-03-04T14:36:27.825Z"
}, - {
- "_id": "5e5fbcebd1195468b647aa08",
- "rent": "72yt62a23168u2cd55aabc32",
- "charger": true,
- "objectDetection": false,
- "isOpen": false,
- "lastDoorOpeningTimestamp": null,
- "lockerTitle": "C2",
- "type": "L",
- "active": true,
- "createdAt": "2020-03-04T14:36:27.825Z",
- "updatedAt": "2020-03-04T14:36:27.825Z"
}
]
}
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).
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 |
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); });
{- "_id": "5d5a6e83d1682b7194fc5f9c",
- "rent": null,
- "charger": true,
- "objectDetection": false,
- "isOpen": true,
- "lastDoorOpeningTimestamp": "null",
- "lockerTitle": "A1",
- "bloq": "5d5a6e83d1682b7194fc5f91",
- "type": "S",
- "active": true
}
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).
bloqID required | string Pass the Bloq id where the locker you want to open is. |
lockers | Array<string> Pass the Lockers ids that you wish to open |
{- "lockers": [
- [
- "5d5a6e83d1682b7194fc5f9c",
- "5d5a6e83d1682b7194fc5f7g"
]
]
}
[- "5d5a6e83d1682b7194fc5f9c",
- "5d5a6e83d1682b7194fc5f7g"
]
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.
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 |
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); });
{- "_id": "5d5a6e83d1682b7194fc5f9c",
- "rent": null,
- "charger": true,
- "objectDetection": false,
- "isOpen": false,
- "lastDoorOpeningTimestamp": "null",
- "lockerTitle": "A1",
- "bloq": "5d5a6e83d1682b7194fc5f91",
- "type": "S",
- "active": true
}
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.
bloqID required | string Pass the Bloq id which the locker belongs to. |
lockerID required | string Pass the Locker id to which you to update. |
active required | boolean Flag with the new locker state, true -> enabled, false -> disabled |
{- "active": true
}
{- "_id": "5d5a6e83d1682b7194fc5f9c",
- "rent": null,
- "charger": true,
- "objectDetection": false,
- "isOpen": false,
- "lastDoorOpeningTimestamp": "null",
- "lockerTitle": "A1",
- "bloq": "5d5a6e83d1682b7194fc5f91",
- "type": "S",
- "active": true
}
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.
bloqID required | string Pass the Bloq id which the locker belongs to. |
lockerID required | string Pass the Locker id to which you to update. |
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); });
{- "_id": "5d5a6e83d1682b7194fc5f9c",
- "rent": null,
- "charger": true,
- "objectDetection": false,
- "isOpen": true,
- "lastDoorOpeningTimestamp": "null",
- "lockerTitle": "A1",
- "bloq": "5d5a6e83d1682b7194fc5f91",
- "type": "S",
- "active": true
}
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.
Creates a Bloq Location. A Bloq Location is a location that can be used as a reference for a future Bloq placement.
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 |
{- "address": "Street 123, 1100-123 Lisbon",
- "latitude": 38.707163,
- "longitude": -9.135517,
- "externalID": "externalID-1",
- "name": "Supermarket Locker 01",
- "metadata": {
- "key": "value"
}
}
{- "address": "Street 123, 1100-123 Lisbon",
- "externalID": "externalID-1",
- "name": "Supermarket Locker 01",
- "location": {
- "coordinates": [
- 16.166201,
- 46.661362
], - "type": "Point"
}, - "state": "created",
- "metadata": {
- "key": "value"
}
}
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.
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 |
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); });
{- "totalDocs": 2,
- "page": 1,
- "limit": 15,
- "docs": [
- {
- "address": "Street 123, 1100-123 Lisbon",
- "externalID": "externalID-1",
- "name": "Supermarket Locker 01",
- "location": {
- "coordinates": [
- 16.166201,
- 46.661362
], - "type": "Point"
}, - "state": "created",
- "metadata": {
- "key": "value"
}
}, - {
- "address": "Street 123, 1100-123 Lisbon",
- "externalID": "externalID-2",
- "name": "Supermarket Locker 02",
- "location": {
- "coordinates": [
- 16.166201,
- 46.661362
], - "type": "Point"
}, - "state": "created",
- "metadata": {
- "key": "value"
}
}
]
}
Gets the Bloq Location with the id given in the parameters.
bloqLocationID required | string Pass the Bloq Location id that you wish to retrieve |
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); });
{- "address": "Street 123, 1100-123 Lisbon",
- "externalID": "externalID-1",
- "name": "Supermarket Locker 01",
- "location": {
- "coordinates": [
- 16.166201,
- 46.661362
], - "type": "Point"
}, - "state": "created",
- "metadata": {
- "key": "value"
}
}
Updates the Bloq Location with the id given in the parameters. Only the fields that are passed in the request body will be updated.
bloqLocationID required | string Pass the Bloq Location id that you wish to update |
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") |
{- "address": "Street 123, 1100-123 Lisbon",
- "latitude": 38.707163,
- "longitude": -9.135517,
- "externalID": "externalID-1",
- "name": "Supermarket Locker 01",
- "metadata": {
- "key": "value"
}, - "state": "churned"
}
{- "address": "Street 123, 1100-123 Lisbon",
- "externalID": "externalID-1",
- "name": "Supermarket Locker 01",
- "location": {
- "coordinates": [
- 16.166201,
- 46.661362
], - "type": "Point"
}, - "state": "created",
- "metadata": {
- "key": "value"
}
}
Gets the Bloq Location with the external ID given in the parameters.
externalID required | string Pass the Bloq Location external ID that you wish to retrieve |
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); });
{- "address": "Street 123, 1100-123 Lisbon",
- "externalID": "externalID-1",
- "name": "Supermarket Locker 01",
- "location": {
- "coordinates": [
- 16.166201,
- 46.661362
], - "type": "Point"
}, - "state": "created",
- "metadata": {
- "key": "value"
}
}
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.
externalID required | string Pass the Bloq Location external ID that you wish to update |
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") |
{- "address": "Street 123, 1100-123 Lisbon",
- "latitude": 38.707163,
- "longitude": -9.135517,
- "externalID": "externalID-1",
- "name": "Supermarket Locker 01",
- "metadata": {
- "key": "value"
}, - "state": "churned"
}
{- "address": "Street 123, 1100-123 Lisbon",
- "externalID": "externalID-1",
- "name": "Supermarket Locker 01",
- "location": {
- "coordinates": [
- 16.166201,
- 46.661362
], - "type": "Point"
}, - "state": "created",
- "metadata": {
- "key": "value"
}
}
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
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. |
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); });
{- "totalDocs": 2,
- "page": 1,
- "limit": 15,
- "docs": [
- {
- "_id": "a4522ad7123c5f2a3642aa1a",
- "remainingLabels": "120"
}, - {
- "_id": "a4522ad7123c5f2a3642aa1b",
- "remainingLabels": "no data"
}
]
}
Get the amount of labels available for a given bloq.
bloqID required | string Pass the Bloq id to which to want to retrieve the amount of labels available. |
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); });
{- "remainingLabels": "120"
}
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.
bloqID required | string Pass the Bloq id where the locker you want to open is. |
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. |
content | object The content that will be used to fill the template. When the content is sent a templateID is required. |
{- "content": { }
}
{- "_id": "5d5a6e83d1682b7194fc5f9c",
- "rent": null,
- "charger": true,
- "objectDetection": false,
- "isOpen": false,
- "lastDoorOpeningTimestamp": "null",
- "lockerTitle": "A1",
- "bloq": "5d5a6e83d1682b7194fc5f91",
- "type": "S",
- "active": true
}
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.
bloqID required | string Pass the Bloq id where the locker you want to open is. |
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); });
{- "code": "bloqIDInvalid",
- "message": "Invalid bloqID. bloqID is either missing or has a wrong format."
}
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.
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.
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 |
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); });
{- "docs": [
- {
- "_id": "5f85c02704d61b14f47c78a0",
- "type": "delivery",
- "state": "finished",
- "states": [
- {
- "state": "created",
- "timestamp": "2020-10-13T14:56:39.561Z",
- "event": "62448ea072dec768a47bfd76",
- "_id": "62448ea072dec768a47bfd78"
}, - {
- "state": "reserved",
- "timestamp": "2020-10-13T14:59:39.561Z",
- "event": "62448ea072dec768a47bfd76",
- "_id": "62448ea072dec768a47bfd78"
}
], - "customer": {
- "_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"
}, - "locker": {
- "_id": "6182c7d52619d20c60405bb8",
- "rent": "625415fe8fd512ecaec2841e",
- "charger": true,
- "objectDetection": true,
- "isOpen": true,
- "lastDoorOpeningTimestamp": "2022-04-11T11:17:53.967Z",
- "active": true,
- "lockerTitle": "A1",
- "type": "XL",
- "bloq": "6182c7d52619d20c60405bb7",
- "createdAt": "2021-11-03T17:33:09.896Z",
- "updatedAt": "2022-04-11T11:50:22.539Z"
}, - "bloq": {
- "_id": "6182c7d52619d20c60405bb7",
- "activeOnMqtt": true,
- "active": true,
- "lockers": [
- "6182c7d52619d20c60405bb8",
- "6182c7d52619d20c60405bba",
- "6182c7d52619d20c60405bbc",
- "6182c7d52619d20c60405bbe"
], - "supports": [
- "delivery",
- "return"
], - "partner": "6169a0a732452574e5e247ea",
- "details": {
- "city": "Faro",
- "title": "Partner 2 Bloq 2"
}, - "price": "617920f4f5902907070e5182",
- "createdAt": "2021-11-03T17:33:09.896Z",
- "updatedAt": "2022-03-30T16:57:02.197Z"
}, - "startDate": "2020-10-13T14:56:39.561Z",
- "endDate": "2020-10-13T14:57:47.007Z",
- "details": {
- "phoneNumber": "+351967755441",
- "pickUpCode": "2124",
- "dropOffCode": "4432"
}, - "pricing": {
- "price": 400,
- "openingPrice": 100,
- "perMinutePrice": 40,
- "durationMinutes": 10,
- "amountPaid": 0,
- "debt": 0
}, - "unsuccessful": false
}
], - "totalDocs": 50,
- "limit": 10,
- "page": 1
}
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.
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 |
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); });
{- "docs": [
- {
- "_id": "5f85c02704d61b14f47c78a0",
- "type": "delivery",
- "state": "finished",
- "states": [
- {
- "state": "created",
- "timestamp": "2020-10-13T14:56:39.561Z",
- "event": "62448ea072dec768a47bfd76",
- "_id": "62448ea072dec768a47bfd78"
}, - {
- "state": "reserved",
- "timestamp": "2020-10-13T14:59:39.561Z",
- "event": "62448ea072dec768a47bfd76",
- "_id": "62448ea072dec768a47bfd78"
}
], - "customer": {
- "_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"
}, - "locker": {
- "_id": "6182c7d52619d20c60405bb8",
- "rent": "625415fe8fd512ecaec2841e",
- "charger": true,
- "objectDetection": true,
- "isOpen": true,
- "lastDoorOpeningTimestamp": "2022-04-11T11:17:53.967Z",
- "active": true,
- "lockerTitle": "A1",
- "type": "XL",
- "bloq": "6182c7d52619d20c60405bb7",
- "createdAt": "2021-11-03T17:33:09.896Z",
- "updatedAt": "2022-04-11T11:50:22.539Z"
}, - "bloq": {
- "_id": "6182c7d52619d20c60405bb7",
- "activeOnMqtt": true,
- "active": true,
- "lockers": [
- "6182c7d52619d20c60405bb8",
- "6182c7d52619d20c60405bba",
- "6182c7d52619d20c60405bbc",
- "6182c7d52619d20c60405bbe"
], - "supports": [
- "delivery",
- "return"
], - "partner": "6169a0a732452574e5e247ea",
- "details": {
- "city": "Faro",
- "title": "Partner 2 Bloq 2"
}, - "price": "617920f4f5902907070e5182",
- "createdAt": "2021-11-03T17:33:09.896Z",
- "updatedAt": "2022-03-30T16:57:02.197Z"
}, - "startDate": "2020-10-13T14:56:39.561Z",
- "endDate": "2020-10-13T14:57:47.007Z",
- "details": {
- "phoneNumber": "+351967755441",
- "pickUpCode": "2124",
- "dropOffCode": "4432"
}, - "pricing": {
- "price": 400,
- "openingPrice": 100,
- "perMinutePrice": 40,
- "durationMinutes": 10,
- "amountPaid": 0,
- "debt": 0
}, - "unsuccessful": false
}
], - "totalDocs": 50,
- "limit": 10,
- "page": 1
}
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.
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. |
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); });
{- "docs": [
- {
- "_id": "5f85c02704d61b14f47c78a0",
- "type": "delivery",
- "state": "finished",
- "states": [
- {
- "state": "created",
- "timestamp": "2020-10-13T14:56:39.561Z",
- "event": "62448ea072dec768a47bfd76",
- "_id": "62448ea072dec768a47bfd78"
}, - {
- "state": "reserved",
- "timestamp": "2020-10-13T14:59:39.561Z",
- "event": "62448ea072dec768a47bfd76",
- "_id": "62448ea072dec768a47bfd78"
}
], - "customer": {
- "_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"
}, - "locker": {
- "_id": "6182c7d52619d20c60405bb8",
- "rent": "625415fe8fd512ecaec2841e",
- "charger": true,
- "objectDetection": true,
- "isOpen": true,
- "lastDoorOpeningTimestamp": "2022-04-11T11:17:53.967Z",
- "active": true,
- "lockerTitle": "A1",
- "type": "XL",
- "bloq": "6182c7d52619d20c60405bb7",
- "createdAt": "2021-11-03T17:33:09.896Z",
- "updatedAt": "2022-04-11T11:50:22.539Z"
}, - "bloq": {
- "_id": "6182c7d52619d20c60405bb7",
- "activeOnMqtt": true,
- "active": true,
- "lockers": [
- "6182c7d52619d20c60405bb8",
- "6182c7d52619d20c60405bba",
- "6182c7d52619d20c60405bbc",
- "6182c7d52619d20c60405bbe"
], - "supports": [
- "delivery",
- "return"
], - "partner": "6169a0a732452574e5e247ea",
- "details": {
- "city": "Faro",
- "title": "Partner 2 Bloq 2"
}, - "price": "617920f4f5902907070e5182",
- "createdAt": "2021-11-03T17:33:09.896Z",
- "updatedAt": "2022-03-30T16:57:02.197Z"
}, - "startDate": "2020-10-13T14:56:39.561Z",
- "endDate": "2020-10-13T14:57:47.007Z",
- "details": {
- "phoneNumber": "+351967755441",
- "pickUpCode": "2124",
- "dropOffCode": "4432"
}, - "pricing": {
- "price": 400,
- "openingPrice": 100,
- "perMinutePrice": 40,
- "durationMinutes": 10,
- "amountPaid": 0,
- "debt": 0
}, - "unsuccessful": false
}
], - "totalDocs": 50,
- "limit": 10,
- "page": 1
}
Endpoint to retrieve information about a rent through its external ID.
externalID required | string Pass the external rent ID to retrieve all the information about its status |
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); });
{- "_id": "5f85c02704d61b14f47c78a0",
- "type": "delivery",
- "state": "finished",
- "states": [
- {
- "state": "created",
- "timestamp": "2020-10-13T14:56:39.561Z"
}, - {
- "state": "reserved",
- "timestamp": "2020-10-13T14:59:39.561Z"
}
], - "customer": {
- "_id": "5ff5de4e19a966f468221124",
- "phoneNumber": "+3519217654323",
- "email": "lseeatuc1t@gmail.com",
- "name": "John"
}, - "startDate": "2020-10-13T14:56:39.561Z",
- "endDate": "2020-10-13T14:57:47.007Z",
- "details": {
- "phoneNumber": "+351967755441",
- "pickUpCode": "4563",
- "dropOffCode": "2123"
}, - "locker": {
- "_id": "5d5a6e83d1682b7194fc5f9c",
- "type": "S",
- "active": true,
- "charger": true,
- "objectDetection": false,
- "isOpen": false,
- "lastDoorOpeningTimestamp": "exampleTimestamp",
- "lockerTitle": "A1",
- "bloq": {
- "_id": "5d5a6e83d1682b7194fc5f91",
- "active": true,
- "maxRentTimeHour": 1,
- "supports": [
- "send",
- "delivery"
], - "title": "Bloq Title",
- "location": {
- "coordinates": [
- 8.145623,
- 42.2311
], - "type": "Point"
}, - "city": "Testing City",
- "code": "test",
- "price": "5e557511f738fabc43f1e166"
}
}, - "pricing": {
- "price": 400,
- "openingPrice": 100,
- "perMinutePrice": 40,
- "durationMinutes": 10,
- "amountPaid": 0,
- "debt": 0
}
}
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).
rentID required | string The rent identifier - rentID |
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); });
[- {
- "_id": "5ff5dd37844bdcd739fcad92",
- "customer": "5fd7433ccba07c541a707567",
- "title": "Rent Created",
- "code": 6000,
- "description": "Rent has transited to CREATED state",
- "bloq": "5fb4fc6fc97fda1ab9409a20",
- "locker": "5fb4fc6fc97fda1ab9409a21",
- "rent": "5ff5dd36844bdcd739fcad90",
- "createdAt": "2020-10-13T14:56:39.561Z"
}, - {
- "_id": "5ff5dd5d844bdcd739fcad93",
- "customer": "5fd7433ccba07c541a707567",
- "title": "Rent Start",
- "code": 6011,
- "description": "Rent has transited to STARTING state",
- "bloq": "5fb4fc6fc97fda1ab9409a20",
- "locker": "5fb4fc6fc97fda1ab9409a21",
- "rent": "5ff5dd36844bdcd739fcad90",
- "createdAt": "2020-10-13T14:56:39.561Z"
}, - {
- "_id": "5ff5dd874ec285f2ed293371",
- "customer": "5fd7433ccba07c541a707567",
- "title": "In Progress",
- "code": 6012,
- "description": "Rent has transited to IN_PROGRESS state",
- "bloq": "5fb4fc6fc97fda1ab9409a20",
- "locker": "5fb4fc6fc97fda1ab9409a21",
- "rent": "5ff5dd36844bdcd739fcad90",
- "createdAt": "2020-10-13T14:56:39.561Z"
}
]
Endpoint to retrieve information about a rent through its ID.
rentID required | string Pass the rent ID to retrieve all the information about its status |
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); });
{- "_id": "5f85c02704d61b14f47c78a0",
- "type": "delivery",
- "state": "finished",
- "states": [
- {
- "state": "created",
- "timestamp": "2020-10-13T14:56:39.561Z"
}, - {
- "state": "reserved",
- "timestamp": "2020-10-13T14:59:39.561Z"
}
], - "customer": {
- "_id": "5ff5de4e19a966f468221124",
- "phoneNumber": "+3519217654323",
- "email": "lseeatuc1t@gmail.com",
- "name": "John"
}, - "startDate": "2020-10-13T14:56:39.561Z",
- "endDate": "2020-10-13T14:57:47.007Z",
- "details": {
- "phoneNumber": "+351967755441",
- "pickUpCode": "4563",
- "dropOffCode": "2123"
}, - "locker": {
- "_id": "5d5a6e83d1682b7194fc5f9c",
- "type": "S",
- "active": true,
- "charger": true,
- "objectDetection": false,
- "isOpen": false,
- "lastDoorOpeningTimestamp": "exampleTimestamp",
- "lockerTitle": "A1",
- "bloq": {
- "_id": "5d5a6e83d1682b7194fc5f91",
- "active": true,
- "maxRentTimeHour": 1,
- "supports": [
- "send",
- "delivery"
], - "title": "Bloq Title",
- "location": {
- "coordinates": [
- 8.145623,
- 42.2311
], - "type": "Point"
}, - "city": "Testing City",
- "code": "test",
- "price": "5e557511f738fabc43f1e166"
}
}, - "pricing": {
- "price": 400,
- "openingPrice": 100,
- "perMinutePrice": 40,
- "durationMinutes": 10,
- "amountPaid": 0,
- "debt": 0
}
}
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.
rentID required | string Pass the rent ID to retrieve all the information about its status |
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 |
{- "expiryDate": "2019-08-24T14:15:22Z",
- "deliveryDateLimit": "2019-08-24T14:15:22Z",
- "collectTimeLimit": 0,
- "externalID": "string",
- "dropOffCode": "string",
- "desiredLockerType": "string",
- "labelContent": { },
- "labelTemplateID": null,
- "pickUpCodes": {
- "pin1": "3451",
- "pin2": "4567",
- "pin3": "5467"
}, - "operationType": "firstMile",
- "prePickUpActions": [
- "mfa"
], - "carrier": "string"
}
{- "docs": [
- {
- "_id": "5f85c02704d61b14f47c78a0",
- "type": "delivery",
- "state": "finished",
- "states": [
- {
- "state": "created",
- "timestamp": "2020-10-13T14:56:39.561Z",
- "event": "62448ea072dec768a47bfd76",
- "_id": "62448ea072dec768a47bfd78"
}, - {
- "state": "reserved",
- "timestamp": "2020-10-13T14:59:39.561Z",
- "event": "62448ea072dec768a47bfd76",
- "_id": "62448ea072dec768a47bfd78"
}
], - "customer": {
- "_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"
}, - "locker": {
- "_id": "6182c7d52619d20c60405bb8",
- "rent": "625415fe8fd512ecaec2841e",
- "charger": true,
- "objectDetection": true,
- "isOpen": true,
- "lastDoorOpeningTimestamp": "2022-04-11T11:17:53.967Z",
- "active": true,
- "lockerTitle": "A1",
- "type": "XL",
- "bloq": "6182c7d52619d20c60405bb7",
- "createdAt": "2021-11-03T17:33:09.896Z",
- "updatedAt": "2022-04-11T11:50:22.539Z"
}, - "bloq": {
- "_id": "6182c7d52619d20c60405bb7",
- "activeOnMqtt": true,
- "active": true,
- "lockers": [
- "6182c7d52619d20c60405bb8",
- "6182c7d52619d20c60405bba",
- "6182c7d52619d20c60405bbc",
- "6182c7d52619d20c60405bbe"
], - "supports": [
- "delivery",
- "return"
], - "partner": "6169a0a732452574e5e247ea",
- "details": {
- "city": "Faro",
- "title": "Partner 2 Bloq 2"
}, - "price": "617920f4f5902907070e5182",
- "createdAt": "2021-11-03T17:33:09.896Z",
- "updatedAt": "2022-03-30T16:57:02.197Z"
}, - "startDate": "2020-10-13T14:56:39.561Z",
- "endDate": "2020-10-13T14:57:47.007Z",
- "details": {
- "phoneNumber": "+351967755441",
- "pickUpCode": "2124",
- "dropOffCode": "4432"
}, - "pricing": {
- "price": 400,
- "openingPrice": 100,
- "perMinutePrice": 40,
- "durationMinutes": 10,
- "amountPaid": 0,
- "debt": 0
}, - "unsuccessful": false
}
], - "totalDocs": 50,
- "limit": 10,
- "page": 1
}
Endpoint to extend the rent expiry date by giving the new expiry date.
rentID required | string Pass the rent ID to that will be updated |
expiryDate | string <date-time> The new expiry date |
{- "expiryDate": "2019-08-24T14:15:22Z"
}
{- "_id": "5f85c02704d61b14f47c78a0",
- "type": "delivery",
- "state": "finished",
- "states": [
- {
- "state": "created",
- "timestamp": "2020-10-13T14:56:39.561Z"
}, - {
- "state": "reserved",
- "timestamp": "2020-10-13T14:59:39.561Z"
}
], - "customer": {
- "_id": "5ff5de4e19a966f468221124",
- "phoneNumber": "+3519217654323",
- "email": "lseeatuc1t@gmail.com",
- "name": "John"
}, - "startDate": "2020-10-13T14:56:39.561Z",
- "endDate": "2020-10-13T14:57:47.007Z",
- "details": {
- "phoneNumber": "+351967755441",
- "pickUpCode": "4563",
- "dropOffCode": "2123"
}, - "locker": {
- "_id": "5d5a6e83d1682b7194fc5f9c",
- "type": "S",
- "active": true,
- "charger": true,
- "objectDetection": false,
- "isOpen": false,
- "lastDoorOpeningTimestamp": "exampleTimestamp",
- "lockerTitle": "A1",
- "bloq": {
- "_id": "5d5a6e83d1682b7194fc5f91",
- "active": true,
- "maxRentTimeHour": 1,
- "supports": [
- "send",
- "delivery"
], - "title": "Bloq Title",
- "location": {
- "coordinates": [
- 8.145623,
- 42.2311
], - "type": "Point"
}, - "city": "Testing City",
- "code": "test",
- "price": "5e557511f738fabc43f1e166"
}
}, - "pricing": {
- "price": 400,
- "openingPrice": 100,
- "perMinutePrice": 40,
- "durationMinutes": 10,
- "amountPaid": 0,
- "debt": 0
}
}
Opens the Locker associated with a Rent by its ID and changes its state to OPEN.
rentID required | string Pass the rentID to which the customer want to open the locker. |
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); });
{- "_id": "5f85c02704d61b14f47c78a0",
- "type": "store",
- "state": "locker_opened",
- "states": [
- {
- "state": "created",
- "timestamp": "2020-10-13T14:56:39.561Z"
}, - {
- "state": "reserved",
- "timestamp": "2020-10-13T14:59:39.561Z"
}
], - "customer": "5f7dc9fc04d61b14f47c6f00",
- "startDate": "2020-10-13T14:56:39.561Z",
- "expiryDate": "2020-10-13T14:57:47.007Z",
- "details": {
- "phoneNumber": "+351967755441",
- "pickUpCode": "9910"
}, - "locker": "5d5a6e83d1682b7194fc5f9c",
- "pricing": {
- "openingPrice": 100,
- "perMinutePrice": 40
}
}
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.
rentID required | string Rent ID |
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); });
{- "_id": "5f85c02704d61b14f47c78a0",
- "type": "send",
- "state": "cancelled",
- "states": [
- {
- "state": "created",
- "timestamp": "2020-10-13T14:56:39.561Z"
}, - {
- "state": "reserved",
- "timestamp": "2020-10-13T14:59:39.561Z"
}
], - "customer": "5f7dc9fc04d61b14f47c6f00",
- "startDate": "2020-10-13T14:56:39.561Z",
- "endDate": "2020-10-13T14:57:47.007Z",
- "details": {
- "phoneNumber": "+351967755441",
- "pickUpCode": "9910"
}, - "locker": "5d5a6e83d1682b7194fc5f9c",
- "pricing": {
- "price": 400,
- "openingPrice": 100,
- "perMinutePrice": 40,
- "durationMinutes": 10,
- "amountPaid": 0,
- "debt": 0
}
}
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.
rentID required | string Rent ID |
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); });
{- "_id": "5f85c02704d61b14f47c78a0",
- "type": "delivery",
- "state": "collect_item",
- "states": [
- {
- "state": "created",
- "timestamp": "2020-10-13T14:56:39.561Z"
}, - {
- "state": "reserved",
- "timestamp": "2020-10-13T14:59:39.561Z"
}
], - "customer": "5f7dc9fc04d61b14f47c6f00",
- "startDate": "2020-10-13T14:56:39.561Z",
- "endDate": "2020-10-13T14:57:47.007Z",
- "details": {
- "phoneNumber": "+351967755441",
- "pickUpCode": "9910"
}, - "locker": "5d5a6e83d1682b7194fc5f9c",
- "pricing": {
- "price": 400,
- "openingPrice": 100,
- "perMinutePrice": 40,
- "durationMinutes": 10,
- "amountPaid": 0,
- "debt": 0
}
}
Endpoint to finish the rent without collecting any item after the rent was cancelled or expired.
rentID required | string Rent ID |
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); });
{- "_id": "5f85c02704d61b14f47c78a0",
- "type": "delivery",
- "state": "finished",
- "states": [
- {
- "state": "created",
- "timestamp": "2020-10-13T14:56:39.561Z"
}, - {
- "state": "reserved",
- "timestamp": "2020-10-13T14:59:39.561Z"
}
], - "customer": "5f7dc9fc04d61b14f47c6f00",
- "startDate": "2020-10-13T14:56:39.561Z",
- "endDate": "2020-10-13T14:57:47.007Z",
- "details": {
- "phoneNumber": "+351967755441",
- "pickUpCode": "9910",
- "dropOffCode": "3421"
}, - "locker": "5d5a6e83d1682b7194fc5f9c",
- "pricing": {
- "price": 400,
- "openingPrice": 100,
- "perMinutePrice": 40,
- "durationMinutes": 10,
- "amountPaid": 0,
- "debt": 0
}
}
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.
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.
rentID required | string Pass the rentID to which the customer want to open the locker. |
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); });
{- "_id": "5f85c02704d61b14f47c78a0",
- "type": "store",
- "state": "collect_item",
- "states": [
- {
- "state": "created",
- "timestamp": "2020-10-13T14:56:39.561Z"
}, - {
- "state": "reserved",
- "timestamp": "2020-10-13T14:59:39.561Z"
}
], - "customer": "5f7dc9fc04d61b14f47c6f00",
- "startDate": "2020-10-13T14:56:39.561Z",
- "expiryDate": "2020-10-13T14:57:47.007Z",
- "details": {
- "phoneNumber": "+351967755441",
- "pickUpCode": "9910"
}, - "locker": "5d5a6e83d1682b7194fc5f9c",
- "pricing": {
- "openingPrice": 100,
- "perMinutePrice": 40
}
}
Sends a signal simulating that the locker was physically closed. Used only for testing.
rentID required | string Pass the rentID to which the customer want to open the locker. |
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); });
{- "_id": "5f85c02704d61b14f47c78a0",
- "type": "store",
- "state": "in_progress",
- "states": [
- {
- "state": "created",
- "timestamp": "2020-10-13T14:56:39.561Z"
}, - {
- "state": "reserved",
- "timestamp": "2020-10-13T14:59:39.561Z"
}
], - "customer": "5f7dc9fc04d61b14f47c6f00",
- "startDate": "2020-10-13T14:56:39.561Z",
- "expiryDate": "2020-10-13T14:57:47.007Z",
- "details": {
- "phoneNumber": "+351967755441",
- "pickUpCode": "9910"
}, - "locker": "5d5a6e83d1682b7194fc5f9c",
- "pricing": {
- "openingPrice": 100,
- "perMinutePrice": 40
}
}
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.
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.
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. |
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' } |
{- "pickUpCodes": {
- "pin1": "3451",
- "pin2": "5467"
}
}
{- "_id": "5f85c02704d61b14f47c78a0",
- "type": "store",
- "state": "starting",
- "states": [
- {
- "state": "created",
- "timestamp": "2020-10-13T14:56:39.561Z"
}, - {
- "state": "reserved",
- "timestamp": "2020-10-13T14:59:39.561Z"
}
], - "customer": "5f7dc9fc04d61b14f47c6f00",
- "locker": "5d5a6e83d1682b7194fc5f9c",
- "startDate": "2019-08-19T09:40:19.343+00:00",
- "expiryDate": "2019-08-19T11:40:19.343+00:00",
- "details": {
- "pickUpCode": "7856"
}, - "pricing": {
- "openingPrice": 100,
- "perMinutePrice": 40
}
}
Ends the Store operation identified by the ID passed in the parameters.
rentID required | string Pass the ID of the Store operation being finished. |
openLocker | boolean Default: false Flag to use in the case that is necessary to open the locker when the store ends |
{- "openLocker": false
}
{- "_id": "5f85c02704d61b14f47c78a0",
- "type": "store",
- "state": "finished",
- "states": [
- {
- "state": "created",
- "timestamp": "2020-10-13T14:56:39.561Z"
}, - {
- "state": "reserved",
- "timestamp": "2020-10-13T14:59:39.561Z"
}
], - "customer": "5f7dc9fc04d61b14f47c6f00",
- "locker": "5d5a6e83d1682b7194fc5f9c",
- "startDate": "2019-08-19T09:40:19.343+00:00",
- "endDate": "2019-08-19T10:40:19.343+00:00",
- "details": {
- "pickUpCode": "7856"
}, - "pricing": {
- "price": 400,
- "openingPrice": 100,
- "perMinutePrice": 40,
- "durationMinutes": 10,
- "amountPaid": 0,
- "debt": 0
}
}
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.
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.
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. |
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' } |
{- "phoneNumber": "+351919090909",
- "pickUpCodes": { }
}
{- "_id": "5f85c02704d61b14f47c78a0",
- "type": "send",
- "state": "starting",
- "states": [
- {
- "state": "created",
- "timestamp": "2020-10-13T14:56:39.561Z"
}, - {
- "state": "reserved",
- "timestamp": "2020-10-13T14:59:39.561Z"
}
], - "startDate": "2019-08-19T09:40:19.343+00:00",
- "expiryDate": "2019-08-19T11:40:19.343+00:00",
- "customer": "5f7dc9fc04d61b14f47c6f00",
- "locker": "5d5a6e83d1682b7194fc5f9c",
- "details": {
- "pickUpCodes": {
- "pin1": "7856",
- "pin2": "7851"
}, - "dropOffCode": "4109"
}, - "pricing": {
- "openingPrice": 100,
- "perMinutePrice": 40
}
}
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. 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.
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.
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.
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. |
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 |
{- "expiryDate": "2019-08-24T14:15:22Z",
- "deliveryDateLimit": "2019-08-24T14:15:22Z",
- "collectTimeLimit": 0,
- "notificationOptions": [
- "sms",
- "email"
], - "externalID": "string",
- "customer": {
- "name": "string",
- "email": "string",
- "phoneNumber": "string"
}, - "pickUpCode": "string",
- "dropOffCode": "string",
- "desiredLockerType": "string",
- "labelContent": { },
- "labelTemplateID": null,
- "pickUpCodes": {
- "pin1": "3451",
- "pin2": "4567",
- "pin3": "54678"
}, - "operationType": "firstMile",
- "carrier": "string",
- "prePickUpActions": [
- "mfa"
]
}
{- "_id": "5f85c02704d61b14f47c78a0",
- "type": "delivery",
- "state": "reserved",
- "states": [
- {
- "state": "created",
- "timestamp": "2020-10-13T14:56:39.561Z"
}, - {
- "state": "reserved",
- "timestamp": "2020-10-13T14:59:39.561Z"
}
], - "customer": "5f7dc9fc04d61b14f47c6f00",
- "startDate": "2020-10-13T14:56:39.561Z",
- "expiryDate": "2020-10-13T16:57:47.007Z",
- "details": {
- "pickUpCodes": {
- "pin1": "3231",
- "pin2": "2211"
}, - "dropOffCode": "5431"
}, - "notificationOptions": [
- "sms",
- "email"
], - "locker": "5d5a6e83d1682b7194fc5f9c",
- "pricing": {
- "openingPrice": 100,
- "perMinutePrice": 40
}
}
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.
rentID required | string Pass the ID of the Rent that you wish to start |
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 |
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); });
{- "_id": "5f85c02704d61b14f47c78a0",
- "type": "delivery",
- "state": "starting",
- "states": [
- {
- "state": "created",
- "timestamp": "2020-10-13T14:56:39.561Z"
}, - {
- "state": "reserved",
- "timestamp": "2020-10-13T14:59:39.561Z"
}
], - "customer": "5f7dc9fc04d61b14f47c6f00",
- "startDate": "2020-10-13T14:56:39.561Z",
- "expiryDate": "2020-10-13T16:57:47.007Z",
- "details": {
- "pickUpCode": "7856",
- "dropOffCode": "2139"
}, - "locker": "5d5a6e83d1682b7194fc5f9c",
- "pricing": {
- "openingPrice": 100,
- "perMinutePrice": 40
}
}
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.
rentID required | string Pass the ID of the Rent that you wish to start |
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); });
{- "_id": "5f85c02704d61b14f47c78a0",
- "type": "delivery",
- "state": "in_progress",
- "states": [
- {
- "state": "created",
- "timestamp": "2020-10-13T14:56:39.561Z"
}, - {
- "state": "reserved",
- "timestamp": "2020-10-13T14:59:39.561Z"
}
], - "customer": "5f7dc9fc04d61b14f47c6f00",
- "startDate": "2020-10-13T14:56:39.561Z",
- "expiryDate": "2020-10-13T16:57:47.007Z",
- "details": {
- "pickUpCode": "7856",
- "dropOffCode": "9090"
}, - "locker": "5d5a6e83d1682b7194fc5f9c",
- "pricing": {
- "openingPrice": 100,
- "perMinutePrice": 40
}
}
Signals this delivery as being ready to be pickup up. This feature is limited depending on your plan.
rentID required | string Pass the ID of the Rent that you wish to signal as ready for pickup |
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); });
{- "_id": "5f85c02704d61b14f47c78a0",
- "type": "delivery",
- "state": "ready_for_pickup",
- "states": [
- {
- "state": "created",
- "timestamp": "2020-10-13T14:56:39.561Z"
}, - {
- "state": "reserved",
- "timestamp": "2020-10-13T14:59:39.561Z"
}, - {
- "state": "ready_for_pickup",
- "timestamp": "2020-10-13T15:59:39.561Z"
}
], - "customer": "5f7dc9fc04d61b14f47c6f00",
- "startDate": "2020-10-13T14:56:39.561Z",
- "expiryDate": "2020-10-13T16:57:47.007Z",
- "details": {
- "pickUpCode": "7856",
- "dropOffCode": "5421"
}, - "locker": "5d5a6e83d1682b7194fc5f9c",
- "pricing": {
- "openingPrice": 100,
- "perMinutePrice": 40
}
}
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.
rentID required | string Pass the ID of the Rent that you wish to signal as in transit. |
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); });
{- "_id": "5f85c02704d61b14f47c78a0",
- "type": "delivery",
- "state": "in_transit",
- "states": [
- {
- "state": "created",
- "timestamp": "2020-10-13T14:56:39.561Z"
}, - {
- "state": "reserved",
- "timestamp": "2020-10-13T14:59:39.561Z"
}, - {
- "state": "ready_for_pickup",
- "timestamp": "2020-10-13T15:59:39.561Z"
}, - {
- "state": "in_transit",
- "timestamp": "2020-10-14T18:59:39.561Z"
}
], - "customer": "5f7dc9fc04d61b14f47c6f00",
- "startDate": "2020-10-13T14:56:39.561Z",
- "expiryDate": "2020-10-13T16:57:47.007Z",
- "details": {
- "pickUpCode": "7856",
- "dropOffCode": "7764"
}, - "locker": "5d5a6e83d1682b7194fc5f9c",
- "pricing": {
- "openingPrice": 100,
- "perMinutePrice": 40
}
}
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.
rentID required | string Pass the ID of the Rent that you wish to signal as in transit. |
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) |
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); });
{- "_id": "5f85c02704d61b14f47c78a0",
- "type": "delivery",
- "state": "in_transit",
- "states": [
- {
- "state": "created",
- "timestamp": "2020-10-13T14:56:39.561Z"
}, - {
- "state": "reserved",
- "timestamp": "2020-10-13T14:59:39.561Z"
}, - {
- "state": "ready_for_pickup",
- "timestamp": "2020-10-13T15:59:39.561Z"
}, - {
- "state": "in_transit",
- "timestamp": "2020-10-14T18:59:39.561Z"
}
], - "customer": "5f7dc9fc04d61b14f47c6f00",
- "startDate": "2020-10-13T14:56:39.561Z",
- "expiryDate": "2020-10-13T16:57:47.007Z",
- "details": {
- "pickUpCode": "7856",
- "dropOffCode": "7764"
}, - "locker": "5d5a6e83d1682b7194fc5f9c",
- "pricing": {
- "openingPrice": 100,
- "perMinutePrice": 40
}
}
Endpoint to return the delivery. Given expired rentID this endpoint will transform this delivery into a return with a given expiry date.
rentID required | string Pass the rent ID to that will be updated |
expiryDate | string <date-time> The new expiry date |
{- "expiryDate": "2019-08-24T14:15:22Z"
}
{- "_id": "5f85c02704d61b14f47c78a0",
- "type": "delivery",
- "state": "finished",
- "states": [
- {
- "state": "created",
- "timestamp": "2020-10-13T14:56:39.561Z"
}, - {
- "state": "reserved",
- "timestamp": "2020-10-13T14:59:39.561Z"
}
], - "customer": {
- "_id": "5ff5de4e19a966f468221124",
- "phoneNumber": "+3519217654323",
- "email": "lseeatuc1t@gmail.com",
- "name": "John"
}, - "startDate": "2020-10-13T14:56:39.561Z",
- "endDate": "2020-10-13T14:57:47.007Z",
- "details": {
- "phoneNumber": "+351967755441",
- "pickUpCode": "4563",
- "dropOffCode": "2123"
}, - "locker": {
- "_id": "5d5a6e83d1682b7194fc5f9c",
- "type": "S",
- "active": true,
- "charger": true,
- "objectDetection": false,
- "isOpen": false,
- "lastDoorOpeningTimestamp": "exampleTimestamp",
- "lockerTitle": "A1",
- "bloq": {
- "_id": "5d5a6e83d1682b7194fc5f91",
- "active": true,
- "maxRentTimeHour": 1,
- "supports": [
- "send",
- "delivery"
], - "title": "Bloq Title",
- "location": {
- "coordinates": [
- 8.145623,
- 42.2311
], - "type": "Point"
}, - "city": "Testing City",
- "code": "test",
- "price": "5e557511f738fabc43f1e166"
}
}, - "pricing": {
- "price": 400,
- "openingPrice": 100,
- "perMinutePrice": 40,
- "durationMinutes": 10,
- "amountPaid": 0,
- "debt": 0
}
}
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.
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.
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. |
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' } |
{- "expiryDate": "2019-08-24T14:15:22Z",
- "deliveryDateLimit": "2019-08-24T14:15:22Z",
- "collectTimeLimit": "2019-08-24T14:15:22Z",
- "notificationOptions": [
- "sms",
- "email"
], - "externalID": "string",
- "customer": {
- "name": "string",
- "email": "string",
- "phoneNumber": "string"
}, - "pickUpCodes": {
- "pin1": "2211",
- "pin2": "1235"
}
}
{- "_id": "5f85c02704d61b14f47c78a0",
- "type": "return",
- "state": "reserved",
- "states": [
- {
- "state": "created",
- "timestamp": "2020-10-13T14:56:39.561Z"
}, - {
- "state": "reserved",
- "timestamp": "2020-10-13T14:59:39.561Z"
}
], - "customer": "5f7dc9fc04d61b14f47c6f00",
- "startDate": "2020-10-13T14:56:39.561Z",
- "expiryDate": "2020-10-13T16:57:47.007Z",
- "details": {
- "pickUpCodes": {
- "pin1": "2121",
- "pin2": "3444"
}
}, - "notificationOptions": [
- "sms",
- "email"
], - "locker": "5d5a6e83d1682b7194fc5f9c",
- "pricing": {
- "openingPrice": 100,
- "perMinutePrice": 40
}
}
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.
rentID | string the rent ID |
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. |
object Optional object that can be used instead of customerID to create a customer on the go. |
{- "customer": {
- "name": "string",
- "email": "string",
- "phoneNumber": "string"
}
}
{- "_id": "5f85c02704d61b14f47c78a0",
- "type": "return",
- "state": "reserved",
- "states": [
- {
- "state": "created",
- "timestamp": "2020-10-13T14:56:39.561Z"
}, - {
- "state": "reserved",
- "timestamp": "2020-10-13T14:59:39.561Z"
}
], - "customer": "5f7dc9fc04d61b14f47c6f00",
- "startDate": "2020-10-13T14:56:39.561Z",
- "expiryDate": "2020-10-13T16:57:47.007Z",
- "details": {
- "pickUpCodes": {
- "pin1": "2121",
- "pin2": "3444"
}
}, - "notificationOptions": [
- "sms",
- "email"
], - "locker": "5d5a6e83d1682b7194fc5f9c",
- "pricing": {
- "openingPrice": 100,
- "perMinutePrice": 40
}
}
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.
rentID required | string Pass the ID of the Return that you wish to end. |
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); });
{- "_id": "5f85c02704d61b14f47c78a0",
- "type": "return",
- "state": "reserved",
- "states": [
- {
- "state": "created",
- "timestamp": "2020-10-13T14:56:39.561Z"
}, - {
- "state": "reserved",
- "timestamp": "2020-10-13T14:59:39.561Z"
}
], - "customer": "5f7dc9fc04d61b14f47c6f00",
- "startDate": "2020-10-13T14:56:39.561Z",
- "expiryDate": "2020-10-13T16:57:47.007Z",
- "details": {
- "pickUpCodes": {
- "pin1": "2121",
- "pin2": "3444"
}
}, - "notificationOptions": [
- "sms",
- "email"
], - "locker": "5d5a6e83d1682b7194fc5f9c",
- "pricing": {
- "openingPrice": 100,
- "perMinutePrice": 40
}
}
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.
Endpoint to create a Customer.
name | string |
string | |
phoneNumber | string |
{- "name": "John Doe",
- "email": "happy_user9236@gmail.com",
- "phoneNumber": "+351912345678"
}
{- "_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"
}
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.
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 |
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); });
{- "totalDocs": 2,
- "page": 1,
- "limit": 10,
- "docs": [
- {
- "_id": "23d4bcebd23c5468b647bd42",
- "email": "happy_customer325@company.com",
- "phoneNumber": "+351912345678",
- "name": "John Doe"
}, - {
- "_id": "23d4bcebd23c5468b647baaa",
- "email": "mary_smith@company.com",
- "phoneNumber": "+351912345221",
- "name": "Mary Smith"
}
]
}
Retrieve a customer by their ID.
customerID required | string Pass the ID of the customer to retrieve all the information about its status |
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); });
{- "_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 some information about one of your Customers identified by its customerID, like their phone number or email.
customerID required | string Pass the ID of the customer to retrieve all the information about its status |
name | string |
string | |
phoneNumber | string |
{- "name": "John Doe",
- "email": "happy_user9236@gmail.com",
- "phoneNumber": "+351912345678"
}
{- "_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 by passing their ID as a parameter.
customerID required | string Pass the ID of the customer to retrieve all the information about its status |
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); });
{- "_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 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.
Endpoint to retrieve a JWT token that can be used by couriers to authenticate themselves in the bloqs.
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. |
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); });
{- "token": "eyJhbGciOiJFUzUxMiIsInR5cCI6IkpXVCJ9.eyJjb3VyaWVyX2lkIjoiRFJJVkVSSUQxIiwiaWF0IjoxNzAwNTg5MjI3LCJleHAiOjE3MDExOTQwMjd9.ALXBtytYWuh5KACz8IJMFTKnEhxvAhIFFQalJnfI1p7fx1fXZLmM4y4ujo9OeOI_a3hJHZCEoh_TGnhgVqzn_U4kASX8qDYnxFMpT-V0i-Y34VBVYLCbEnhP5aGkNCEsyTkz5crl6dyEEyvT6QlVNFC_3aXKX_AOkKQxuTvH1ZJtZZ5x"
}
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. |
Each event can have the field actionInitiatedBy which describes who and where the event originates. This field can have up to 3 subfields:
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:
metadata: {
code: "<dropoff_code_used>",
reason: "offline_drop_off_on_wrong_bloq" | "offline_drop_off_on_inactive_bloq" | "invalid_offline_dropoff"
}
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
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)}`;
}
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.
url required | string |
enabledEvents required | Array of strings |
description | string |
secret | string |
{- "url": "/ourPartner/receiveWebhook",
- "enabledEvents": [
- "locker.locker_opened",
- "locker.locker_closed"
], - "description": "Is called when a locker is opened or closed",
- "secret": "Y2No6tuPrX"
}
{- "_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": [
- "locker.locker_closed",
- "locker.locker_opened"
]
}
{- "_id": "string",
- "admin": "string",
- "customer": "string",
- "rent": "string",
- "bloq": "string",
- "locker": "string",
- "price": "string",
- "codeName": "string",
- "description": "string",
- "message": "string",
- "title": "string",
- "metadata": {
- "pricing": {
- "perMinutePrice": 0,
- "openingPrice": 0,
- "durationMinutes": 0,
- "totalPrice": 0,
- "discount": 0
}, - "externalID": "string"
}, - "actionInitiatedBy": {
- "source": "bloq_it_admin",
- "role": "string",
- "id": "string"
}
}
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.
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 |
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); });
{- "totalDocs": 2,
- "page": 1,
- "limit": 15,
- "docs": [
- {
- "_id": "a4522ad7123c5f2a3642aa1a",
- "description": "Is called when a locker is opened or closed",
- "url": "/yourCompany/receiveLockerWebhook",
- "updatedAt": "2020-10-27T10:35:24.557+00:00",
- "enabledEvents": [
- "locker.locker_closed",
- "locker.locker_opened"
]
}, - {
- "_id": "23d4bcebd23c54bba647df6a",
- "description": "Rent hooks",
- "url": "/yourCompany/receiveRentWebhook",
- "updatedAt": "2020-10-27T10:35:24.557+00:00",
- "enabledEvents": [
- "rent.created",
- "rent.in_progess",
- "rent.collect_item",
- "rent.finished"
]
}
]
}
Endpoint to get a Webhook. By passing the webhookID our application retrieves and sends all of its information
webhookID required | string Pass the ID of a webhook to retrieve all its information |
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); });
{- "_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": [
- "locker.locker_closed",
- "locker.locker_opened"
]
}
Endpoint to update a Webhook. By passing the webhookID and the new list of events our application updates the list subscribed events.
webhookID required | string Pass the ID of webhook to retrieve all of its information |
url | string |
enabledEvents | Array of strings |
description | string |
secret | string |
{- "url": "/ourPartner/receiveWebhook",
- "enabledEvents": [
- "locker.locker_opened",
- "locker.locker_closed"
], - "description": "Is called when a locker is opened or closed",
- "secret": "Y2No6tuPrX"
}
{- "_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": [
- "locker.locker_closed",
- "locker.locker_opened"
]
}
Endpoint to delete a Webhook.
webhookID required | string Pass the webhook id to retrieve all its information |
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); });
{- "_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": [
- "locker.locker_closed",
- "locker.locker_opened"
]
}
Endpoint to get the events history.
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 |
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); });
{- "totalDocs": 2,
- "page": 1,
- "limit": 15,
- "docs": [
- {
- "_id": "a4522ad7123c5f2a3642aa1a",
- "customer": "d21d213e21e2112e12dd21dq,",
- "bloq": "bb922ad7123c5f2a3642aa1a",
- "rent": "cd218ad71922ad7a3642ff2d",
- "codeName": "rent.created",
- "description": "Rent has transited to CREATED state",
- "createdAt": "2020-10-27T10:35:24.557+00:00"
}, - {
- "_id": "adgeeq33rf8233fa3642aa1a",
- "customer": "d21d213e21e211ffdadd21d8",
- "bloq": "af298a887f62d1cb199a82da",
- "rent": "dad6654a2d2b271f1a5c3ee3",
- "codeName": "rent.reserved",
- "description": "Rent has transited to the RESERVED state"
}
]
}