Integration Details Overview

Learn the platform integration in details. We have described all the integration steps in details here.

Registration

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.

Test environment

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.

API Keys

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 zones / regions

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.

Get doorhub delivery zones [check the api]

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.

Copenhagen
Roskilde

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": []
}

Get doorhub city zone [Check the api]

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"

Query Parameters

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"
            }
        ]
    }
}

Check if the addresses are in delivery zone [check the api]

{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"

Body Parameters

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"
         ]
    }
}

Order

Pre checkout the time and charge [check the api]

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",
       }'

Body Parameters

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
    }
}

Place an order [check the api]

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 (As Soon As Possible) orders
Scheduled 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",
            "owner_id":"123312",
            "deliveryId":"ORD345987",
            "pickupAddress":"Toftegårds Allé 49, 2500 København",
            "dropOffAddress":"Heimdalsgade 44, 2200 K\u00f8benhavn",
            "dropOffLatitude": 53.3584319,
            "dropOffLongitude": -6.2760482,
            "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!"
        }'

Body Parameters

Parameters	Type	Status	Description
regionName	string	required	`zone_city` name which was the response from the zone api (Get doorhub delivery zones). Example: "copenhagen".
owner_id	string	optional, required if the platform is a p2c type	if the store is already registered into the Doorhub system you can send your own store id here. Example: "1234".
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	optional, required if dropOffLatitude & dropOffLongitude is not present	The google like address of the order where it should be delivered. Example: Heimdalsgade 42, 2200 København N
dropOffLatitude	numeric	optional, required if dropOffAddress is not present	The Latitude of the order where it should be delivered. Example: 53.3584319
dropOffLongitude	numeric	optional, required if dropOffAddress is not present	The Longotude of the order where it should be delivered. Example: -6.2760482
sellerName	string	required	Name of the seller, for p2c platform it can be the restaurant name. Example: Barakat grill & pizza restaurant
sellerPhone	string	required (c2c) or optional (p2c)	Phone number of the seller. for c2c 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
timeForPickup	DateTime	optional	Date and time of the Pickup, 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	optional	Any instruction / comments about the order.
prepTime	numeric	optional	What is the preparation time for this store.
cashOnDelivery	boolean	optional	If Doorhub allow cash on delivery to your region, you can send true, or else default is false, if you don't sent it, it will be default false too.

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"
    }
}

Confirm an order [check the api]

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 åäö"
        }
    }
}

Cancel an order [check the api]

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?

If there is no driver assigned to the order.
If the pickup time is not less than 10 minutes.

Which cases the order can't be cancel?

If the order is already picked up by the driver
If the order is already delivered to the customer

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": []
}

Edit an order [check the api]

This service is used to edit an existing order, an order drop off time or delivery address can be changed.

View an order [check the api]

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 åäö"
        }
    }
}

Doorhub

Doorhub Services

Integration Details Overview

Registration

Test environment

API Keys

Doorhub zones / regions

Get doorhub delivery zones [check the api]

Get doorhub city zone [Check the api]

Query Parameters

Check if the addresses are in delivery zone [check the api]

Body Parameters

Order

Pre checkout the time and charge [check the api]

Body Parameters

Place an order [check the api]

Body Parameters

Confirm an order [check the api]

Cancel an order [check the api]

Edit an order [check the api]

View an order [check the api]