DSP Integration Guide

1 - DSP Introduction

The Public API is a tool that allows to integrate with Taker Go and helps make food delivery a fast and comfy for restaurants and end users.The diagram of communication Taker go with the restaurant business and DSP shown below.

Block Schema 1

2 - Base Urls

Production API Base URL: https://production.go.taker.io/
Sandbox API Base URL: https://sandbox.go.taker.io/

3 - Creating Account

Developer Applications and Sandbox accounts are created by Taker Go team after obtaining some needed information from the developerThe needed information include the following:

3.1 - Redirect URL

This is the URL to which you want Taker Go user to be redirected after successfully authorizing your App.You need to provide a direct link for your production application, not a link to the local host for your Sandbox application.

3.2 - Webhook URL & Webhook Events

When changing the order status, we expect a Webhook from the DSP (for more information, see section 8.4).

3.3 - Install URL and Token

To register your application, we need to get an url-address and Token from you.The authorization processis alwaysinitiated from your App sideWhen your App gets officially listed in Taker Go Marketplace, Taker Go user will be able to install your App directly from the marketplaceWhen user clicks on install, user will be taken to the Install URL that you will use to know that a Taker Go user wants to install your Taker Go AppFrom there, you should initiate the authorization process with Taker Go authorization server

Details should be sent to support@takergo.com

4 - Security of data transfer

To ensure the security of both systems, the Bearer token is used.

5 - Error

If the request is not executed, the API returns Error -422 (E-422)

The above command returns JSON structured like this:

{
  "error_key": [
    "Error text"
  ]
}

6 - Order Status

The list of order statuses

const STATUSES = [
    'NO_STATUS'        => 0,
    'PENDING'          => 11,
    'ASSIGNED'         => 12,
    'WAY_TO_STORE'     => 13,
    'ARRIVED_AT_STORE' => 14,
    'WAY_TO_CUSTOMER'  => 15,
    'NEAR_CUSTOMER'    => 16,
    'DELIVERED'        => 21,
    'CANCELED'         => 31,
    'RETURNED'         => 32,
    'DSP_ISSUE'        => 33,
    'NOT_SENT'         => 34
];

7 - Payment Types from Taker Go

You can make order in the mobile application, on the website, by phone number or order at a kiosk and pay for the order as follows:

const PAYMENT_TYPE = [
    'CASH'      =>  0,
    'ONLINE'    =>  1,
    'POINTS'    =>  2,
    'TERMINAL'  =>  3
];

8 - Work with external API

DSP_URL - Installed from the side of the Taker.

DSP_TOKEN - Installed from the side of the Taker.

TAKER_TOKEN - Installed from the side of the Taker.

id – Taker Go Order ID.

8.1 - Public Create Order (in DSP)

The request for a Public Create Order (in DSP) must contain the following data:

Endpoint: POST - DSP_URL/orders

Headers

{
  "Authorization" : "Bearer DSP_TOKEN",
  "Content-Type": "application/json"
}

Body

{
  "id": integer,
  "pickup_details": {
    "name": string,
    "phone": string(ex: "+966555633706"),
    "coordinate": {
      "latitude": float,
      "longitude": float
    },
    "address": string
  },
  "delivery_details": {
    "name": string,
    "phone": string(ex: "+966555633706"),
    "coordinate": {
      "latitude": float,
      "longitude": float
    },"address": string
  },
  "order": {
    "reference": string,
    "payment_type": int (PAYMENT_TYPE),
    "currency": string(ex: "SAR"), 
    "total": float,
    "notes": {
      "ar": string,
      "en": string
    }
  },
  "business": {
    "name": string,
    "phone": string(ex: "+966555633706"),
    "logo": url
  }
}

Expected Response

Expected “Status Code” - 200

Expected Response Body

{
  "dsp_order_id":  string, // DSP order ID
  "status": STATUSES
}

8.2 - Public Get Order (in DSP)

The request for a Public GetOrder (in DSP) must contain the following data:

Endpoint: GET - DSP_URL/orders/{ID}

Headers

{
  "Authorization" : "Bearer DSP_TOKEN",
  "Content-Type": "application/json"
}

Body

{}

Expected Response

Expected “Status Code” - 200

Expected Response Body

{
  "dsp_order_id", string,
  "status": STATUSES,
// IF Status "ASSIGNED" or more
  "driver":? {
      "name": string,
      "phone": string(ex: "+966555633706"),
      "image":? url,
      "rating":? float (ex: 4.32)
  }
}

8.3 - Public Delete Order (in DSP)

The request for a Public DeleteOrder (in DSP) must contain the following data:

Endpoint: DELETE - DSP_URL/orders/{ID}

Headers

{
  "Authorization" : "Bearer DSP_TOKEN",
  "Content-Type": "application/json"
}

Body

{}

Expected Response

Expected “Status Code” - 200

Expected Response Body

{}

8.4 - Expected Webhook (from DSP)

The request for Expected Webhook (from DSP)must contain the following data:

Endpoint: POST - /webhooks/public

Status - Success

Headers

{
  "Authorization" : "Bearer DSP_TOKEN",
  "Content-Type": "application/json"
}

Body

{
  "dsp_order_id", string,
  "status": STATUSES,
// IF Status "ASSIGNED" or more
  "driver":? {
      "name": string,
      "phone": string(ex: "+966555633706"),
      "image":? url,
      "rating":? float (ex: 4.32)
  }
}

Expected Response

Expected “Status Code” - 200

Expected Response Body

{}

Status - Error

Expected Response

Expected “Status Code” - 422

Expected Response Body

{}

Restaurant Integration Guide

1 - Restaurant Introduction

The Public API is a tool that allows to integrate with TakerGo service and helps make fooddelivery a fast and comfy for restaurants and end users. The diagram of communicationTakerGo with the restaurant which is not Taker client shown below.

Block Schema 2

2 - Base Urls

Production API Base URL: https://production.go.taker.io/
Sandbox API Base URL: https://sandbox.go.taker.io/

3 - TakerGo Order ID

Be attentive, every delivery in TakerGo has its own ID, so you need to regularly update theID of the order on your side.

4 - Creating Account

Sandbox and Production accounts are created by TakerGo team after obtaining some needed information from the restaurant.

The needed information include the following:

ORGANIZATION_URL - Installed from the side of the TakerGo

This is the URL from which you will send us order details for searching the driver and to which you want TakerGo will send you order statuses. You need to provide a direct link for your production application and a link to your sandbox application for test orders.

ORGANIZATION_TOKEN - Installed from the side of the TakerGo

To register your account, we need also to get a Bearer Token from you, Token must include the word Bearer. To ensure the security of both systems, the Bearer token is used.

TAKERGO_TOKEN - Installed from the side of the TakerGo

5 - Error

If the request is not executed, the webhook returns Error - 4XX (E-4XX) as follows:

{
  "error_key": [
    "Error text"
  ]
}

6 - Statuses

The list of order statuses

const STATUSES = [
  'NOT_ASSIGNED'      =>  1,
  'ASSIGNED'          =>  2,
  'COLLECTING_ORDER'  =>  3,
  'ON_THE_WAY'        =>  4,
  'DELIVERED'         =>  5,
  'CANCELED'          =>  6,
  'FAILED_TO_ASSIGN'  =>  7,
  'NEAR_PICK_UP'      =>  8,
  'AT_PICK_UP'        =>  9,
  'NEAR_DELIVERY'     => 10,
  'AT_DELIVERY'       => 11,
  'RETURNING'         => 12,
  'RETURNED'          => 13,
  'RE_ASSIGNING'      => 14
];

7 - Payment Types

You can make order in the mobile application, on the website, by phone number or order at a kiosk and pay for the order

const PAYMENT_TYPE = [
  'CASH'      =>  0,
  'ONLINE'    =>  1,
  'POINTS'    =>  2,
  'TERMINAL'  =>  3
];

8 - APIs

List of API endpoints

8.1 - Create Order to TakerGo

Endpoint: POST - /v2/orders

Headers

{ 
  "Authorization" : "Bearer TAKERGO_TOKEN", 
  "ContentType": "application /json"
}

Body

{
  "pickup_details": { 
    "name": string, 
    "phone": string (ex: "+966555633706"), 
    "coordinate": {
      "latitude": float, 
      "longitude": float
    }, 
    "address": string
  },
  "delivery_details": { 
    "name": string, 
    "phone": string(ex:"+966555633706"), 
    "coordinate": { 
      "latitude": float, 
      "longitude": float
    }, 
    "address": string
  },
  "order": { 
    "id": int, 
    "profile_id": int, 
    "reference": string, 
    "payment_type": int (PAYMENT_TYPE),
    "currency": string (ex: "SAR"), 
    "total": float, 
    "delivery_fee":? float (default: 0), 
    "notes": { 
      "ar": string, 
      "en": string
    }
  }, 
  "branch": { 
    "id": int (ex: 50), 
    "name": string, 
    "phone": string(ex:"+966555633706")
  }, 
  "business": { 
    "id": int (ORGANIZATION_ID), 
    "name": string (ex:"Mathaq Warq Enab; Branch: Twaiq Branch"), 
    "phone": string(ex: "+966555633706"), 
    "logo":url
  }, 
  "customer": { 
    "id": int (ex: 76484), 
    "name": string, 
    "phone_number": string (ex:"+966555633706") 
  }
}

Expected Response

Expected “Status Code” - 200

Expected Response Body

{
  "id": int, 
  "status": int (STATUSES) 
}

8.2 - Get Order to TakerGo

Endpoint: GET - /v2/orders/{ID}

Headers

{ 
  "Authorization" : "Bearer TAKERGO_TOKEN", 
  "ContentType": "application /json"
}

Body

{}

Expected Response

Expected “Status Code” - 200

Expected Response Body

{
  "id": int, 
  "status": int (STATUSES) 
}

8.3 - Send order to the next DSP

Endpoint: POST - /v2/orders/{ID}/next_dsp

Headers

{ 
  "Authorization" : "Bearer TAKERGO_TOKEN", 
  "ContentType": "application /json"
}

Body

{}

Expected Response

Expected “Status Code” - 200

Expected Response Body

{
  "id": int, 
  "status": int (STATUSES) 
}

8.4 - Cancel order

Endpoint: DELETE - /v2/orders/{ID}

Headers

{ 
  "Authorization" : "Bearer TAKERGO_TOKEN", 
  "ContentType": "application /json"
}

Body

{}

Expected Response

Expected “Status Code” - 202

Expected Response Body

{}

8.5 - Webhook Events from the restaurant

When changing the order status, we send you a Webhook from the DSP.

Endpoint: POST - ORGANIZATION_URL/takergo/v2/webhook/order

Headers

{ 
  "Authorization" : "Bearer TAKERGO_TOKEN", 
  "ContentType": "application /json"
}

Body

{ 
  "id": int, 
  "dsp_id": int, 
  "dsp_name":? string, 
  "dsp_order_id": string,
  "status": int (STATUSES), 
  "driver":? { 
    "name": string, 
    "phone_number": string, 
    "image_url":? url, 
    "rating":? float 
  }, 
  "profile_id": int, 
  "organization_id": int (ORGANIZATION_ID),
  "organization_order_ id": int
}

Expected Response

Expected “Status Code” - 200

Expected Response Body

{}

Webhook - No attempts

Endpoint: POST - ORGANIZATION_URL/takergo/v2/webhook/attempts

Headers

{ 
  "Authorization" : "Bearer TAKERGO_TOKEN", 
  "ContentType": "application /json"
}

Body

{ 
  "id": int, 
  "dsp_id": int, 
  "dsp_name":? string, 
  "attempts": int (0 or less),
  "profile_id": int, 
  "organization_id": int (ORGANIZATION_ID), 
  "organization_order _id": int
}

Expected Response

Expected “Status Code” - 200

Expected Response Body

{}

9 - Interface for using events

For using TakerGo service we recommend you to create the interface, which includes the following. The information is given as an example and is for guidance only.

Dispatching Rules page:

Profiles, where the restaurant will do settings for branches

The list of DSPs and on/off buttons (all DSPs wich integrated with TakerGo)

The priority fields for DSPs

Branch list (the list of branches with on/off buttons for selected DSPs)

Driver acceptance timeout field (the time for driver searching in each DSP)

Dispatching rules

Order details interface:

Order Details