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