Zeek Technology

# 開發說明

# 接口類型

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.3 香港、台灣
AP2 https://open-api.ap2-sandbox.zeek.one/v1.3 新加坡、泰國、越南、馬來西亞
  • 我們提供額外開發環境給定製化對接的客戶，詳情請與我們團隊聯絡。

# Release 環境

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

Zone URL Region
AP1 https://ap1-open-api.zeek.one/v1.3 香港、台灣
AP2 https://ap2-open-api.zeek.one/v1.3 新加坡、泰國、越南、馬來西亞

# 數據格式

請求(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.3/order/takeaway/merchants/supported' \
--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,
        "order_id": "FD3165848793513984"
    }
}'

# 接口返回

# 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 繁體中文：zh-HK
英文：en

新加坡

參數 可用值
region 新加坡：SG
lang 英文：en

馬來西亞

參數 可用值
region 吉隆坡： KUL
lang 馬來文：ms
英文：en

泰國

參數 可用值
region 曼谷：BKK
lang 泰文：th
英文：en

越南

參數 可用值
region 胡志明市：SGN
河內：HAN
安江：VNAGG
北寧：VNBNH
平陽：VNBDG
平順：VNBTN
金瓯：VNCMU
芹苴：VNCTO
峴港：VNDNG
多樂：VNDLK
同奈：VNDNI
海防：VNHPG
慶和：VNKHA
堅江：VNKGG
隆安：VNLAN
南定：VNNDH
義安：VNNAN
廣寧：VNQNH
太原：VNTNN
清化：VNTHA
頭頓：VNVTU
太平：VNTBH
廣南：VNQNM
承天順化：VNTTH
西寧：VNTNH
前江：VNTGG
lang 越南文：vi
英文：en

台灣

參數 可用值
region 台北：TPE
lang 繁體中文：zh-TW
英文：en

# 錯誤碼

錯誤碼 說明
261002 timestamp錯誤+具體錯誤的參數（例如：timestamp錯誤請確保timestamp時間與當前時間誤差不超過在180秒)
261003 缺少必要參數+具體錯誤的參數（例如：缺少必要參數 缺少參數timestamp）
261004 請求參數錯誤+具體錯誤的參數（例如：請求參數錯誤 merchant_id不能為空）
261005 重複數據提交,不要在60s內重複提交數據!
261105 redis操作失敗+具體描述（例如：redis操作失敗，商舖信息獲取失敗,商圈或者店鋪不存在）
261103 數據庫操作失敗+具體原因（例如：數據庫創建失敗，創建訂單失敗）
262001 開發者賬號不存在
262002 簽名錯誤
262111 用戶不可以發單+具體錯誤描述（例如：用戶不可以發單，店鋪綁定的appid與開發者不匹配'）
263006 超出配送距離
263001 訂單不存在
263004 訂單已創建
263014 超過最大預約時間
264007 不在店鋪設置的營業時間內+具體描述（例如：不在店鋪設置的營業時間，不在商圈的營業時間內）
264100 商家不存在
264101 商家已達到上限

← 接口列表 →