# 開發說明

# 接口類型

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

# 請求接口

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

# 回調接口

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

# 規範

• 採用 HTTPS 協議
• 數據編碼採用UTF-8
• 接口請求 (API request) 和返回 (API response) 的 Payload 數據格式都是 JSON。

# API URL

# Sandbox 環境

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

• 我們提供額外開發環境給定製化對接的客戶，詳情請與我們團隊聯絡。

# Release 環境

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

# API Request

接口請求 (API request) 的 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

在接口請求 (API request) 時，需要傳入以下的 HTTP Header。

# Content-Type

請傳入 application/json;charset=UTF-8，所有接口請求都是以 UTF-8 編碼及 JSON 格式進行

# Authorization

在請求接口時，需要在 Authorization header 傳入 access token，才能獲得 Zeek 平台授權使用該接口。請參考 接口授權。

# KS-Region

傳入使用服務的地區：

# KS-Lang

請根據地區傳入語言：

# KS-Client-Request-Id

在每次請求時，建議開發都傳入一個 UUID 到 KS-Client-Request-Id Header, 方便在測試排查時，讓開發者和 Zeek 團隊辨認正在請求的是哪一個。 UUID 的例子是 f058ebd6-02f7-4d3f-942e-904344e8cde5。

# API Response

# HTTP 狀態碼

接口返回 (HTTP response) 時，會使用以下 HTTP 狀態碼，反饋接口請求結果：

• 200 OK
• 400 Bad Request
• 401 Unauthorized
• 403 Forbidden
• 404 Not Found
• 500 Internal Server Error

# HTTP Header

在接口返回包括以下的 HTTP header：

# Payload 格式

成功調用例子：

{
    "error": 0,
    "data": {
        "token_type": "Bearer",
        "access_token": "xxxxxxxxxxxxxxxxxxxxxxx",
        "expires_in": 86400,
        "scope": "delivery"
    }
}

失敗調用例子：

{
    "error": 261004,
    "err_msg": "Incorrect parameters"
}

# 時區

所有接口請求或返回的時間值，其代表時區都需要和傳入的 region 參數一致。例如當 region="HK" 時，則代表正在傳入 UTC+8 時區的時間值。

# 地理位置座標

座標數據使用的格式是 "緯度,經度"，例如 22.285944,114.158177。

# 接口授權

# API請求

Open API 使用 OAuth 的 Client credentials flow 進行接口授權。當中涉及以下幾步：

• 第 1 步：開發者從 Zeek 團隊獲得 AppId 和 AppSecret 。
• 第 2 步：對接方系統調用 PA-API-1.1 獲取 Access Token 接口 以 AppId 和 AppSecret 獲取 Access token。Access token 的有效為 24 小時。
• 第 3 步：開發者在請求其他接口時，在 HTTP Header 加上 Authorization: Bearer [Access token]，Zeek 平台會利用 Access token 認證授權。

# 訂單狀態回調

訂單狀態回調是透過生成及傳入簽名(Signature)實現。訂單狀態回調時，都會使用請求參數來生成簽名，故此每次請求的簽名都不同。以下將會透過一個例子，說明如何傳入所需參數。

# Step 1. 獲取 App ID 和 App Secret

Zeek 團隊提供 appid 和 secret_key 給開發者，並將使用這兩個參數生成簽名(Signature)，用作接口授權，故此，請妥善及保密保管。

# Step 2. 生成 request_param_string

假如，原請求數據是

{
    "order_id": "DA-A-12345",
    "merchant_id": "123",
    "client": {
        "order_id": "11111111",
        "shipment_code": "22222222"
    },
    "status": {
        "code": "9015",
        "name": "Delivery in progress",
        "lastmodify": "2022-10-10 16:34:38"
        }
}

在串接前，先把參數值為非數字和字符串的參數去除。

{
    "order_id": "DA-A-12345",
    "merchant_id": "123"
}

以數據的鍵名 (key) 按字母升序排列：

{
    "merchant_id": "123",
    "order_id": "DA-A-12345"
}

把每一個參數鍵(key)和值(value)，以=連接，然後順序以&連接每一個參數，獲得 request_param_string：

# Step 3. 生成 pre_signature

在 request_param_string 加入 appid、secret_key、timestamp，以 & 連接，生成 pre_signature:

# Step 4. 生成簽名

用 MD5 加密得到 signature (簽名)

# Step 5. 把簽名傳入請求參數

{
    "auth": {
        "appid": 10000001,
        "timestamp": 1665390878,
        "signature": "c6f9dc83a8b8be1b9cdfb63442f0730b"
    },
    "data": {
        "order_id": "DA-A-12345",
        "merchant_id": "123",
        "client": {
            "order_id": "11111111",
            "shipment_code": "22222222"
        },
        "status": {
            "code": "9015",
            "name": "Delivery in progress",
            "lastmodify": "2022-10-10 16:34:38"
        }
    }
}

# 錯誤碼