# 餘額自動下單 API 接口文件

版本：`v2.1`  
更新時間：`2026-10-14`  
生產地址：`https://98-xj.com`  
結算幣種：以接口回傳的 `currency` 為準，目前為 `CNY`

[简体中文](/docs/cardnet-upstream-api-v2.zh-CN.md) | [繁體中文](/docs/cardnet-upstream-api-v2.zh-TW.md) | [English](/docs/cardnet-upstream-api-v2.en-US.md) | [Tiếng Việt](/docs/cardnet-upstream-api-v2.vi-VN.md) | [Русский](/docs/cardnet-upstream-api-v2.ru-RU.md) | [Türkçe](/docs/cardnet-upstream-api-v2.tr-TR.md)

## 1. 接入說明

本接口供已審核通過並啟用 API 憑證的客戶使用。

- 客戶需要先在本站儲值錢包餘額。
- 下單時從錢包餘額立即扣款。
- 僅支援自動發貨商品與 `wallet` 餘額支付。
- 不回傳支付連結或 USDT 收款地址。
- 下單、扣款、庫存占用、錢包流水、訂單建立與自動發貨為同一交易；任一步失敗均不會產生半成品訂單或單獨扣款。
- 建立訂單成功後，透過訂單查詢接口讀取卡密。
- API Key 與 API Secret 必須只保存在伺服器端，不可放入網頁、App 前端或公開儲存庫。

平台向客戶提供：

```text
API_BASE_URL=https://98-xj.com
API_KEY=<平台提供>
API_SECRET=<平台提供>
```

> **重要：API Secret 必須依照頁面顯示的完整原文作為 UTF-8 字串使用。**  
> 目前 Secret 即使看起來像 128 位十六進位文字，也不要做 hex 解碼、Base64 解碼或大小寫轉換。解碼成 64 位元組後再做 HMAC 會得到錯誤簽名。API Key 與 API Secret 必須來自同一份憑證；重新生成 Secret 後舊 Secret 立即失效。

### 1.1 憑證安全

- **生成或重新生成 Secret 需要二次驗證**：在個人中心「API 對接」操作時，必須輸入目前登入密碼；已開啟兩步驗證的帳號還要輸入動態碼。未設定過登入密碼的帳號（例如 Telegram 自動註冊）需先在「安全中心」設定密碼。
- **修改或找回登入密碼會作廢 Secret**：密碼變更後，舊 API Secret 立即失效，所有請求回傳 `401 authentication_failed`。請登入個人中心重新生成，並同步更新伺服器設定。
- **IP 白名單（強烈建議開啟）**：個人中心「API 對接 → IP 白名單」可自助設定允許呼叫的來源 IP。每行一個 IP 或 CIDR（如 `203.0.113.10` 或 `203.0.113.0/24`），最多 20 條，不能填寫 `0.0.0.0/0`。保存同樣需要二次驗證，立即生效。來源 IP 不在白名單時回傳 `403 authentication_failed`；留空表示不限制。請填寫伺服器的固定出口 IP，Key 與 Secret 即使洩漏也無法在其他地方使用。
- **敏感操作限頻**：同一帳號 10 分鐘內最多 10 次生成 Secret 或修改白名單，超出後暫停 15 分鐘。

## 2. 接口列表

| 方法 | 路徑 | 用途 |
| --- | --- | --- |
| `POST` | `/api/v1/upstream/ping` | 測試憑證並查詢錢包餘額 |
| `GET` | `/api/v1/upstream/categories` | 查詢商品分類 |
| `GET` | `/api/v1/upstream/products` | 查詢商品列表 |
| `GET` | `/api/v1/upstream/products/:id` | 查詢單個商品 |
| `POST` | `/api/v1/upstream/orders` | 餘額下單 |
| `GET` | `/api/v1/upstream/orders/:id` | 查詢訂單與卡密 |
| `POST` | `/api/v1/upstream/orders/:id/cancel` | 取消可取消的訂單 |

所有憑證都只接受下述 HMAC-SHA256 v2 簽名；缺少 nonce 的舊版三段簽名一律回傳 `401 authentication_failed`。

## 3. 請求簽名

### 3.1 必填請求標頭

| Header | 說明 |
| --- | --- |
| `Dujiao-Next-Api-Key` | 平台提供的 API Key |
| `Dujiao-Next-Timestamp` | 目前 Unix 秒時間戳 |
| `Dujiao-Next-Nonce` | 本次請求唯一的隨機字串，建議 UUID v4 |
| `Dujiao-Next-Signature` | HMAC-SHA256 簽名，小寫十六進位 |

有 JSON 請求內容時同時傳送：

```http
Content-Type: application/json
```

### 3.2 待簽名字串

```text
METHOD\nPATH\nTIMESTAMP\nNONCE\nSHA256(RAW_BODY)
```

計算規則：

1. `METHOD`：大寫 HTTP 方法，例如 `GET`、`POST`。
2. `PATH`：只包含 URL 路徑，不包含網域、查詢參數或 `#fragment`。
3. `TIMESTAMP`：與請求標頭完全相同的 Unix 秒時間戳。
4. `NONCE`：與請求標頭完全相同的隨機字串。
5. `SHA256(RAW_BODY)`：實際傳送 body 原始位元組的 SHA-256 小寫十六進位。
6. 五段之間使用一個換行符 `\n`，末尾不添加換行。
7. 最終簽名：

```text
hex_lower(HMAC_SHA256(API_SECRET, canonical_string))
```

GET 請求與沒有請求內容的 POST 請求，`RAW_BODY` 使用空位元組串：

```text
SHA256("") = e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855
```

注意：

- 伺服器時間允許誤差為前後 `60` 秒，客戶伺服器必須保持時間同步。
- 每個請求必須使用新的 `nonce`，網路重試也不能複用舊 nonce。
- 簽名成功後不能再修改 JSON 的空格、欄位順序、編碼或換行。
- 查詢參數不參與簽名，但路徑必須參與簽名。
- 請求不能使用 gzip 等壓縮編碼。
- 單個請求內容最大 `65,536` 位元組。
- `API_SECRET` 直接執行 UTF-8 編碼後作為 HMAC key；不要把看似十六進位的 Secret 解碼成二進位。
- API Key 與 Secret 必須成對使用；Secret 輪換後必須原子更新客戶端設定並重啟/熱載入呼叫程序。

### 3.3 固定測試向量

正式請求生產接口前，客戶端必須先通過以下離線測試向量。這裡的 Secret 是公開測試值，不可用於生產：

```text
API_SECRET = 0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef
METHOD     = POST
PATH       = /api/v1/upstream/ping
TIMESTAMP  = 1709625600
NONCE      = 550e8400-e29b-41d4-a716-446655440000
RAW_BODY   = 空位元組串
BODY_HASH  = e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855
SIGNATURE  = 09cf5cedb04ba4b32552c7e9d8c533368eeb48dd9ba1b72fd1e2c151e9487819
```

如果本地計算結果不是上述 `SIGNATURE`，不要請求生產接口。優先檢查：Secret 是否被 hex/Base64 解碼、換行是否為 `\n`、末尾是否多了換行、PATH 是否混入網域或查詢參數。

### 3.4 Python 簽名與請求範例

相依套件：

```bash
pip install requests
```

範例：

```python
import hashlib
import hmac
import json
import os
import time
import uuid
from urllib.parse import urlencode

import requests

BASE_URL = "https://98-xj.com"
API_KEY = os.environ["CARDNET_API_KEY"]
API_SECRET = os.environ["CARDNET_API_SECRET"]


def api_request(method, path, *, query=None, payload=None, timeout=15):
    method = method.upper()
    raw_body = b""
    if payload is not None:
        raw_body = json.dumps(
            payload,
            ensure_ascii=False,
            separators=(",", ":"),
        ).encode("utf-8")

    timestamp = int(time.time())
    nonce = str(uuid.uuid4())
    body_hash = hashlib.sha256(raw_body).hexdigest()
    canonical = (
        f"{method}\n{path}\n{timestamp}\n{nonce}\n{body_hash}"
    ).encode("utf-8")
    signature = hmac.new(
        API_SECRET.encode("utf-8"),
        canonical,
        hashlib.sha256,
    ).hexdigest()

    headers = {
        "Dujiao-Next-Api-Key": API_KEY,
        "Dujiao-Next-Timestamp": str(timestamp),
        "Dujiao-Next-Nonce": nonce,
        "Dujiao-Next-Signature": signature,
    }
    if payload is not None:
        headers["Content-Type"] = "application/json"

    url = BASE_URL + path
    if query:
        url += "?" + urlencode(query)

    response = requests.request(
        method,
        url,
        data=raw_body if payload is not None else None,
        headers=headers,
        timeout=timeout,
    )
    return response.status_code, response.json()


# 測試憑證和餘額
status, result = api_request("POST", "/api/v1/upstream/ping")
print(status, result)

# 建立訂單
status, result = api_request(
    "POST",
    "/api/v1/upstream/orders",
    payload={
        "sku_id": 123,
        "quantity": 1,
        "downstream_order_no": "merchant-20260718-0001",
        "payment_mode": "wallet",
    },
)
print(status, result)

# 查詢訂單和卡密
if result.get("order_id"):
    order_id = result["order_id"]
    status, detail = api_request(
        "GET",
        f"/api/v1/upstream/orders/{order_id}",
    )
    print(status, detail)
```

### 3.5 Node.js 簽名範例

適用於 Node.js 18 及以上版本。`API_SECRET` 直接作為 UTF-8 文字傳給 HMAC：

```javascript
import crypto from "node:crypto";

function signV2(secret, method, path, timestamp, nonce, rawBody = Buffer.alloc(0)) {
  const bodyHash = crypto.createHash("sha256").update(rawBody).digest("hex");
  const canonical = `${method.toUpperCase()}\n${path}\n${timestamp}\n${nonce}\n${bodyHash}`;
  return crypto.createHmac("sha256", Buffer.from(secret, "utf8"))
    .update(Buffer.from(canonical, "utf8"))
    .digest("hex");
}

const method = "POST";
const path = "/api/v1/upstream/ping";
const timestamp = Math.floor(Date.now() / 1000);
const nonce = crypto.randomUUID();
const rawBody = Buffer.alloc(0);
const signature = signV2(
  process.env.CARDNET_API_SECRET,
  method,
  path,
  timestamp,
  nonce,
  rawBody,
);

const response = await fetch(`https://98-xj.com${path}`, {
  method,
  headers: {
    "Dujiao-Next-Api-Key": process.env.CARDNET_API_KEY,
    "Dujiao-Next-Timestamp": String(timestamp),
    "Dujiao-Next-Nonce": nonce,
    "Dujiao-Next-Signature": signature,
  },
});
console.log(response.status, await response.json());
```

### 3.6 Go 簽名範例

```go
package main

import (
	"crypto/hmac"
	"crypto/sha256"
	"encoding/hex"
	"fmt"
	"strings"
)

func signV2(secret, method, path, timestamp, nonce string, rawBody []byte) string {
	bodyHash := sha256.Sum256(rawBody)
	canonical := strings.Join([]string{
		strings.ToUpper(method),
		path,
		timestamp,
		nonce,
		hex.EncodeToString(bodyHash[:]),
	}, "\n")
	mac := hmac.New(sha256.New, []byte(secret)) // Secret 原始 UTF-8 位元組
	_, _ = mac.Write([]byte(canonical))
	return fmt.Sprintf("%x", mac.Sum(nil))
}
```

## 4. 測試憑證與查詢餘額

```http
POST /api/v1/upstream/ping
```

請求內容為空。

成功回應：

```json
{
  "ok": true,
  "site_name": "站點名稱",
  "protocol_version": "1.0",
  "user_id": 1001,
  "balance": "500.00",
  "currency": "CNY",
  "member_level": null
}
```

`balance` 是目前已入帳可用餘額。下單前應先檢查餘額，但最終是否扣款成功以建立訂單回應為準。

## 5. 查詢商品分類

```http
GET /api/v1/upstream/categories
```

成功回應：

```json
{
  "ok": true,
  "categories": [
    {
      "id": 1,
      "parent_id": 0,
      "slug": "example",
      "name": {
        "zh-CN": "示例分類"
      },
      "icon": "",
      "sort_order": 0
    }
  ]
}
```

## 6. 查詢商品

### 6.1 商品列表

```http
GET /api/v1/upstream/products?page=1&page_size=50
```

查詢參數：

| 參數 | 必填 | 說明 |
| --- | --- | --- |
| `page` | 否 | 頁碼，預設 `1` |
| `page_size` | 否 | 每頁數量，預設及最大 `50` |
| `include_inactive` | 否 | `true` 時包含已下架商品 |
| `updated_after` | 否 | RFC3339 時間，例如 `2026-07-18T00:00:00Z` |

成功回應結構：

```json
{
  "ok": true,
  "items": [
    {
      "id": 10,
      "slug": "example-product",
      "title": {
        "zh-CN": "示例商品"
      },
      "price_amount": "20.00",
      "fulfillment_type": "auto",
      "is_active": true,
      "category_id": 1,
      "wholesale_prices": [
        {
          "min_quantity": 10,
          "unit_price": "18.00"
        }
      ],
      "skus": [
        {
          "id": 123,
          "sku_code": "SKU-001",
          "spec_values": {},
          "price_amount": "20.00",
          "stock_status": "in_stock",
          "stock_quantity": 50,
          "is_active": true
        }
      ],
      "created_at": "2026-07-18T00:00:00Z",
      "updated_at": "2026-07-18T00:00:00Z"
    }
  ],
  "total": 1,
  "page": 1,
  "page_size": 50,
  "includes_inactive": false
}
```

庫存狀態：

| `stock_status` | 說明 |
| --- | --- |
| `in_stock` | 庫存正常 |
| `low_stock` | 庫存較少 |
| `out_of_stock` | 無庫存 |
| `unlimited` | 無限庫存，`stock_quantity` 為 `-1` |

餘額 API 下單只支援 `fulfillment_type=auto` 的可用自動發貨 SKU。實際價格、購買限制與庫存會在下單交易內重新校驗，建立訂單回傳的 `amount` 才是最終成交金額。

### 6.2 單個商品

```http
GET /api/v1/upstream/products/10
```

成功回應：

```json
{
  "ok": true,
  "product": {
    "id": 10,
    "title": {
      "zh-CN": "示例商品"
    },
    "price_amount": "20.00",
    "fulfillment_type": "auto",
    "is_active": true,
    "skus": [
      {
        "id": 123,
        "sku_code": "SKU-001",
        "price_amount": "20.00",
        "stock_status": "in_stock",
        "stock_quantity": 50,
        "is_active": true
      }
    ]
  }
}
```

## 7. 建立餘額訂單

```http
POST /api/v1/upstream/orders
Content-Type: application/json
```

請求欄位：

| 欄位 | 必填 | 說明 |
| --- | --- | --- |
| `sku_id` | 是 | 商品接口回傳的 SKU ID |
| `quantity` | 是 | 正整數，目前接口上限 `100`，並受商品自身限制 |
| `downstream_order_no` | 是 | 客戶自己的唯一訂單號，同時作為冪等鍵 |
| `payment_mode` | 否 | 只能省略、傳 `null` 或傳 `"wallet"` |
| `trace_id` | 否 | 客戶鏈路追蹤號 |
| `callback_url` | 否 | 目前不支援；只能省略、傳 `null` 或空字串 |
| `manual_form_data` | 否 | 目前不支援；只能省略、傳 `null` 或空物件 `{}` |

`downstream_order_no` 與非空 `trace_id` 必須滿足：

```regex
^[A-Za-z0-9][A-Za-z0-9._:-]{0,63}$
```

建議請求內容：

```json
{
  "sku_id": 123,
  "quantity": 2,
  "downstream_order_no": "merchant-20260718-0001",
  "payment_mode": "wallet",
  "trace_id": "trace-20260718-0001"
}
```

成功回應：

```json
{
  "ok": true,
  "order_id": 456,
  "order_no": "EXAMPLE-ORDER-NO",
  "status": "completed",
  "amount": "40.00",
  "currency": "CNY",
  "downstream_order_no": "merchant-20260718-0001",
  "trace_id": "trace-20260718-0001"
}
```

建立接口不直接回傳卡密。收到成功回應後，使用 `order_id` 查詢訂單詳情。

### 7.1 冪等規則

冪等範圍為：

```text
(目前 API 憑證, downstream_order_no)
```

- 同一個 `downstream_order_no`，且 `sku_id`、`quantity` 相同：回傳原訂單，不會重複扣款或重複占用庫存。
- 同一個 `downstream_order_no`，但 `sku_id` 或 `quantity` 不同：回傳 `idempotency_conflict`。
- `payment_mode` 省略、`null`、`wallet` 三種寫法等價。
- 網路逾時或 5xx 導致結果不確定時，必須使用原 `downstream_order_no` 與原業務參數重試，但每次都要生成新的 timestamp、nonce 與簽名。
- 不要因為第一次回應逾時就更換 `downstream_order_no`，否則可能建立第二筆真實訂單。

## 8. 查詢訂單與卡密

```http
GET /api/v1/upstream/orders/456
```

成功回應：

```json
{
  "ok": true,
  "order_id": 456,
  "order_no": "EXAMPLE-ORDER-NO",
  "status": "completed",
  "amount": "40.00",
  "refunded_amount": "0.00",
  "currency": "CNY",
  "refund_records": [],
  "items": [
    {
      "product_id": 10,
      "sku_id": 123,
      "title": {
        "zh-CN": "示例商品"
      },
      "quantity": 2,
      "unit_price": "20.00",
      "total_price": "40.00",
      "fulfillment_type": "auto"
    }
  ],
  "fulfillment": {
    "type": "auto",
    "status": "delivered",
    "payload": "<卡密內容>",
    "delivery_data": {},
    "delivered_at": "2026-07-18T00:00:00Z"
  }
}
```

`fulfillment.payload` 與 `fulfillment.delivery_data` 可能包含卡密，必須按敏感資料處理：

- 只透過 HTTPS 傳輸。
- 不可寫入一般存取日誌、錯誤日誌或監控標籤。
- 不可回傳給無權限使用者。

常見訂單狀態：

| 狀態 | 說明 |
| --- | --- |
| `paid` | 已付款 |
| `fulfilling` | 發貨處理中 |
| `partially_delivered` | 部分發貨 |
| `delivered` | 已發貨 |
| `completed` | 已完成 |
| `partially_refunded` | 部分退款 |
| `refunded` | 已退款 |
| `canceled` | 已取消 |

正常的餘額自動卡密訂單通常會直接回傳 `completed`。

## 9. 取消訂單

```http
POST /api/v1/upstream/orders/456/cancel
```

請求內容為空。

成功回應：

```json
{
  "ok": true,
  "order_id": 456,
  "order_no": "EXAMPLE-ORDER-NO",
  "status": "canceled"
}
```

已自動發貨或已完成的訂單通常不能取消，會回傳 `cancel_not_allowed`。

## 10. 錯誤回應

統一錯誤結構：

```json
{
  "ok": false,
  "error_code": "invalid_request",
  "error_message": "request rejected"
}
```

客戶端應根據 HTTP 狀態碼與 `error_code` 處理，不要依賴 `error_message` 文字。

| HTTP | `error_code` | 含義與處理 |
| --- | --- | --- |
| `400` | `bad_request` | 路徑參數格式錯誤（如訂單 ID、商品 ID 不是純數字），修正後再請求 |
| `400` | `invalid_request` | JSON 格式、欄位名、欄位類型或取值不合法（含未知欄位、`downstream_order_no` 格式不符） |
| `400` | `payment_mode_not_supported` | `payment_mode` 只能省略、傳 `null` 或 `"wallet"` |
| `400` | `callback_not_supported` | `callback_url` 只能省略、傳 `null` 或空字串 |
| `400` | `product_not_supported` | SKU 不存在、已下架、不是自動發貨，或數量不滿足購買限制；更換 SKU 或調整數量 |
| `401` | `authentication_failed` | 鑑權失敗統一回傳此碼：缺少請求標頭、API Key 無效或已停用、帳號停用、簽名錯誤、時間戳超出 ±60 秒或不是秒級整數、缺少 nonce、Secret 已因改密作廢等。暫停自動請求並告警，逐項核對後手工重試一次 `/ping` |
| `403` | `authentication_failed` | 簽名正確，但來源 IP 不在該憑證的 IP 白名單內；核對伺服器出口 IP，或在個人中心更新白名單 |
| `403` | `wallet_order_not_enabled` | 該憑證未開通餘額下單權限，聯絡平台 |
| `403` | `member_level_required` | 該商品僅限指定會員等級購買 |
| `403` | `credential_paused` | 該憑證的 API 呼叫已被暫停，聯絡平台 |
| `404` | `product_not_found` | 商品不存在 |
| `404` | `order_not_found` | 訂單不存在或不屬於目前帳號 |
| `409` | `replay_detected` | nonce 已被使用；生成新的 nonce 重新簽名，業務參數保持不變 |
| `409` | `idempotency_conflict` | 同一個 `downstream_order_no` 綁定了不同的商品或數量，停止自動重試 |
| `409` | `insufficient_balance` | 錢包餘額不足；先儲值並確認已入帳 |
| `409` | `insufficient_stock` | 庫存不足；更換商品、減少數量或稍後重試 |
| `409` | `cancel_not_allowed` | 目前訂單狀態不允許取消 |
| `413` | `invalid_request` | 請求內容超過 `65,536` 位元組 |
| `415` | `invalid_request` | 請求使用了 gzip 等壓縮編碼 |
| `429` | `rate_limited` | 超出頻率限制；按 `Retry-After`（如有）退避，再用新的 timestamp、nonce 與簽名重試 |
| `500` | `internal_error` | 查詢類接口內部錯誤；退避後重試 |
| `503` | `service_unavailable` | 服務暫時不可用或併發已滿；保持原冪等參數，退避後用新簽名重試 |

> `401` 與 `403` 表示憑證、簽名或帳號設定問題，客戶端必須暫停自動請求並告警。修正設定後只允許先手工重試一次 `/ping`，不要對鑑權失敗進行無限重試。

## 11. 呼叫頻率與重試

- 單個憑證總請求上限為 `60 次/分鐘`，超限後封鎖 `30` 秒，期間回傳 `429 rate_limited`。
- 同一來源 IP 在鑑權前的請求上限為 `120 次/分鐘`，超限後封鎖 `5` 分鐘。
- 建立、取消等寫請求併發不超過 `2`，查詢請求併發不超過 `8`；超出時回傳 `503 service_unavailable`。
- 建立訂單建議控制在 `5 次/10 秒`以內。
- 只有 `429`、`503` 與網路逾時可使用指數退避，例如 `1、2、4、8` 秒。
- `401`、`403` 必須立即暫停自動呼叫並告警，禁止自動重試，避免錯誤設定形成請求風暴。
- 重試建立訂單時保持同一個 `downstream_order_no`、`sku_id` 與 `quantity`，但必須生成新的 timestamp、nonce 與簽名。
- `insufficient_balance`、`insufficient_stock`、`sku_unavailable`、`product_unavailable`、`idempotency_conflict` 不應盲目重試。

## 12. 上線前檢查

客戶正式接入前應確認：

1. API 憑證已經審核通過並啟用。
2. API Key 是後台顯示的 64 位 Key，API Secret 是生成時顯示的完整 128 位原文。
3. 固定離線測試向量已通過，確認 Secret 未進行 hex/Base64 解碼。
4. `POST /api/v1/upstream/ping` 回傳 `ok=true`。
5. 錢包 `balance` 足夠支付測試訂單。
6. 客戶伺服器時間已同步。
7. API Secret 只保存在伺服器端環境變數或密鑰管理系統。
8. 使用真實傳送的原始 body 計算簽名。
9. 建立訂單已實現 `downstream_order_no` 冪等重試。
10. 客戶端不會自動重試 `401`、`403`，且卡密不會進入一般日誌。
11. 已在個人中心設定 IP 白名單，只包含伺服器的固定出口 IP（建議）。
12. 修改登入密碼或重新生成 Secret 後，有流程同步更新伺服器上的 Secret。

## 13. 更新記錄

### 2026-10-14 · v2.1

- 新增「1.1 憑證安全」：生成或重新生成 Secret 需要二次驗證；修改或找回登入密碼會作廢 Secret；可自助設定 IP 白名單。
- 錯誤碼表按實際回傳重寫：鑑權失敗統一為 `401 authentication_failed`，IP 不在白名單為 `403 authentication_failed`，餘額不足為 `409 insufficient_balance`；補充 `member_level_required`、`wallet_order_not_enabled`、`credential_paused`、`product_not_found`、`internal_error`。
- 頻率限制補充封鎖時長與按 IP 的限制。
- 新增越南語、俄語、土耳其語版本。

### 2026-08-27 · v2.0

- 明確 HMAC-SHA256 v2 的五段 canonical 格式。
- 明確 128 位 API Secret 按 UTF-8 原文使用，禁止 hex/Base64 解碼。
- 增加可離線驗證的固定測試向量以及 Python、Node.js、Go 範例。
- 補齊實際鑑權錯誤碼，並規定 `401`、`403` 禁止自動重試。
