# 開發說明

# 接口類型

Open API 都是以 HTTPS 協議運作。 接口分為 請求接口回調接口 兩種。

# 請求接口

對接方系統請求 Zeek 平台的接口.

# 回調接口

透過回調接口,Zeek 平台主動向對接方系統推送信息,例如訂單狀態更新。回調接口的URL由開發者提供。

# 規範

  • 採用 HTTPS 協議
  • 數據編碼採用UTF-8
  • HeaderContent-Type"application/json"

# API URL

# Sandbox 環境

開發者可以在 Sandbox 環境進行 API 對接及測試。

Zone URL Region
AP1 https://sandbox-ap1-open-api.zeek.one/v1.1 香港
  • 我們提供額外開發環境給定製化對接的客戶,詳情請與我們團隊聯絡。

# Release 環境

Release 環境是正式運作的環境。

Zone URL Region
AP1 https://ap1-open-api.zeek.one/v1.1 香港

# 數據格式

請求(request)和返回(response)的數據格式都是 JSON。

# 接口請求

# 請求數據格式

在請求時,在 Request body 需要包括 authdatadata.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 語言 參考 lang 參數表
region string 地區 參考 region 參數表
# 請求例子
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 團隊提供 appidsecret_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 加入 appidsecret_keytimestamp,以 & 連接,生成 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 不在店鋪設置的營業時間內+具體描述(例如:不在店鋪設置的營業時間,不在商圈的營業時間內)