# 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.
# 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. |
← ZeekDash List of APIs →