Learn the platform integration in details. We have described all the integration steps in details here.
First of all platform needs to register into the Doorhub system. Register me.
Once a platform is registered, it may take 08-48 hours to activate the account. Please contact us to activate it immediately.
Once your account is activated, you can login to the dashboard of our test environment (https://test.doorhub.io/dashboard). Test environment is used only for testing and integration purposes.
The dashboard is useful for the integration as here you can see the placed orders, order current statuses etc.
Dashboard of the test environment provides helpful features targets for the testing of the system and integration. When you use the TEST api key the response of the API might be a mock of the same format as it is on the live server.
Once you are into the dashboard, you can see the TEST api key. while doing the integration you should send this API key for all the requests.
Key format: Test api key starts with pt_test_*
You LIVE api key will be activated once the integration is complete and agreed by both parties (Doorhub and Platform). Live api key should be used for the production environment for placing the real orders.
Key format: Live api key starts with pt_live_*
{info} Even thought you are using TEST key or LIVE key, you should always send the api request to our LIVE environment (https://doorhub.io).
Doorhub provide deliveries in different regions. When platform is registered platform already selected which regions platform wants to deliver the orders.
Doorhub only deliver's orders that are supported by Doorhub delivery zones and Platform has to be registered on that region. For an example, if platform didn't registered
for Roskilde region, platform can't place an order to that region.
Using this api service platform can get all the delivery regions that Doorhub supports for them (the platform).
{primary} Example of a request
curl -X GET -G "https://doorhub.io/api/platform/v1/zones/area"
-H "Authorization: Bearer {api-key}"
-H "Api-Version: v1"{success} Example of response [200]
{
"success": true,
"message": "",
"data": [
{
"zone_city": "Copenhagen",
"delivery_zone": "55.723304,12.329385,55.748819,12.421395,55.755002,12.452981,55.773544,12.466714,55.771999,12.525765,55.75191,12.540871,55.743408,12.547738,55.744181,12.58207,55.731811,12.599923,55.72021,12.654855,55.600912,12.672707,55.589272,12.649361,55.598584,12.56971,55.633484,12.550484,55.623405,12.506539,55.607894,12.428262,55.611772,12.393929"
},
{
"zone_city": "Roskilde",
"delivery_zone": "55.657214,12.028107,55.652178,12.020897,55.62408,12.052483,55.617295,12.089218,55.625825,12.115654,55.640941,12.1287,55.660894,12.153763,55.679481,12.12664,55.68103,12.068619,55.674448,12.064842,55.662249,12.083038"
}
]
}Explanation: From the response you can see two regions Doorhub supports for your platform.
For each region, Doorhub will also provide the supported delivery area zone. This zone_city name you need to provide into the order checkout api as regionName.
{danger} Example of response [400]
{
"success": false,
"message": "No region is supported or activated to your platform, Please contact Doorhub to activate",
"error": []
}This service returns the specific regions area that Doorhub supports.
{primary} Example of a request
curl -X GET -G "https://doorhub.io/api/platform/v1/zones/area/{city}"
-H "Authorization: Bearer {api-key}"
-H "Api-Version: v1"| Parameters | Type | Status | Description |
|---|---|---|---|
| city | required | zone_city name which was the response from the zone api (Get doorhub delivery zones). Example: "copenhagen" |
{success} Example of response [200]
{
"success": true,
"message": "",
"data": {
"zone_city": "copenhagen",
"delivery_zone": "55.723304,12.329385,55.748819,12.421395,55.755002,12.452981,55.773544,12.466714,55.771999,12.525765,55.75191,12.540871,55.743408,12.547738,55.744181,12.58207,55.731811,12.599923,55.72021,12.654855,55.600912,12.672707,55.589272,12.649361,55.598584,12.56971,55.633484,12.550484,55.623405,12.506539,55.607894,12.428262,55.611772,12.393929"
}
}{danger} Example of response [400]
{
"success": false,
"message": "Provided city is not supported for your platform",
"error": {
"city": [
"Provided city is not supported for your platform by Doorhub"
],
"suggestions": [
{
"message": "Please make sure the provided city/region name is correct"
}
]
}
}{primary} Example of a request
curl -X POST "https://doorhub.io/api/platform/v1/zones/support"
-H "Authorization: Bearer {api-key}"
-H "Api-Version: v1"
-d "pickupAddress"="Toftegårds Allé 49, 2500 København"
-d "dropOffAddress"="Heimdalsgade 44, 2200 København"
-d "regionName"="copenhagen"| Parameters | Type | Status | Description |
|---|---|---|---|
| pickupAddress | string | required | The pickup address. Example: Toftegårds Allé 49, 2500 København |
| dropOffAddress | string | required | The dropoff address. Example: Heimdalsgade 44, 2200 København |
| regionName | string | required | zone_city name which was the response from the zone api (Get doorhub delivery zones). Example: "copenhagen". |
{success} Example of response [200]
{
"success": true,
"message": "Addresses are supported by Doorhub",
"data": []
}{danger} Example of response [400]
{
"success": false,
"message": "Pickup Address is not supported by Doorhub delivery zone",
"error": {
"suggestions": [
{
"message": "Please check if the pickupAddress is right and inside the Doorhub delivery zone"
}
],
"pickupAddress": [
"Pickup Address is not supported by Doorhub delivery zone"
]
}
}Before placing an order platform may need to check the estimated pickup and delivery time.
Currently these service is only available for asap delivery estimation
{primary} Example of a request
curl -X POST "https://doorhub.io/api/platform/v1/orders/precheck"
-H "Authorization: Bearer {api-key}"
-H "Api-Version: v1"
-H "Content-Type: application/json"
-d '{
"regionName":"copenhagen",
"pickupAddress":"Toftegårds Allé 49, 2500 København",
"dropOffAddress":"Heimdalsgade 44, 2200 K\u00f8benhavn",
"productSize":"small",
}'| Parameters | Type | Status | Description |
|---|---|---|---|
| regionName | string | required | zone_city name which was the response from the zone api (Get doorhub delivery zones). Example: "copenhagen". |
| pickupAddress | string | required | The google like address of the order pickup location, Example: Toftegårds Allé 49, 2500 København |
| dropOffAddress | string | required | The google like address of the order where it should be delivered. Example: Heimdalsgade 42, 2200 København N |
| productSize | string | required | The size of the products, it can be [small ,medium, big]. Our Bag size is W: 16 x L: 16 x H: 18 "Inch". For Food category: 0-6 items AND price <> 0 - 550 dkk: small,0-9 items AND price <> 551 - 999 dkk: medium,10 > items AND price > 1000 dkk: big |
{success} Example of a response [200]
{
"success": true,
"message": "success",
"data": {
"serviceName": "Doorhub delivery",
"timeUnit": "minute",
"priceUnit": "DKK",
"estimatedPickupTime": 24,
"estimatedTimeForPickup": "2019-05-02 14:56",
"estimatedDeliveryTime": 48,
"estimatedTimeForDelivery": "2019-05-02 15:20",
"estimatedDeliveryCharge": 55
}
}To place an order to Doorhub as platform, you will use this checkout service. Depending on the type of platform (p2c / p2p) the required fields of the request may be required or optional. p2c = Business to Consumer model type, Example: JustEat, Hungry, OrderYoyo etc. p2p = Consumer to Consumer model type, Example: Facebook Market Place, Tradono, Etc.
There are two types of orders
ASAP order: asap orders are considered when there is none timeForDropOff and timeForPickup is provided. Doorhub will consider it as ASAP order and response with timeForPickup and timeForDropOff.
Schedule order: platform has to send the timeForDropOff time which is the delivered time to the customer, if the delivery is possible for Doorhub, Doorhub will response with timeForPickup time (when driver will collect the order), and place the order. Otherwise Doorhub will suggest the best possible timeForPickup and timeForDropOff, but the order is not actually placed yet. In this situation Platform needs to confirm the order (using the confirm api endpoint), means approval of the new timeForPickup and timeForDropOff time. In case of suggestion time table Doorhub also provides a validation time, that is, how long this pickup and drop-off time will be valid to accept the confirmation.
{primary} Example of a request
curl -X POST "https://doorhub.io/api/platform/v1/orders/checkout"
-H "Authorization: Bearer {api-key}"
-H "Api-Version: v1"
-H "Content-Type: application/json"
-d '{
"regionName":"copenhagen",
"deliveryId":"/docs/1.0/platforms/integration-details#ORD345987",
"pickupAddress":"Toftegårds Allé 49, 2500 København",
"dropOffAddress":"Heimdalsgade 44, 2200 K\u00f8benhavn",
"sellerName":"John Mayer \/ Barakat grill & pizza restaurant",
"sellerPhone":98547631,
"customerName":"Emma Watson",
"customerPhone":68547631,
"customerFloor":"1st Floor \/ 2nd",
"productSize":"small",
"timeForDropOff":"2019-01-01 17:25",
"timeForPickup":"2019-01-01 17:25",
"description":"Please call on my mobile when you are here, the outside building calling button does not works!"
}'| Parameters | Type | Status | Description |
|---|---|---|---|
| regionName | string | required | zone_city name which was the response from the zone api (Get doorhub delivery zones). Example: "copenhagen". |
| deliveryId | string | required | Delivery order Id in the platform system, this is for the reference of the order. |
| pickupAddress | string | required | The google like address of the order pickup location, Example: Toftegårds Allé 49, 2500 København |
| dropOffAddress | string | required | The google like address of the order where it should be delivered. Example: Heimdalsgade 42, 2200 København N |
| sellerName | string | required | Name of the seller, for p2c platform it can be the restaurant name. Example: Barakat grill & pizza restaurant |
| sellerPhone | string | required (p2p) or optional (p2c) | Phone number of the seller. for p2p platform its required but for p2c platform type it's optional (restaurant phone name) |
| timeForDropOff | DateTime | required: if scheduled order | Date and time of the delivery, for scheduled order it's required, if this field is not provided then it's a ASAP order. Example: 2019-02-08 16:50 |
| customerName | string | required | Name of the customer |
| customerPhone | string | required | Phone numner of the customer. Example: 91722653 |
| customerFloor | string | optional | Floor numner of the customer. Example: 1.Tv |
| productSize | string | required | The size of the products, it can be [small ,medium, big]. Our Bag size is W: 16 x L: 16 x H: 18 "Inch". For Food category: 0-6 items AND price <> 0 - 550 dkk: small,0-9 items AND price <> 551 - 999 dkk: medium,10 > items AND price > 1000 dkk: big |
| description | string | optinal | Any instruction / comments about the order. |
Checkout response:
201 - When the order it created
200 - Order maybe already exists and confirmed
200 - Order maybe already exists and needs to confirm using confirm API
200 - Order maybe can't place in time (for scheduled order) and Doorhub sends best possible suggestion time
400 - Any bad request, like the zone is not supported by Doorhub etc.
422 - If any required request field is missing / any error
{success} Example of a response [201]
when the order is created, it will response with http code: 201
{
"success": true,
"message": "Order processed successfully",
"data": {
"id": "ORD79-0005",
"deliveryId": "3364",
"serviceName": "Doorhub delivery",
"timeUnit": "minute",
"priceUnit": "DKK",
"estimatedPickupTime": 24,
"estimatedTimeForPickup": "2019-03-19 16:28",
"estimatedDeliveryTime": 55,
"estimatedTimeForDelivery": "2019-03-19 16:58",
"estimatedDeliveryCharge": 47,
"order": {
"id": "ORD79-0005",
"customerName": "Shamsul Alam",
"customerPhone": "91766313",
"customerFloor": "3tv",
"deliveryId": "3364",
"sellerName": "Barakat & Grill",
"pickupAddress": "Amerikavej 19, copenhagen",
"dropOffAddress": "Heimdalsgade 42, copenhagen",
"estimatedTimeForPickup": "2019-03-19 16:28",
"estimatedTimeForDelivery": "2019-03-19 16:58",
"deliveryCharge": 47,
"productSize": "Small",
"orderCreated": "2019-03-19 16:03:32",
"confirmed": true,
"description": "This is the order description with also supports unicode åäö..."
}
}
}{danger} Example of a response [422]
if any arguments is missing that is required
{
"success": false,
"message": "The delivery id field is required.",
"error": {
"deliveryId": [
"The delivery id field is required."
],
"regionName": [
"The region name field is required."
]
}
}{warning} Example of response [200]
if the order is already placed and confirmed
{
"success": true,
"message": "Order is already exists, please check the order status",
"data": {
"id": "ORD79-0005",
"deliveryId": "3364",
"serviceName": "Doorhub delivery",
"timeUnit": "minute",
"priceUnit": "DKK",
"order": {
"id": "ORD79-0005",
"customerName": "Shamsul Alam",
"customerPhone": "91766313",
"customerFloor": "3tv",
"deliveryId": "3364",
"sellerName": "Barakat & Grill",
"pickupAddress": "Amerikavej 19, copenhagen",
"dropOffAddress": "Heimdalsgade 42, copenhagen",
"estimatedTimeForPickup": "2019-03-19 16:28:00",
"estimatedTimeForDelivery": "2019-03-19 16:58:00",
"deliveryCharge": 47,
"productSize": "small",
"orderCreated": "2019-03-19 16:03:32",
"confirmed": true,
"description": "This is the order description with åäö"
}
}
}{warning} Example of response [200]
if the order is waiting for confirmation
{
"success": true,
"message": "Order needs to confirm, please check the order status",
"data": {
"id": "ORD79-0005",
"deliveryId": "3364",
"serviceName": "Doorhub delivery",
"timeUnit": "minute",
"priceUnit": "DKK",
"order": {
"id": "ORD79-0005",
"customerName": "Shamsul Alam",
"customerPhone": "91766313",
"customerFloor": "3tv",
"deliveryId": "3364",
"sellerName": "Barakat & Grill",
"pickupAddress": "Amerikavej 19, copenhagen",
"dropOffAddress": "Heimdalsgade 42, copenhagen",
"estimatedTimeForPickup": "2019-03-19 16:28:00",
"estimatedTimeForDelivery": "2019-03-19 16:58:00",
"deliveryCharge": 47,
"productSize": "small",
"orderCreated": "2019-03-19 16:03:32",
"confirmed": false,
"description": "This is the order description with åäö"
}
}
}{warning} Example of response [200]
if Doorhub can't delivered the order with in specified time and provide suggestion time, this order needs to confirm if Platform needs to place the order
{
"success": true,
"message": "DropOff not possible within required time",
"suggestion": true,
"data": {
"id": "ORD79-0006",
"pickupTime": "2019-03-19 16:53",
"dropOffTime": "2019-03-19 17:23",
"deliverId": "3365",
"validUntil": "2019-03-19 16:33"
}
}This service used to confirm an order that was not placed into Doorhub system but instead Doorhub responses with the best possible timeForPickup and timeForDropOff time. Platform needs to confirm to agree with the suggested times provided by Doorhub.
{primary} Example of request
curl -X POST "https://doorhub.io/api/platform/v1/orders/checkout/confirm"
-H "Authorization: Bearer {api-key}"
-H "Api-Version: v1"
-H "Content-Type: application/json"
-d '{"orderId":"ORD79-0006","deliveryId":"3365"}'{success} Example of response [200]
{
"success": true,
"message": "Order confirmed successfully",
"data": {
"id": "ORD79-0006",
"deliveryId": "3365",
"serviceName": "Doorhub delivery",
"timeUnit": "minute",
"priceUnit": "DKK",
"order": {
"id": "ORD79-0006",
"customerName": "Shamsul Alam",
"customerPhone": "91766313",
"customerFloor": "3tv",
"deliveryId": "3365",
"sellerName": "Barakat & Grill",
"pickupAddress": "Amerikavej 19, copenhagen",
"dropOffAddress": "Heimdalsgade 42, copenhagen",
"estimatedTimeForPickup": "2019-03-19 17:43:00",
"estimatedTimeForDelivery": "2019-03-19 17:23:00",
"deliveryCharge": 47,
"productSize": "small",
"confirmed": true,
"description": "This is the order description with åäö"
}
}
}{warning} Example of response [200]
if the valid time expired for confirming the order and new pickup and drop off time suggested
{
"success": true,
"message": "Validity time expired",
"suggestion": true,
"data": {
"id": "ORD79-0006",
"pickupTime": "2019-03-19 18:36",
"dropOffTime": "2019-03-19 19:06",
"deliveryId": "3365",
"valid_until": "2019-03-19 18:16"
}
}{danger} Example of response [422]
if the order id or delivery id is not valid
{
"success": false,
"message": "orderId is not a valid order id",
"error": []
}{warning} Example of response [200]
{
"success": true,
"message": "Order is already confirmed",
"data": {
"id": "ORD79-0006",
"deliveryId": "3365",
"serviceName": "Doorhub delivery",
"timeUnit": "minute",
"priceUnit": "DKK",
"order": {
"id": "ORD79-0006",
"customerName": "Shamsul Alam",
"customerPhone": "91766313",
"customerFloor": "3tv",
"deliveryId": "3365",
"sellerName": "Barakat & Grill",
"pickupAddress": "Amerikavej 19, copenhagen",
"dropOffAddress": "Heimdalsgade 42, copenhagen",
"estimatedTimeForPickup": "2019-03-19 17:43:00",
"estimatedTimeForDelivery": "2019-03-19 17:23:00",
"deliveryCharge": 47,
"productSize": "small",
"orderCreated": "2019-03-19 18:20:00",
"confirmed": true,
"description": "This is the order description with åäö"
}
}
}This service is used to cancel an order. Any order maybe canceled after it is placed to the Doorhub system.
When order can be cancel?
Which cases the order can't be cancel?
An order maybe canceled but still might charged as if the pickup time less than 10 minutes
{primary} Example of request
curl -X PATCH "https://doorhub.io/api/platform/v1/orders/cancel/{orderRef}"
-H "Authorization: Bearer {api-key}"
-H "Api-Version: v1"{success} Example of response [200]
{
"success": true,
"message": "Order is canceled",
"data": {
"id": "ORD79-0006",
"deliveryId": "3365",
"customerName": "Shamsul Alam",
"customerPhone": "91766313",
"sellerAddress": "Amerikavej 19, copenhagen",
"sellerName": "Barakat & Grill",
"orderedAt": "2019-03-19 18:20:00",
"pickupTime": "2019-03-20 11:05:00",
"dropOffTime": "2019-03-19 17:23:00"
}
}{danger} Example of response [400]
if the order is not valid
{
"success": false,
"message": "order is not a valid order id",
"error": []
}{danger} Example of response [400]
{
"success": false,
"message": "order can't cancel",
"error": []
}{danger} Example of response [400]
{
"success": false,
"message": "order can't cancel, less than 10 min to pickup",
"error": []
}This service is used to edit an existing order, an order drop off time or delivery address can be changed.
This service is used to view an existing order details.
{primary} Example of request
curl -X GET -G "https://doorhub.io/api/platform/v1/orders/{orderRef}"
-H "Authorization: Bearer {api-key}"
-H "Api-Version: v1"{success} Example of response [200]
{
"success": true,
"message": "",
"data": {
"id": "ORD79-0007",
"deliveryId": "3366",
"serviceName": "Doorhub delivery",
"timeUnit": "minute",
"priceUnit": "DKK",
"order": {
"id": "ORD79-0007",
"customerName": "Shamsul Alam",
"customerPhone": "91766313",
"customerFloor": "3tv",
"deliveryId": "3366",
"sellerName": "Barakat & Grill",
"pickupAddress": "Amerikavej 19, copenhagen",
"dropOffAddress": "Heimdalsgade 42, copenhagen",
"estimatedTimeForPickup": "2019-03-20 19:41:00",
"estimatedTimeForDelivery": "2019-03-20 20:11:00",
"deliveryCharge": 47,
"productSize": "small",
"confirmed": true,
"description": "This is the order description with åäö"
}
}
}