API 對接文件
透過介面可以用程式在本站下單、查詢訂單和取得兌換碼。下單金額直接從帳戶餘額扣除,不需要逐筆付款。
- 註冊帳號,在 會員中心 儲值餘額。
- 在 會員中心 → API 介面 建立金鑰,取得
AppID和Secret,建議同時設定 IP 白名單。 - 請按下面的簽章方式呼叫介面。
| 介面網址 | 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 | 隨機字串重複使用 |
1004 | IP 不在白名單內 |
2001 | 商品編碼不存在或已下架 |
2002 | 庫存不足 |
2003 | 缺少必填欄位,或欄位格式不正確 |
3001 | 餘額不足 |
4001 | 訂單不存在 |
429 | 呼叫太頻繁 |
出錯時的回傳格式:{ "code": 3001, "message": "餘額不足" }
商品編碼表
價格為目前的進貨價,以 /products 介面回傳為準。
| 編碼 sku | 商品 | 交付方式 | 價格 |
|---|