# 開發說明
# 接口類型
Open API 都是以 HTTPS 協議運作。 接口分為 請求接口 和 回調接口 兩種。
# 請求接口
對接方系統請求 Zeek 平台的接口.
# 回調接口
透過回調接口,Zeek 平台主動向對接方系統推送信息,例如訂單狀態更新。回調接口的URL由開發者提供。
# 規範
- 採用 HTTPS 協議
- 數據編碼採用
UTF-8
Header
的Content-Type
為"application/json"
# API URL
# Sandbox 環境
開發者可以在 Sandbox 環境進行 API 對接及測試。
Zone | URL | Region |
---|---|---|
AP1 | https://open-api.ap1-sandbox.zeek.one/v1.1 | 香港 |
- 我們提供額外開發環境給定製化對接的客戶,詳情請與我們團隊聯絡。
# Release 環境
Release 環境是正式運作的環境。
Zone | URL | Region |
---|---|---|
AP1 | https://ap1-open-api.zeek.one/v1.1 | 香港 |
# 數據格式
請求(request)和返回(response)的數據格式都是 JSON。
# 接口請求
# 請求數據格式
在請求時,在 Request body 需要包括 auth
、data
和 data.meta
字段。
{
"auth":{
"appid":100000001,
"timestamp":1528793155,
"signature":"b7e5162e8ce738ec964c71f54857af32"
},
"data":{
"meta":{
"lang":"zh-HK",
"region":"HK"
},
// 其他數據
}
}
# 系統級參數
在調用所有接口時(包括請求接口和回調接口),開發者都必需傳入以下系統級參數。
參數名稱 | 類型 | 說明 | 備註 |
---|---|---|---|
appid | int | App ID | 由 Zeek 提供 |
signature | string | 簽名 | 用作接口授權,生成方式見授權和簽名 |
timestamp | int | 秒級時間戳 | 例如 1548151468 |
lang | string | 語言 | 參考 參數值列表 |
region | string | 地區 | 參考 參數值列表 |
# 請求例子
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"
},
// 其他接口參數例子
"merchant_id": 123,
"product_code": "HDP-ECOMM-H"
}
}'
# 接口返回
# HTTP 狀態碼
當開發者調用接口後,接收到的 HTTP 狀態碼是 200
時,代表系統已經接收到請求參數,並返回結果。結果會有以下兩種可能性:
1.成功調用,返回所需結果。
2.因為傳入的參數不正確,在 Response body 中返回錯誤碼。
如果是其他錯誤,例如是接口 URL 錯誤的話,系統會依照一般情況返回其他 HTTP 狀態碼,例如是 404
# 返回數據格式
名稱 | 類型 | 說明 | 備註 |
---|---|---|---|
error | int | 錯誤碼 | - 調用成功時返回 0 .- 其他錯誤嗎請參考錯誤碼列表。 |
data | object / array | 返回結果數據 | - 只有在調用成功時返回。 - 請參考各接口的返回數據格式 |
err_msg | string | 錯誤訊息文字 | - 只有在調用失敗時返回。 |
成功調用例子:
{
"error": 0,
"data": {
"order_id": "FD3165848793513984",
"client_order_id": "15104092022333"
}
}
失敗調用例子:
{
"error": 261004,
"err_msg": "Incorrect parameters"
}
# 時區
所有接口請求或返回的時間值,其代表時區都需要和傳入的 region
參數一致。例如當 region="HK"
時,則代表正在傳入 UTC+8 時區的時間值。
# 地理位置座標
座標數據使用的格式是 "緯度,經度",例如 22.285944,114.158177
。
# 授權和簽名
接口授權是透過生成及傳入簽名(Signature)實現。在每次調用接口時,都需要使用請求參數來生成簽名,故此每次請求的簽名都不同。以下將會透過一個例子,說明如何傳入所需參數。
# Step 1. 獲取 App ID 和 App Secret
Zeek 團隊提供 appid
和 secret_key
給開發者。開發者需要使用這兩個參數生成簽名(Signature),用作接口授權,故此,請妥善及保密保管。
參數 | 例子 |
---|---|
appid | 10000001 |
secret_key | da39a3ee5e6b4b0d3255bfef95601890afd80709 |
# Step 2. 生成 request_param_string
假如,原請求數據是
{
"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":""
}
在串接前,先把參數值為非數字和字符串的參數去除。
{
"merchant_id":"457",
"client_order_id":"72755da14c35",
"client_shipment_code":"72755da14c28",
"box_size":3,
"product_name":"Product A",
"remarks":""
}
以數據的鍵名 (key) 按字母升序排列:
{
"box_size":3,
"client_order_id":"72755da14c35",
"client_shipment_code":"72755da14c28",
"merchant_id":"457",
"product_name":"Product A",
"remarks":""
}
把每一個參數鍵(key)和值(value),以=
連接,然後順序以&
連接每一個參數,獲得 request_param_string
:
參數 | 例子 |
---|---|
appid | 10000001 |
secret_key | da39a3ee5e6b4b0d3255bfef95601890afd80709 |
request_param_string | box_size=3&client_order_id=72755da14c35&client_shipment_code=72755da14c28&merchant_id=457 &product_name=Product A&remarks= |
# Step 3. 生成 pre_signature
在 request_param_string
加入 appid
、secret_key
、timestamp
,以 &
連接,生成 pre_signature
:
參數 | 例子 |
---|---|
appid | 10000001 |
secret_key | da39a3ee5e6b4b0d3255bfef95601890afd80709 |
timestamp | 1528793155 |
request_param_string | box_size=3&client_order_id=72755da14c35&client_shipment_code=72755da14c28&merchant_id=457 &product_name=Product A&remarks= |
pre_signature | box_size=3&client_order_id=72755da14c35&client_shipment_code=72755da14c28&merchant_id=457 &product_name=Product A&remarks=&10000001&da39a3ee5e6b4b0d3255bfef95601890afd80709 &1528793155 |
# Step 4. 生成簽名
用 MD5 加密得到 signature
(簽名)
參數 | 例子 |
---|---|
appid | 10000001 |
secret_key | da39a3ee5e6b4b0d3255bfef95601890afd80709 |
timestamp | 1528793155 |
request_param_string | box_size=3&client_order_id=72755da14c35&client_shipment_code=72755da14c28&merchant_id=457 &product_name=Product A&remarks= |
pre_signature | box_size=3&client_order_id=72755da14c35&client_shipment_code=72755da14c28&merchant_id=457 &product_name=Product A&remarks=&10000001&da39a3ee5e6b4b0d3255bfef95601890afd80709 &1528793155 |
signature | d22e6c489d8d4969234fbeb865decd53 |
# Step 5. 把簽名傳入請求參數
注意,以下只是一個請求參數的範例。請根據每個接口格式以傳入參數。
{
"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":""
}
}
# 簽名檢查工具
可以透過以下的工具,檢查生成的簽名步驟是否正確:
Input secret_key :
Input request payload :
# 參數值列表
# region 參數
地區 | 值 |
---|---|
香港 | HK |
# lang 參數
各地區支持語言表:
地區 | lang 參數 |
---|---|
香港 | 繁體中文:zh-HK 英文: en |
# 錯誤碼
錯誤碼 | 說明 |
---|---|
261002 | timestamp錯誤+具體錯誤的參數(例如:timestamp錯誤 請確保timestamp時間與當前時間誤差不超過在180秒) |
261003 | 缺少必要參數+具體錯誤的參數(例如:缺少必要參數 缺少參數timestamp) |
261004 | 請求參數錯誤+具體錯誤的參數(例如:請求參數錯誤 merchant_id不能為空) |
261005 | 重複數據提交,不要在60s內重復提交數據! |
261105 | redis操作失敗+具體描述(例如:redis操作失敗,商鋪信息獲取失敗,商圈或者店鋪不存在) |
261103 | 數據庫操作失敗+具體原因(例如:數據庫創建失敗,創建訂單失敗) |
262001 | 開發者賬號不存在 |
262002 | 簽名錯誤 |
262111 | 用戶不可以發單+具體錯誤描述(例如:用戶不可以發單,你所選擇的寄件時間已超過截單時間,請重新選擇寄件日期或寄件時間。) |
263007 | 物品重量超出上限 |
263006 | 超出配送距離 |
263001 | 訂單不存在 |
263004 | 訂單已創建 |
263014 | 超過最大預約時間 |
264007 | 不在店鋪設置的營業時間內+具體描述(例如:不在店鋪設置的營業時間,不在商圈的營業時間內) |