# Specification

# API types

Open API are HTTPS APIs. There are 2 types of API: Request API and Callback API.

# Request API

The API call is requested from Client system to Zeek platform.

# Callback API

The Zeek platform updates developer by means of callback API. For example, when the delivery order status is changed, the platform will send the latest status to client system via callback API. Therefore developer needs to provide the callback URL to platform.

# Standard

  • HTTPS protocol should be applied in API requests.
  • UTF-8 encoding is used.
  • Content-Type in Header should be "application/json".

# API URL

# Sandbox environment

Developers can perform API integration and testing on Sandbox environment.

Zone URL Region
AP1 https://sandbox-ap1-open-api.zeek.one/v1.3 Hong Kong
AP2 https://sandbox-ap2-open-api.zeek.one/v1.3 Singapore, Kuala Lumpur, Bangkok, Ho Chi Minh City
  • We provide different development environment for client who requires customized integration. Please contact our team for details.

# Release environment

Release environment is for live service.

Zone URL Region
AP1 https://ap1-open-api.zeek.one/v1.3 Hong Kong
AP2 https://ap2-open-api.zeek.one/v1.3 Singapore, Kuala Lumpur, Bangkok, Ho Chi Minh City

# Data format

The data formats of request and response are JSON.

# API request

# Request data format

In API request, auth, data and data.meta are mandatory in request body.

{
    "auth":{
        "appid":100000001,
        "timestamp":1528793155,
        "signature":"b7e5162e8ce738ec964c71f54857af32"
    },
    "data":{
        "meta":{
            "lang":"zh-HK",
            "region":"HK"
        },
        
        // Other parameters here.
    }
}
# Global parameters

Global parameters are mandatory in every API call (including Request API and Callback API). Here are the parameters:

Parameter name Type Description Remarks
appid int App ID Provided by Zeek
signature string Signature Used for API authentication. Please refer to Authentication
timestamp int Current timestamp in second Example: 1548151468
lang string Language Please refer to lang parameter
region string Region Please refer to region parameter
# Request example
curl --location --request POST 'https://ap1-open-api.zeek.one/v1.3/order/takeaway/merchants/supported' \
--header 'Content-Type: application/json; charset=utf-8' \
--data '{
    "auth":{
        "appid":10000001,
        "timestamp":1528793155,
        "signature":"d22e6c489d8d4969234fbeb865decd53"
    },
    "data":{
        "meta":{
            "lang":"zh-HK",
            "region":"HK"
        },
        
        // 其他接口參數例子
        "merchant_id": 123,
        "order_id": "FD3165848793513984"
    }
}'

# API response

# HTTP status code

If developer receives HTTP status code 200 from a API request, it means that the system receives request and return result. Here are two situations:

1.The API request is successful.

2.The API request is failed due to incorrect parameters. You can find the error code in reponse body.

For other failure reasons, (for instance, incorrect API URL), the system will response with HTTP status codes according to common practices. For example, it will return 404 for resource not found.

# Request data format
Name Type Description Remarks
error int Error code - Return 0 when API request is successful.
- For other error codes, please refer to Error codes
data object / array Result data - Only return when the API request is successful.
- Please refer to the response data format of each API.
err_msg string Error message - Only return when the API request is failed.

Example of a successful API request:

{
    "error": 0,
    "data": {
        "order_id": "FD3165848793513984",
        "client_order_id": "15104092022333"
    }
}

Example of a failed API request:

{
    "error": 261004,
    "err_msg": "Incorrect parameters"
}

# Timezone

The timezone for API requests and responses are local time. The local timezone is defined according to region value. For example, if region="HK", the timezone should be UTC+8.

# Geolocation

The coordinates data format in use is "latitude,longitude". For example, 22.285944,114.158177.

# Authentication

API Authentication is performed by signature. Signature is a summary of the request payload. Content of signature should comprise of the actual request payload being sent and the developer’s appid, secretkey shared by Zeek team.

The signature is unique in every API request. Therefore, you need to generate the signature by request parameters. Here we will explain the procedures by an example.

# Step 1. Obtain App ID and App Secret

Zeek team provides appid and secret_key to developer. Developer needs them in signature generation. Therefore, please keep it secure.

Parameter Example
appid 10000001
secret_key da39a3ee5e6b4b0d3255bfef95601890afd80709

# Step 2. Generate request_param_string

For example, the orignal request payload data is

{
   "merchant_id":"457",
   "client_order_id":"72755da14c35",
   "client_shipment_code":"72755da14c28",
   "box_size":3,
   "pickup":{
      "date":"2019-07-30",
      "period":"12:00-16:00"
   },
   "product_name":"Product A",
   "remarks":""
}

Before concatenation, remove parameters which are not numeric nor string.

{
   "merchant_id":"457",
   "client_order_id":"72755da14c35",
   "client_shipment_code":"72755da14c28",
   "box_size":3,
   "product_name":"Product A",
   "remarks":""
}

Sort parameters by key alphabetically in ascending order.

{ 
   "box_size":3,
   "client_order_id":"72755da14c35",
   "client_shipment_code":"72755da14c28",
   "merchant_id":"457",
   "product_name":"Product A",
   "remarks":""
}

Join each parameter by its key and value by =. Then join the resulted strings by &. The request_param_string will be generated:

Parameter Example
appid 10000001
secret_key da39a3ee5e6b4b0d3255bfef95601890afd80709
request_param_string box_size=3&client_order_id=72755da14c35&client_shipment_code=72755da14c28&merchant_id=457
&product_name=Product A&remarks=

# Step 3. Generate pre_signature

Append appid, secret_key, timestamp to request_param_string, use & to join them. Generate pre_signature.

Parameter Example
appid 10000001
secret_key da39a3ee5e6b4b0d3255bfef95601890afd80709
timestamp 1528793155
request_param_string box_size=3&client_order_id=72755da14c35&client_shipment_code=72755da14c28&merchant_id=457
&product_name=Product A&remarks=
pre_signature box_size=3&client_order_id=72755da14c35&client_shipment_code=72755da14c28&merchant_id=457
&product_name=Product A&remarks=&10000001&da39a3ee5e6b4b0d3255bfef95601890afd80709
&1528793155

# Step 4. Generate signature

Use MD5 to encrypt pre_signature. Finally signature will be generated.

Parameter Example
appid 10000001
secret_key da39a3ee5e6b4b0d3255bfef95601890afd80709
timestamp 1528793155
request_param_string box_size=3&client_order_id=72755da14c35&client_shipment_code=72755da14c28&merchant_id=457
&product_name=Product A&remarks=
pre_signature box_size=3&client_order_id=72755da14c35&client_shipment_code=72755da14c28&merchant_id=457
&product_name=Product A&remarks=&10000001&da39a3ee5e6b4b0d3255bfef95601890afd80709
&1528793155
signature d22e6c489d8d4969234fbeb865decd53

# Step 5. Passing signature into the request body

Please note that it is only an example of request body. Please input the request body according the API format specified.

{
    "auth":{
        "appid":10000001,
        "timestamp":1528793155,
        "signature":"d22e6c489d8d4969234fbeb865decd53"
    },
    "data":{
        "meta":{
            "lang":"zh-HK",
            "region":"HK"
        },
        "merchant_id":"457",
        "client_order_id":"72755da14c35",
        "client_shipment_code":"72755da14c28",
        "box_size":3,
        "pickup":{
            "date":"2019-07-30",
            "period":"12:00-16:00"
        },
        "product_name":"Product A",
        "remarks":""
    }
}

# Signature debug tool

You can use this tool to check whether the steps are correct:

Input secret_key :

Input request payload :

# Parameter list

# region

Region Value
Hong Kong HK
Singapore SG
Kuala Lumpur KUL
Bangkok BKK
Ho Chi Minh City SGN

# lang

Supported languages in each region:

Region lang parameter
Hong Kong Traditional Chinese: zh-HK
English: en
Singapore English: en
Kuala Lumpur Malay: ms
English: en
Bangkok Thai: th
English: en
Ho Chi Minh City Vietnamese: vi
English: en

# Error codes

Error code Description
261002 Incorrect timestamp. For example, the different between input timestamp and current timestamp exceeds 180 seconds
261003 Missing mandatory parameters
261004 Incorrect parameters
261005 Duplicated data is submitted within 60 seconds
261105 Error in redis operation
261103 Error in database operation
262001 Developer account does not exist
262002 Incorrect signature
262111 Cannot create order due to insufficient permission
263006 Exceeded delivery distance limit
263001 Delivery order does not exist
263004 Delivery order has been created already
263014 Exceeded scheduled time limit
264007 Exceeded merchant's opening hours
264100 Merchant does not exist
264101 Exceeded merchant number limit