# 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.

• 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.

# 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:

# Request example

curl --location --request POST 'https://ap1-open-api.zeek.one/v1.1/order/homeexpress/get_datetime' \
--header 'Content-Type: application/json; charset=utf-8' \
--data '{
    "auth":{
        "appid":10000001,
        "timestamp":1528793155,
        "signature":"d22e6c489d8d4969234fbeb865decd53"
    },
    "data":{
        "meta":{
            "lang":"zh-HK",
            "region":"HK"
        },
        
        // Other request parameters here
        "merchant_id": 123,
        "product_code": "HDP-ECOMM-H"
    }
}'

# 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

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.

# 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:

# Step 3. Generate pre_signature

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

# Step 4. Generate signature

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

# 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:

# Parameter list

Hong Kong

# Error codes