doorhub logo doorhub

Integration Details Overview

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


Registration

First of all company needs to register into the Doorhub system. Register.

Once a company 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 co_test_*

You LIVE api key will be activated once the integration is complete and agreed by both parties (Doorhub and Company). Live api key should be used for the production environment for placing the real orders.

Key format: Live api key starts with co_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 company is registered company already selected which regions company wants to deliver the orders. Doorhub only deliver's orders that are supported by Doorhub delivery zones and Sub store has to be registered on that region. For an example, if company didn't registered for Roskilde region, company can't place an order to that region.

Get Zones [check the api]

Using this api service company can get all the delivery regions that Doorhub supports for them (the company).

{primary} Example of a request

curl -X GET -G "https://doorhub.io/api/company/v1/zones/list" 
    -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"
        }
    ]
}

Get sub stores [check the api]

Using this api service company can get all the delivery regions that Doorhub supports for them (the company).

{primary} Example of a request

curl -X GET -G "https://doorhub.io/api/company/v1/store/subStores" 
    -H "Authorization: Bearer {api-key}" 
    -H "Api-Version: v1"

{success} Example of response [200]

{
    "success": true,
    "message": "Sub-stores list",
    "data": [
        {
            "subStoreId": 1,
            "subStoreName": "DH Restaurant",
            "pickupAddress": "Gammel Jernbanevej 31, København, Denmark",
            "city": "Copenhagen"
        }
    ]
}

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

{primary} Example of a request

curl -X POST "https://doorhub.io/api/company/v1/zones/support" 
    -H "Authorization: Bearer {api-key}" 
    -H "Api-Version: v1" 
    -d "subStoreId"=1
    -d "pickupAddress"="Toftegårds Allé 49, 2500 København" 
    -d "dropOffAddress"="Heimdalsgade 44, 2200 København" 


Body Parameters
Parameters Type Status Description
subStoreId number required subStoreId maped with doorhub delivery zone.
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

{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

Place an order [check the api]

To place an order to Doorhub as company, you will use this checkout service.

There are two types of orders

  1. ASAP (As Soon As Possible) orders
  2. 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: company 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 Company 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/company/v1/order/checkout" 
    -H "Authorization: Bearer {api-key}" 
    -H "Api-Version: v1" 
    -H "Content-Type: application/json" 
    -d '{
        "pickupAddress": "valby, copenhagen",
        "dropOffAddress" : "Ryparken 33",
        "customerName" : "Qutub",
        "customerPhone" : "52172329",
        "productSize" : "medium",
        "customerFloor" : "11", 
        "timeForDropOff" : "2019-04-10 16:08",
        "subStoreId" : 1,
        "description" : "this is test",
        "deliveryId" : "1000005",
        "description":"Please call on my mobile when you are here, the outside building calling button does not works!"
        }'


Body Parameters
Parameters Type Status Description
subStoreId integer required Sub Store Id is for the reference of the sub store.
deliveryId string required Delivery order Id in the company 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, (store name)
sellerPhone string optional Phone number of the seller, store phone
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": "CMP1-0179",
        "deliveryId": "1000005",
        "serviceName": "Doorhub delivery",
        "timeUnit": "minute",
        "priceUnit": "DKK",
        "estimatedPickupTime": 29,
        "estimatedTimeForPickup": "2019-04-10 15:32",
        "estimatedDeliveryTime": 15,
        "estimatedTimeForDelivery": "2019-04-10 16:08",
        "estimatedDeliveryCharge": 55.2,
        "order": {
            "id": "CMP1-0179",
            "customerName": "Qutub",
            "customerPhone": "52172329",
            "customerFloor": "11",
            "deliveryId": "1000005",
            "sellerName": "DH Restaurant",
            "pickupAddress": "valby, copenhagen",
            "dropOffAddress": "Ryparken 33",
            "estimatedTimeForPickup": "2019-04-10 15:32",
            "estimatedTimeForDelivery": "2019-04-10 16:08",
            "deliveryCharge": 55.2,
            "productSize": "medium",
            "orderCreated": "2019-04-10 14:28:44",
            "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": "CMP1-0179",
        "deliveryId": "1000005",
        "serviceName": "Doorhub delivery",
        "timeUnit": "minute",
        "priceUnit": "DKK",
        "order": {
            "id": "CMP1-0179",
            "customerName": "Qutub",
            "customerPhone": "52172329",
            "customerFloor": "11",
            "deliveryId": "1000005",
            "sellerName": "DH Restaurant",
            "pickupAddress": "valby, copenhagen",
            "dropOffAddress": "Ryparken 33",
            "estimatedTimeForPickup": "2019-04-10 15:32:00",
            "estimatedTimeForDelivery": "2019-04-10 16:08:00",
            "deliveryCharge": 55.2,
            "productSize": "medium",
            "orderCreated": "2019-04-10 14:28:44",
            "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": "CMP1-0180",
        "deliveryId": "1000006",
        "serviceName": "Doorhub delivery",
        "timeUnit": "minute",
        "priceUnit": "DKK",
        "order": {
            "id": "CMP1-0180",
            "customerName": "Qutub",
            "customerPhone": "52172329",
            "customerFloor": "11",
            "deliveryId": "1000006",
            "sellerName": "DH Restaurant",
            "pickupAddress": "valby, copenhagen",
            "dropOffAddress": "Ryparken 33",
            "estimatedTimeForPickup": "2019-04-10 15:07:00",
            "estimatedTimeForDelivery": "2019-04-10 15:43:00",
            "deliveryCharge": 55.2,
            "productSize": "medium",
            "orderCreated": "2019-04-10 14:37:23",
            "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 Company needs to place the order

{
     "success": true,
        "message": "DropOff not possible within required time",
        "data": {
            "id": "CMP1-0180",
            "pickupTime": "2019-04-10 15:07",
            "dropOffTime": "2019-04-10 15:43",
            "deliveryId": "1000006",
            "validUntil": "2019-04-10 14:42"
        },
        "suggestion": true
}

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. Company needs to confirm to agree with the suggested times provided by Doorhub.

{primary} Example of request

curl -X POST "https://doorhub.io/api/company/v1/order/checkout/confirm" 
    -H "Authorization: Bearer {api-key}" 
    -H "Api-Version: v1" 
    -H "Content-Type: application/json" 
    -d '{"orderId":"CMP1-0180","deliveryId":"1000006"}'

{success} Example of response [200]

{
    "success": true,
    "message": "Order confirmed successfully",
    "data": {
        "id": "CMP1-0180",
        "deliveryId": "1000006",
        "serviceName": "Doorhub delivery",
        "timeUnit": "minute",
        "priceUnit": "DKK",
        "order": {
            "id": "CMP1-0180",
            "customerName": "Qutub",
            "customerPhone": "52172329",
            "customerFloor": "11",
            "deliveryId": "1000006",
            "sellerName": "DH Restaurant",
            "pickupAddress": "valby, copenhagen",
            "dropOffAddress": "Ryparken 33",
            "estimatedTimeForPickup": "2019-04-10 15:07:00",
            "estimatedTimeForDelivery": "2019-04-10 15:43:00",
            "deliveryCharge": 55.2,
            "productSize": "medium",
            "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",
    "data": {
        "id": "CMP1-0182",
        "pickupTime": "2019-04-10 15:34",
        "dropOffTime": "2019-04-10 16:10",
        "deliveryId": "1000008",
        "validUntil": "2019-04-10 15:09"
    },
    "suggestion": true
}

{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": "CMP1-0181",
       "deliveryId": "1000007",
       "serviceName": "Doorhub delivery",
       "timeUnit": "minute",
       "priceUnit": "DKK",
       "order": {
           "id": "CMP1-0181",
           "customerName": "Qutub",
           "customerPhone": "52172329",
           "customerFloor": "11",
           "deliveryId": "1000007",
           "sellerName": "DH Restaurant",
           "pickupAddress": "valby, copenhagen",
           "dropOffAddress": "Ryparken 33",
           "estimatedTimeForPickup": "2019-04-10 15:12:00",
           "estimatedTimeForDelivery": "2019-04-10 15:48:00",
           "deliveryCharge": 55.2,
           "productSize": "medium",
           "orderCreated": "2019-04-10 14:42:40",
           "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/company/v1/order/cancel/{orderRef}" 
    -H "Authorization: Bearer {api-key}" 
    -H "Api-Version: v1"

{success} Example of response [200]

{
    "success": true,
    "message": "Order is canceled",
    "data": {
        "id": "CMP1-0181",
        "deliveryId": "1000007",
        "customerName": "Ahmed",
        "customerPhone": "52172329",
        "sellerAddress": "valby, copenhagen",
        "sellerName": "DH Restaurant",
        "orderedAt": "2019-04-10 14:42:40",
        "pickupTime": "2019-04-10 15:12:00",
        "dropOffTime": "2019-04-10 15:48: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/company/v1/order/{orderRef}/show" 
    -H "Authorization: Bearer {api-key}" 
    -H "Api-Version: v1"

{success} Example of response [200]

{
     "success": true,
        "message": "",
        "data": {
            "id": "CMP1-0179",
            "deliveryId": "1000005",
            "serviceName": "Doorhub delivery",
            "timeUnit": "minute",
            "priceUnit": "DKK",
            "order": {
                "id": "CMP1-0179",
                "customerName": "Qutub",
                "customerPhone": "52172329",
                "customerFloor": "11",
                "deliveryId": "1000005",
                "sellerName": "DH Restaurant",
                "pickupAddress": "valby, copenhagen",
                "dropOffAddress": "Ryparken 33",
                "estimatedTimeForPickup": "2019-04-10 15:32:00",
                "estimatedTimeForDelivery": "2019-04-10 16:08:00",
                "deliveryCharge": 55.2,
                "productSize": "medium",
                "confirmed": true,
               "description": "This is the order description with åäö",
               "status": "waiting"
        }
    }
}