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 | 商品 | 交付方式 | 价格 |
|---|