# 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.
• Payload of API request and response are in JSON format.

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

# Production environment

Production environment is for live service.

# API Request

An example of API request by Curl:

curl --location --request POST 'https://ap1-open-api.zeek.one/parcel/v1.0/vas' \
--header 'Content-Type: application/json;charset=UTF-8' \
--header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c' \
--header 'KS-Region: SG' \
--header 'KS-Lang: en' \
--header 'KS-Client-Request-Id: f058ebd6-02f7-4d3f-942e-904344e8cde5' \
--data-raw '{
    "merchant_id": "1111111",
    "product_code": "DASH2HR"
}'

# HTTP Header

Please send the following HTTP headers in API requests.

# Content-Type

Please send application/json;charset=UTF-8, as all API request are in UTF-8 encoding and JSON.

# Authorization

You need to send access token in Authorization header, in order to get authorized to Zeek Open API access. Please refer to Authentication。

# KS-Region

Input the region in service:

# KS-Lang

Please send the language according to region:

# KS-Client-Request-Id

You are suggested to send a UUID in KS-Client-Request-Id Header. It helps us to locate the API request during troubleshooting. An example of UUID is f058ebd6-02f7-4d3f-942e-904344e8cde5.

# API Response

# HTTP status code

The HTTP status code will be included in API response:

• 200 OK
• 400 Bad Request
• 401 Unauthorized
• 403 Forbidden
• 404 Not Found
• 500 Internal Server Error

# HTTP Header

The following HTTP headers will be included in API response:

# Payload format

Example of a successful API request:

{
    "error": 0,
    "data": {
        "token_type": "Bearer",
        "access_token": "xxxxxxxxxxxxxxxxxxxxxxx",
        "expires_in": 86400,
        "scope": "delivery"
    }
}

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 Request

We use Client credentials flow of Oauth for API authentication. Here are the steps:

• Step 1: Developer obtains AppId and AppSecret from Zeek team.
• Step 2: Client system request PA-API-1.1 Get access token, use AppId and AppSecret to exchange the Access token. The TTL of access token is 24 hours.
• Step 3: While requesting other API, include access token in HTTP Header in the format: Authorization: Bearer [Access token]. Then the API request will be authenticated.

# Status Callback

The Order status callback 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

{
    "order_id": "DA-A-12345",
    "merchant_id": "123",
    "client": {
        "order_id": "11111111",
        "shipment_code": "22222222"
    },
    "status": {
        "code": "9015",
        "name": "Delivery in progress",
        "lastmodify": "2022-10-10 16:34:38"
        }
}

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

{
    "order_id": "DA-A-12345",
    "merchant_id": "123"
}

Sort parameters by key alphabetically in ascending order.

{
    "merchant_id": "123",
    "order_id": "DA-A-12345"
}

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

{
    "auth": {
        "appid": 10000001,
        "timestamp": 1665390878,
        "signature": "c6f9dc83a8b8be1b9cdfb63442f0730b"
    },
    "data": {
        "order_id": "DA-A-12345",
        "merchant_id": "123",
        "client": {
            "order_id": "11111111",
            "shipment_code": "22222222"
        },
        "status": {
            "code": "9015",
            "name": "Delivery in progress",
            "lastmodify": "2022-10-10 16:34:38"
        }
    }
}

# Error codes