首頁 / API 對接文件

API 對接文件

版本 v1 · 適用於代理商和開發者

透過介面可以用程式在本站下單、查詢訂單和取得兌換碼。下單金額直接從帳戶餘額扣除,不需要逐筆付款。

  1. 註冊帳號,在 會員中心 儲值餘額。
  2. 在 會員中心 → API 介面 建立金鑰,取得 AppID 和 Secret,建議同時設定 IP 白名單。
  3. 請按下面的簽章方式呼叫介面。
介面網址https://vynqlo.com/api/open/v1
資料格式請求和回傳都是 JSON,編碼 UTF-8
金額單位人民幣元,最多兩位小數
呼叫頻率每個金鑰每秒最多 10 次,超出會回傳 429

簽章方式

每個請求都要帶上下面 4 個請求標頭:

請求標頭說明
X-App-Id你的 AppID
X-Timestamp目前的 Unix 時間戳(秒),和伺服器相差不能超過 300 秒
X-Nonce隨機字串,16–32 位,同一個值 10 分鐘內不能重複使用
X-Sign簽章,計算方法見下

把下面 5 項用換行符號 \n 連起來,得到待簽章字串:

時間戳\n隨機字串\n請求方法(大寫)\n請求路徑(含查詢參數)\n請求本文原文(GET 請求為空字串)

再用 Secret 做 HMAC-SHA256,結果轉成小寫十六進位,就是 X-Sign。

Python 範例

import hmac, hashlib, json, time, secrets, requests APP_ID = "vq_xxxxxxxxxxxxxxxx" SECRET = "你的 Secret" BASE = "https://vynqlo.com/api/open/v1" def call(method, path, body=None): raw = json.dumps(body, ensure_ascii=False, separators=(",", ":")) if body else "" ts, nonce = str(int(time.time())), secrets.token_hex(8) msg = "\n".join([ts, nonce, method, "/api/open/v1" + path, raw]) sign = hmac.new(SECRET.encode(), msg.encode(), hashlib.sha256).hexdigest() headers = {"X-App-Id": APP_ID, "X-Timestamp": ts, "X-Nonce": nonce, "X-Sign": sign, "Content-Type": "application/json"} return requests.request(method, BASE + path, headers=headers, data=raw.encode() or None).json() print(call("GET", "/balance"))

商品列表

GET /products — 回傳所有可下單的商品、你的進貨價和庫存。

{ "code": 0, "data": [ { "sku": "apple.us.25", "name": "Apple 禮品卡 · 美國 $25", "delivery": "code", // code 兌換碼 / link 連結代付 / username 用戶名稱直儲 "price": 189.00, "stock": 167, // 連結代付、用戶名稱直儲的商品為 null,表示不限 "fields": [] // 下單時需要額外提交的欄位,見「建立訂單」 } ] }

查詢餘額

GET /balance

{ "code": 0, "data": { "balance": 2380.50 } }

建立訂單

POST /orders — 餘額足夠時立即扣款並開始處理。

參數必填說明
sku是商品編碼,見文末「商品編碼表」
quantity否數量,預設 1。兌換碼商品每單最多 10,其他商品只能為 1
out_trade_no是你自己系統的訂單號,6–64 位英數字。同一個單號重複提交會直接回傳既有訂單,不會重複扣款
account_email連結代付必填顧客的帳號信箱
checkout_url連結代付必填官方結帳連結
username用戶名稱直儲必填例如 Telegram 使用者名稱 @name

請求範例:

{ "sku": "chatgpt.plus.1m", "out_trade_no": "A20261119001",
  "account_email": "user@example.com",
  "checkout_url": "https://chatgpt.com/checkout/..." }

回傳範例:

{
  "code": 0,
  "data": {
    "order_no": "VQ2611190001",
    "out_trade_no": "A20261119001",
    "status": "processing",
    "amount": 169.00,
    "balance": 2211.50
  }
}

查詢訂單

GET /orders/{order_no},或 GET /orders?out_trade_no=你的單號

{
  "code": 0,
  "data": {
    "order_no": "VQ2611190002",
    "out_trade_no": "A20261119002",
    "sku": "apple.us.25",
    "quantity": 2,
    "amount": 378.00,
    "status": "delivered",
    "cards": ["XXXX-XXXX-XXXX-XXXX", "YYYY-YYYY-YYYY-YYYY"],
    "created_at": 1795060000,
    "finished_at": 1795060003,
    "remark": ""
  }
}
status含義
processing已扣款,處理中(代付、直儲訂單通常 5–30 分鐘)
delivered兌換碼已發放,請在 cards 裡
completed代付或直儲已完成
failed處理失敗,金額已退回餘額,原因見 remark

回呼通知

在會員中心設定回呼網址後,訂單變為 delivered、completed 或 failed 時,我們會 POST 訂單資料到這個網址,內容和「查詢訂單」回傳的 data 一樣。

  • 通知同樣帶 X-App-Id、X-Timestamp、X-Nonce、X-Sign,簽章方法相同,請先驗章再處理。
  • 處理成功後回傳 HTTP 200 和文字 success。否則會在 1、5、15、60 分鐘後重試,最多 4 次。
  • 同一筆訂單可能會收到多次通知,請依 order_no 去重。

錯誤碼

code說明
0成功
1001簽章錯誤,或缺少請求標頭
1002時間戳超出允許範圍
1003隨機字串重複使用
1004IP 不在白名單內
2001商品編碼不存在或已下架
2002庫存不足
2003缺少必填欄位,或欄位格式不正確
3001餘額不足
4001訂單不存在
429呼叫太頻繁

出錯時的回傳格式:{ "code": 3001, "message": "餘額不足" }

商品編碼表

價格為目前的進貨價,以 /products 介面回傳為準。

編碼 sku商品交付方式價格