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


# Sandbox environment

Developers can perform API integration and testing on Sandbox environment.

Zone URL Region
AP1 https://open-api.ap1-sandbox.zeek.one/parcel/v1.0 Hong Kong
AP2 https://open-api.ap2-sandbox.zeek.one/parcel/v1.0 Singapore, Thailand, Vietnam, Malaysia
  • 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.

Zone URL Region
AP1 https://ap1-open-api.zeek.one/parcel/v1.0 Hong Kong
AP2 https://ap2-open-api.zeek.one/parcel/v1.0 Singapore, Thailand, Vietnam, Malaysia

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

Region Value
Hong Kong HK
Singapore SG
Vietnam Ho Chi Minh City: SGN
Hanoi: HAN
Malaysia Kuala Lumpur: KUL
Thailand Bangkok: BKK
# KS-Lang

Please send the language according to region:

Region KS-Lang value
Hong Kong Traditional Chinese: zh-HK
English: en
Singapore English: en
Vietnam Vietnamese: vi
English: en
Malaysia Malay: ms
English: en
Thailand Thai: th
English: en
# 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:

Header Example Description
KS-Api-Version 1.0 API version number
KS-Client-Request-Id f058ebd6-02f7-4d3f-942e-904344e8cde5 The KS-Client-Request-Id which is sent in API request.

# Payload 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 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": {
        "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.

Parameter Example
appid 10000001
secret_key da39a3ee5e6b4b0d3255bfef95601890afd80709

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

Parameter Example
appid 10000001
secret_key da39a3ee5e6b4b0d3255bfef95601890afd80709
request_param_string merchant_id=123&order_id=DA-A-12345

# 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 1665390878
request_param_string merchant_id=123&order_id=DA-A-12345
pre_signature merchant_id=123&order_id=DA-A-12345&10000001&da39a3ee5e6b4b0d3255bfef95601890afd80709&1665390878

# Step 4. Generate signature

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

Parameter Example
appid 10000001
secret_key da39a3ee5e6b4b0d3255bfef95601890afd80709
timestamp 1665390878
request_param_string merchant_id=123&order_id=DA-A-12345
pre_signature merchant_id=123&order_id=DA-A-12345&10000001&da39a3ee5e6b4b0d3255bfef95601890afd80709&1665390878
signature c6f9dc83a8b8be1b9cdfb63442f0730b

# 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

Error code Description
400190000001 Invalid request.
400180062 Invalid JSON format.
400120134 Address is empty.
400120131 Invalid phone number.
400120135 Invalid address.
400120037 Longitude is empty.
400120038 Invalid longitude.
400120040 Invalid latitude.
4001128032 Invalid address ID.
400120313 Invalid tips.
4001128083 Invalid COD.
4001128071 Failed to get order details.
4001128090 Position is mandatory.
400190001027 Geolocation is not within supported area.
400190001033 Invalid time type.
400190001042 Failed to pricing. The order does not support the position or region.
400190000002 The task is not supported by the position.
400190001000 The position is not supported by the business.
400190001005 Tips must be greater than zero, if input.
400190001006 Tips must by numerical value.
400190001013 Position is mandatory.
400190001035 Invalid date or time format.
400190001036 Order time cannot be earlier than current time.
400190001031 Invalid item type.
400190001032 Invalid item size.
400190001043 Invalid tunnel.
400190001044 Invalid cancel time format.
400190001020 Starting point is missing.
400190001021 Destination is missing.
4001128003 Invalid starting point address ID.
4001128002 Invalid sender phone number.
4001128005 Invalid sender information.
4001128004 Invalid starting point address.
4001128006 Invalid sender longitude.
4001128007 Invalid sender latitude.
400110062 Invalide country code
4001128009 Invalid destination address ID.
4001128014 Invalid area type.
4001128059 Invalid destination address type.
4001128010 Invalid destination address.
4001128012 Invalid recipient longitude.
4001128013 Invalid recipient latitude.
4001128011 Invalid recipient information.
4001128008 Invalid recipient phone number.
400110062 Invalid country code.
400190001052 XL item needs "Meet at G/F", cannot choose "Without elevator" option.
400190001045 Invalid tunnel code.
400193000001 Contact name is empty.
400193000002 Contact phone is empty.
400193000005 System busy.
400193000006 System busy.
400193000008 Invalid VAS
400193000009 VAS is not supported due to out of area.
400193000022 Designated cancel order time must within 24 hours of order dispatch time
4001340000 Invalid parameter.
400120217 Invalid parameter.
4001260300 Invalid parameter.
4001280009 Temp order is not existed.
400120212 Failed to save order.
400180070 Reason for resubmit order is missing.
4001260300 Invalid parameter.
4001260061 Please do not resubmit order.
400120212 Failed to save order.
400180056 Order not found.
40011 Please login again.
400180062 Invalid JSON format.
4001310001 Invalid business ID.
4001310002 Invalid product code.
400120134 Address is empty.
400190001032 Invalid item size.
50006 Token decode failed.
40001 Invalid parameters
40101 Unauthorized (Invalide access_token, merchant_id, client_id or client_secret)
40301 Access token is expired
40302 THe merchant_id is not authorized
40303 You can only create or cancel the same order once in 60sec
50001 Internal server error
50002 Internal server error
50003 Internal server error
50004 Internal server error
50005 Internal server error
50006 Internal server error