充值平台 API 对接文档智链科技 · 下游开发者接入指南
01接入概览
本文面向接入智链科技 ZLINK AI 充值平台的下游开发者。下游统一调用平台域名,完成卡密校验、账号充值、任务查询和使用记录核对。当前文档覆盖 OpenAI 商品,具体套餐与额度由卡密确定。
| 项目 | 约定 |
|---|---|
| API Base URL | https://chong.zlkjai.org |
| 协议与格式 | HTTPS;请求与响应为 UTF-8 JSON |
| 业务判断 | code=0 表示本次请求成功;充值终态另看 sync_result 或 data.status |
| 当前鉴权方式 | 持有平台卡密及对应流程凭据调用;当前版本不要求下游 API Key / Bearer |
| 账号输入 | 完整 ChatGPT Session JSON;使用用户当前有效的登录态 |
| 商品范围 | 本版说明 OpenAI 商品;套餐、购买资格及开放范围以平台实际校验为准 |
| 时间格式 | 保留响应时区;Z 表示 UTC,展示北京时间时转换为 UTC+8 |
| 暂不包含 | 余额扣款、采购发卡、价格表、实时库存、Webhook、取消充值任务 |
示例卡密、账号、令牌和订单号均为占位数据。source 是服务端返回的路由标识,必须原样回传;它不是下游账号、密钥或自定义商户号。
发送空记录查询,检查网络与 JSON 返回;不会校验真实卡密或发起充值。
点击按钮后开始检测。
02快速接入与状态流转
| 顺序 | 方法与路径 | 说明 |
|---|---|---|
| 1 | POST /api/cards/query | 校验并临时保留卡密;取得激活凭据 |
| 2 | POST /api/cards/use | 提交账号 Session;内部完成预检和兑换提交 |
| 3 | GET /api/cards/task/{task_id} | 查询异步任务;直到成功或最终失败 |
| 辅助 | POST /api/cards/lookup | 使用记录查询;用于恢复与售后核对 |
- 新流程开始前生成并保存
request_nonce,同一流程重试时持续复用;保留卡密原始大小写。 - 调用
query。仅在code=0、data.status=unused且source=AUTO时进入本版提交流程。 - 保存激活凭据、到期时间及商品字段。获取用户当前有效的完整 ChatGPT Session JSON,确认目标账号后提交。
- 调用一次
use。如sync_result=succeeded,本次已成功;如sync_result=pending,先保存task_id和order_id再轮询。 - 建议每 3 秒查询一次任务。
pending / working继续等待;succeeded成功;failed最终失败。 - 等待超过约 3 分钟可停止前台自动轮询,显示“仍在处理中”,保留任务并提供稍后查询入口。该等待窗口不是服务端失败时限。
lookup 核查;结果仍不明确时交由平台确认。| 响应现象 | 正确解释 |
|---|---|
use.code=0 + sync_result=pending | 任务已受理,尚未确认到账 |
task.code=0 + data.status=failed | 查询成功,但兑换最终失败 |
task.code≠0 / 网络错误 | 查询未成功,不能据此认定兑换失败 |
lookup.status=unused | 未查到已使用记录或卡密已释放;不能单凭它证明卡密有效 |
03公共约定与凭据
下游请求头
| Header | 是否需要 | 说明 |
|---|---|---|
Content-Type: application/json | POST 必填 | UTF-8 JSON 请求体 |
Accept: application/json | 建议 | 声明希望获取 JSON |
User-Agent: ZLINK-Partner/1.0 | 服务端调用建议配置 | 填写清晰的应用名与版本。浏览器自动携带,不要在浏览器脚本中强行设置。 |
User-Agent。联调时默认 Python 客户端遇到 HTTP 403 / 1010,使用上面的应用标识后可正常得到业务 JSON。该头是应用标识,不是鉴权密钥。不需要把平台内部请求头复制到下游程序。若遇到 HTTP 403,请先检查应用标识及访问策略;不要通过添加内部密钥解决网络访问问题。
响应包络
{
"code": 0,
"msg": "说明文本(可能省略)",
"data": {}
}| 字段 | 类型 | 说明 |
|---|---|---|
code | integer | 业务结果;必须判断。不同接口的非零码含义见对应章节。 |
msg | string,可选 | 请求级提示;任务结果提示通常位于 data.message。 |
data | object,可选 | 接口数据。失败响应可能没有此字段。 |
| 扩展字段 | 可选 | 客户端应忽略未识别字段;不要依赖 debug 等诊断内容。 |
现有 Worker 的普通业务响应使用 HTTP 200,业务失败也可能为 200;未知路径为 404,OPTIONS 预检为 204。网关仍可能返回其他 HTTP 状态或非 JSON 内容。上游 HTTP 429 / 503 及 Retry-After 不保证原样透传,不能只按 HTTP 200 判断业务成功。
四类流程数据
| 字段 | 来源 | 使用规则 |
|---|---|---|
code(卡密) | 平台发放 | 敏感数据;保持原始大小写,去除误粘贴空白。不要自行更改为大写。 |
request_nonce | 调用方生成 | 建议 24 随机字节的无填充 Base64URL(解码后允许 16–64 字节);同一流程复用。它用于锁定恢复,不是严格的交易幂等键。 |
activation_token | query 返回 | 短期激活凭据;与本流程、卡密配套使用。到期时间以响应为准。 |
task_id | use 返回 | 不透明任务查询凭据;保存原值,URL 编码后使用,不解析、不拼造。 |
生成 request_nonce(浏览器或支持 Web Crypto 的运行环境)
const bytes = crypto.getRandomValues(new Uint8Array(24));
const requestNonce = btoa(String.fromCharCode(...bytes))
.replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
// 在首次校验前保存,同一流程不得每次重新生成。请通过下游服务端调用接口,并将卡密、Session 和流程凭据按敏感数据保护。Session 不放入 URL、日志、工单截图或公共 Postman 环境;查询凭据出现在任务路径中时,应对访问日志相应脱敏。完成或终止流程后及时清理不再需要的账号登录态。
04校验卡密
/api/cards/query用于启动兑换流程。此接口会临时保留 平台卡密,并返回后续提交所需的凭据。验证本身不等于完成兑换;不要用它进行后台定时巡检或批量盘点。
| 参数 | 类型 | 要求 | 说明 |
|---|---|---|---|
code | string | 必填 | 卡密;当前格式校验要求至少 12 个字符,仅字母、数字和连字符,且至少包含一个字母。 |
request_nonce | string | 强烈建议 | 调用方预先生成的流程标识。不传时服务端生成;响应丢失后可能无法恢复原流程。 |
{
"code": "ZLKJEXAMPLE12345",
"request_nonce": "Xr7a3kH9mQ2sV5wE8zB1nC4dF6gJ0pLu"
}成功示例
{
"code": 0,
"msg": "卡密有效",
"data": {
"source": "AUTO",
"status": "unused",
"code": "ZLKJEXAMPLE12345",
"type": "recharge",
"product_api_type": "gpt",
"activation_token": "ACTIVATION_TOKEN_PLACEHOLDER",
"request_nonce": "Xr7a3kH9mQ2sV5wE8zB1nC4dF6gJ0pLu",
"expires_in": 180,
"expires_at": "2026-11-16T02:03:00Z",
"provider": "openai",
"product_name": "ChatGPT Plus",
"plan": "plus",
"plan_type": "",
"product_type": "subscription"
}
}expires_in=180 仅为示例,不代表固定有效期。保存实际 expires_at;后续提交时字段名改为 activation_expires_at。product_name、plan 以实际返回为准,不写死套餐映射。Credits 商品另返回 product_type=codex_credits,并可能包含 credit_quantity。
结果与处理
| code | data.status | 处理方式 |
|---|---|---|
| 0 | unused | 校验通过;保存凭据后继续 |
| 0 | bound | 其他通道兼容状态,不进入本文充值 流程 |
| 1 | used | 已有使用记录;转售后查询 |
| 4 | processing | 已有订单处理中;勿再次提交 |
| 2 | disabled 或无 data | 禁用、不可用或作废;查看 msg |
| 3 | locked | 临时锁定;返回原流程继续,或等待后再核查 |
| 1 | unknown | 暂无法确认状态;稍后重试,不能认定无效 |
| 1 | 可能无 data | 格式不符、无效等;结合 msg 处理 |
锁定示例
{
"code": 3,
"msg": "卡密暂时无法重复验证,请返回原流程或等待后重试",
"data": {
"source": "AUTO",
"status": "locked",
"code": "ZLKJEXAMPLE12345",
"retry_after": 180,
"retry_after_estimated": true,
"expires_at": "",
"lock_context": "unknown"
}
}retry_after 单位秒;retry_after_estimated=true 表示估计等待值,不是精确解锁倒计时。lock_context=reservation 表示校验保留,unknown 表示原因未明确。错误文案可能变化,请按字段判断。
05提交兑换
/api/cards/use该请求会实际发起兑换。服务端内部完成账号预检、登录态处理和任务提交,下游无需另外调用账号预检接口。用户应先确认目标账号及商品。
| 参数 | 类型 | 要求 | 说明 |
|---|---|---|---|
code | string | 必填 | 与本流程校验时相同的原始卡密 |
session | object 或 string | 必填 | 推荐传完整 ChatGPT Session JSON 对象;也接受其 JSON 字符串。 |
source | string | 接入必传 | 回传 query 的 source;本文范围应为 AUTO。省略会走其他默认通道。 |
activation_token | string | 流程必传 | query 返回的激活凭据 |
request_nonce | string | 流程必传 | query 返回的流程标识,与此前保持一致 |
activation_expires_at | string | 原样回传 | 取自 query 的 data.expires_at,可能为空 |
product_type | string | 原样回传 | query 返回的商品类型 |
credit_quantity | integer | 条件回传 | Credits 商品返回该值时原样传回,不能自行指定充值数量 |
{
"code": "ZLKJEXAMPLE12345",
"source": "AUTO",
"session": {
"user": {
"email": "user@example.com"
},
"accessToken": "ACCESS_TOKEN_PLACEHOLDER",
"sessionToken": "SESSION_TOKEN_IF_PRESENT"
},
"activation_token": "ACTIVATION_TOKEN_PLACEHOLDER",
"request_nonce": "Xr7a3kH9mQ2sV5wE8zB1nC4dF6gJ0pLu",
"activation_expires_at": "2026-11-16T02:03:00Z",
"product_type": "subscription"
}示例 Session 仅展示结构,不可直接使用。用户获取的实际 Session 不一定含 sessionToken;如已包含则保留,有助于服务端处理部分登录态过期情况。预检不通过时读取 msg,重新取得有效登录态后再按订单状态决定后续操作。
异步受理
{
"code": 0,
"msg": "兑换任务已提交,正在处理中",
"data": {
"task_id": "TASK_ID_FROM_USE_RESPONSE",
"source": "AUTO",
"sync_result": "pending",
"order_id": "ORDER_EXAMPLE_001",
"provider": "openai",
"product_name": "ChatGPT Plus",
"plan": "plus"
}
}立即保存 task_id 和 order_id。sync_result=pending 仅表示受理;若返回 sync_result=succeeded 则已同步完成,此时不再轮询。普通订阅在此响应中可能省略 product_type。
失败与恢复字段
| 字段 | 含义 |
|---|---|
code=1, msg | 本次请求未成功确认提交;结合错误和查询结果处理 |
actual_order=true | 已检测到订单;先查询,勿重复提交 |
stale_lock=true | 锁定凭据需恢复;结合等待时间处理 |
retry_after / expires_at | 可选的重试等待信息;retry_after 位于顶层,与 query 的 data 内位置不同 |
credits_not_eligible=true | 账号未通过 Credits 资格检查 |
duplicate_credits_order=true | 同账号已有 Credits 订单处理中 |
retryable | 兼容控制字段;不构成自动重发兑换的授权或幂等保证 |
正常流程不传内部恢复参数 force_fresh_lock。本版对外未提供独立续期接口;不要通过空闲页面定时校验来长期保留卡密。
06查询任务结果
/api/cards/task/{task_id}| 参数 | 位置 | 说明 |
|---|---|---|
task_id | path | 必须使用 use 返回、且对应 sync_result=pending 的原始任务 ID;按 URL 路径编码。 |
task_id 是平台返回的不透明查询凭据。请完整保存本次提交返回的原始值,按 URL 路径编码后用于查询;不得用订单号替代、删改字符或自行构造。调用方必须从自己保存的真实提交记录中取出任务 ID,不接受终端用户任意填写。
处理中
{
"code": 0,
"data": {
"status": "working",
"message": "充值处理中",
"remote_status": "processing",
"attempt_current": 1,
"attempt_max": 3,
"retrying": false,
"payment_result_checking": false
}
}| data.status | 终态 | 操作 |
|---|---|---|
| pending | 否 | 任务初始化,继续查询 |
| working | 否 | 继续等待;retrying 表示服务端自动重试,无需重发 use |
| succeeded | 是 | 确认成功,停止轮询 |
| failed | 是 | 最终失败,停止轮询并展示 data.message |
最终成功
{
"code": 0,
"data": {
"status": "succeeded",
"message": "ChatGPT Plus充值成功",
"order_no": "ORDER_EXAMPLE_001",
"account": "user@example.com"
}
}最终失败
{
"code": 0,
"data": {
"status": "failed",
"message": "账号兑换资格未通过(示例)",
"order_no": "ORDER_EXAMPLE_001"
}
}code=0,它表示查询动作成功。只有 data.status 能表示兑换终态;查询错误 code=1 不能直接变成“充值失败”。Credits 结果可带 product_type 和 credit_quantity。终态可能带 amount_minor、currency;这是实际支付环节的数据,不是下游向终端客户收取的价格。金额单位为对应币种的最小货币单位;缺失时不要按零处理。
07批量查询使用记录
/api/cards/lookup用于核对卡密使用记录、恢复未确认订单及售后查询。平台接口的记录查询不获取新激活凭据、不发起兑换。它不能替代兑换前的卡密校验。
| 参数 | 类型 | 要求 | 说明 |
|---|---|---|---|
codes | string[] | 必填 | 建议提交 1–50 个格式完整的卡密;保留原始大小写。不要将仅大小写不同的两个卡密放在同一批。 |
{
"codes": [
"ZLKJEXAMPLE12345",
"ZLKJEXAMPLE67890"
]
}响应示例
{
"code": 0,
"data": {
"results": [
{
"code": "ZLKJEXAMPLE12345",
"source": "AUTO",
"status": "used",
"processing": true,
"bound_email": "user@example.com",
"used_at": "2026-11-16T02:01:00Z",
"order_no": "ORDER_EXAMPLE_001",
"provider": "openai",
"product_name": "ChatGPT Plus"
},
{
"code": "ZLKJEXAMPLE67890",
"source": "AUTO",
"status": "unused",
"bound_email": "",
"used_at": ""
}
]
}
}结果项
| 字段 | 类型 | 说明 |
|---|---|---|
code / source / status | string | 卡密标识、通道和记录状态 |
processing | boolean,可选 | true 表示订单处理中,优先于 status=used 展示 |
bound_email / used_at | string,可选 | 关联账号、记录时间,可能为空;处理中可能是开始时间,不代表成功到账时间 |
order_no | string,可选 | 最近订单号,不是完整订单历史 |
| 商品 / 金额字段 | 可选 | 可能含 provider、product_name、plan、product_type、credit_quantity、amount_minor、currency |
| status | 解释 |
|---|---|
| unused | 未查到使用记录或已释放;仍需 query 才能确认可兑换 |
| used + processing=true | 正在处理,不能视为成功到账 |
| used | 存在使用记录;仅可用于售后核对,不凭该字段单独确认充值到账。 |
| locked | 临时保留或锁定 |
| voided | 作废、禁用或过期;其他通道可能返回 disabled |
| unknown | 本次无法确认;不能断言卡密无效 |
| not_found | 当前未识别到有效结果;可能包含格式检查失败 |
unused。不得把 lookup 当作有效库存核验或自动采购依据。本版先去除空白并过滤长度不足 6 的输入,再检查数量;更严格的格式校验仍要求至少 12 位、含字母且只含字母/数字/连字符。调用方应提前验证输入,并保留自己的原始卡密与结果对应关系。不要依赖返回卡密的字母大小写或重复项行为。
08异常、超时与重试
| 场景 | 建议动作 |
|---|---|
| query 返回 locked | 优先返回原流程;参考 expires_at / retry_after 等待后重试;同一流程复用 nonce |
| query 返回 unknown | 短暂退避后再查;提示“暂无法确认”,保留原输入 |
| Session 无效或账号资格未通过 | 展示简化的业务提示;重新获取有效 Session 或更换符合条件的账号 |
| use 网络超时 / 非 JSON / 5xx | 标记“提交结果待确认”,先查任务或 lookup,禁止自动重放 use |
| 已受理但缺少 task_id | 使用卡密查询并联系平台核对;不能再次兑换来“补拿”任务 ID |
| task 查询失败 | 保留原任务;退避后继续查,必要时用 lookup 核对 |
| task 最终 failed | 停止轮询;是否恢复卡密资格以 query 和平台确认结果为准 |
| lookup unknown / 空记录 | 不自动补单;等待或联系平台核对 |
| HTTP 429 / 503(若外层返回) | 如有 Retry-After 则遵从;否则退避重试查询,提交仍先确认原结果 |
建议客户端时间配置
| 操作 | 建议 | 说明 |
|---|---|---|
| query / task | 15 秒请求超时 | 单次查询建议值,不是服务 SLA |
| lookup | 30 秒请求超时 | 聚合查询可能更慢;最多 50 个/次 |
| use | 至少 60 秒;可按链路配置为 120 秒 | 预检与提交可能串行;超时不等于服务端终止 |
| 正常轮询 | 间隔 3 秒 | 查询异常可逐步退避到 5–15 秒,避免并发轮询 |
| 前台等待窗口 | 约 3 分钟后提供稍后查询入口 | 保存任务;不要把窗口结束变成失败或自动重提 |
平台当前没有在此版本中承诺固定 QPS、并发配额、到账时长或 SLA。客户端应限制同一流程并发提交,按平台实际要求调整调用频率。
09调用示例
文档为单文件 HTML,不依赖外部脚本或下载文件。复制下列示例即可开始开发;所有凭据都应替换成你本次流程的实际返回值。
cURL:逐步请求
适用于 Bash / WSL。先将请求 JSON 保存为本地文件,避免敏感信息出现在命令行历史。
BASE="https://chong.zlkjai.org"
# 1. query.json:本页“校验卡密”中的请求结构
curl --silent --show-error --max-time 15 \
"$BASE/api/cards/query" \
-H "Content-Type: application/json" \
-H "Accept: application/json" -H "User-Agent: ZLINK-Partner/1.0" \
--data-binary @query.json
# 2. 会真实发起充值;use.json 回填本次 query 返回的凭据
# 不添加 --retry,不在失败或超时后自动重放
curl --silent --show-error --max-time 120 \
"$BASE/api/cards/use" \
-H "Content-Type: application/json" \
-H "Accept: application/json" -H "User-Agent: ZLINK-Partner/1.0" \
--data-binary @use.json
# 3. 替换为实际 use 返回值经过 URL 编码后的 task_id
curl --silent --show-error --max-time 15 \
"$BASE/api/cards/task/URL_ENCODED_TASK_ID" \
-H "Accept: application/json" -H "User-Agent: ZLINK-Partner/1.0"
# 4. lookup.json:{"codes":["原始卡密"]}
curl --silent --show-error --max-time 30 \
"$BASE/api/cards/lookup" \
-H "Content-Type: application/json" \
-H "Accept: application/json" -H "User-Agent: ZLINK-Partner/1.0" \
--data-binary @lookup.jsonPython 3.10+:可复制的参考客户端
仅使用标准库,导入不会发出网络请求。verify 校验并保留卡密;submit 会真实发起充值且不自动重试;task 仅使用调用方已保存的提交响应。应用应自行持久化订单记录并控制并发。
"""ZLINK AI recharge API reference client (Python 3.10+).
No requests run on import. No automatic redemption retries or polling.
Keep CDKs, session objects and flow credentials private. Persist submission
results before polling. After a timeout, reconcile the original order first.
"""
import json
import secrets
from urllib.request import Request, urlopen
from urllib.error import HTTPError, URLError
from urllib.parse import quote
class APIError(RuntimeError):
"""The request could not be confirmed; this is not an order final state."""
class ZlinkClient:
def __init__(self, base_url="https://chong.zlkjai.org"):
if not base_url.startswith("https://"):
raise ValueError("Use an HTTPS API base URL")
self.base_url = base_url.rstrip("/")
@staticmethod
def new_nonce():
"""Generate once before a new flow; retain it during that flow."""
return secrets.token_urlsafe(24)
def _request(self, method, path, payload=None, timeout=15):
body = None if payload is None else json.dumps(
payload, ensure_ascii=False
).encode("utf-8")
headers = {"Accept": "application/json", "User-Agent": "ZLINK-Partner/1.0"}
if body is not None:
headers["Content-Type"] = "application/json"
request = Request(self.base_url + path, data=body,
headers=headers, method=method)
try:
with urlopen(request, timeout=timeout) as response:
raw = response.read()
except HTTPError as exc:
raise APIError(
f"HTTP {exc.code}; reconcile any submission before retrying"
) from None
except (URLError, TimeoutError, OSError):
raise APIError(
"Transport failure; a submission may already exist. Query first."
) from None
try:
result = json.loads(raw)
except (ValueError, UnicodeError):
raise APIError("Invalid JSON response; order outcome is unconfirmed") from None
if not isinstance(result, dict) or "code" not in result:
raise APIError("Unrecognized response; order outcome is unconfirmed")
return result
def verify(self, cdk, request_nonce):
"""May lock the CDK. Reuse request_nonce for the same flow."""
if not cdk or not request_nonce:
raise ValueError("Provide the original CDK and saved flow nonce")
return self._request("POST", "/api/cards/query", {
"code": cdk, "request_nonce": request_nonce
})
def submit(self, cdk, session, verification, *, confirm_redemption=False):
"""Makes a real redemption request exactly once; never retries.
verification is the entire successful verify response. Check and save
the result. This flag is a local example safeguard, not an API field.
"""
if confirm_redemption is not True:
raise ValueError("Explicitly confirm this real redemption locally")
data = verification.get("data") or {}
if verification.get("code") != 0 or data.get("status") != "unused":
raise ValueError("A successful unused-CDK verification is required")
if data.get("source") != "AUTO":
raise ValueError("This reference client documents the current platform flow only")
if data.get("code") != "".join(cdk.split()):
raise ValueError("CDK must match the saved verification exactly")
if not data.get("activation_token") or not data.get("request_nonce"):
raise ValueError("Verification lacks flow credentials")
if not isinstance(session, (dict, str)) or not session:
raise ValueError("Provide the actual complete session JSON")
payload = {
"code": cdk, "source": data["source"], "session": session,
"activation_token": data["activation_token"],
"request_nonce": data["request_nonce"],
"activation_expires_at": data.get("expires_at", ""),
"product_type": data.get("product_type", "subscription"),
}
if "credit_quantity" in data:
payload["credit_quantity"] = data["credit_quantity"]
return self._request("POST", "/api/cards/use", payload, timeout=120)
def task(self, saved_submission):
"""Poll only an actual pending submission saved by your application."""
data = saved_submission.get("data") or {}
task_id = data.get("task_id", "")
if (saved_submission.get("code") != 0
or data.get("source") != "AUTO"
or data.get("sync_result") != "pending"
or not isinstance(task_id, str)
or not task_id.strip()):
raise ValueError("Supply a saved real pending submission")
return self._request("GET", "/api/cards/task/" + quote(task_id, safe=""))
def lookup(self, cdks):
"""Read usage records; unused alone does not establish CDK validity."""
if (not isinstance(cdks, list) or not 1 <= len(cdks) <= 50
or not all(isinstance(c, str) and c.strip() for c in cdks)):
raise ValueError("Provide a list of 1 to 50 original nonempty CDKs")
return self._request("POST", "/api/cards/lookup", {"codes": cdks}, timeout=30)
@staticmethod
def task_outcome(response):
"""Distinguish request failures from final exchange failure."""
if response.get("code") != 0:
return "query_error"
state = (response.get("data") or {}).get("status")
if state in ("pending", "working", "succeeded", "failed"):
return state
return "unknown"
# Typical manual sequence (no executable demo and no real credentials):
# client = ZlinkClient()
# nonce = client.new_nonce() # Save before verify; reuse on retry.
# verified = client.verify(cdk, nonce)
# Review verified and the customer's actual session/account before submit.
# submitted = client.submit(cdk, session, verified, confirm_redemption=True)
# Save submitted before polling. If sync_result == "succeeded", stop.
# For a pending submission: result = client.task(submitted)
# outcome = client.task_outcome(result)
# "failed" is final failure; "query_error" is NOT final exchange failure.
最小连通性测试
client = ZlinkClient()
result = client._request("POST", "/api/cards/lookup", {"codes": []})
print(result)
# 预期业务校验响应:code=1,提示至少提供一个有效卡密。
# 说明接口连通,不代表已完成真实充值验收。正式充值调用顺序
client = ZlinkClient()
nonce = client.new_nonce() # 首次请求前保存;同一流程重试复用
verified = client.verify(cdk, nonce)
# 先判断 code=0、data.status=unused,并确认账号和商品。
# session 为用户本次提供的完整 JSON 对象。
submitted = client.submit(cdk, session, verified, confirm_redemption=True)
# 先保存 submitted,再处理结果;不要打印或公开其中的凭据。
if submitted.get("code") == 0:
data = submitted.get("data") or {}
if data.get("sync_result") == "succeeded":
print("充值成功")
elif data.get("sync_result") == "pending":
result = client.task(submitted)
state = client.task_outcome(result)
# pending/working:间隔约3秒继续查;succeeded/failed:停止。
# query_error/unknown:仅表示未查明,不当作充值失败。
print(state)
else:
print("提交结果需核对,请使用原卡密查询")
else:
print("请求未确认成功,请核对原因与原订单,勿直接重发")10联调验收与版本记录
| 测试场景 | 期望结果 |
|---|---|
| 有效 OpenAI 卡密 | query 返回 source 原值 / unused 及有效流程凭据 |
| 同一流程重复校验 | 保持同一 nonce;按实际返回恢复凭据,不生成并行流程 |
| 另一个流程占用 | 展示 locked 与等待信息,不循环创建 nonce 抢占 |
| 无效 Session / 资格不符 | 展示业务失败,不将其标为已到账 |
| 异步成功 | use 受理后,仅在真实任务 succeeded 时完成订单 |
| 最终失败 | 即使 task.code=0,也按 data.status=failed 结束 |
| 提交响应丢失 | 转待确认,查原订单,不自动补单 |
| 批量无订单 / unknown | 不将 unused 视为有效库存,不将 unknown 判死卡 |
| Credits 商品(如开通) | 原样回传商品数量;资格检查失败可正确展示 |
文档示例按当前接口逻辑校核,并完成客户端离线校验与线上非交易连通性检查。真实订单的账号资格、卡密归属、最终到账和异常恢复,仍需使用授权测试卡密完成一次端到端验收。联调通过范围不应被解释为所有卡密和账号均可充值。
| 版本 | 日期 | 变更 |
|---|---|---|
| v1.1 | 2026-11-16 | 平台直连版:明确公共请求头、原样回传路由与任务凭据;加入可运行的 Python 示例及连通性检查。 |