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

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

# 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
# KS-Lang

Please send the language according to region:

Region KS-Lang value
Hong Kong Traditional Chinese: zh-HK
English: en
Singapore 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

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.

image

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