API 对接文档 · DJB提链

本页说明如何通过 API 用卡密（CDK）提交提链任务并轮询任务状态。你只需要两个接口：创建任务 和 查询任务。

凭证传递方式：卡密请放在请求头 X-Tilian-CDK（或请求体的 cardCode）。不要写进 URL 查询串——URL 会进入 nginx / CDN 访问日志，泄露即等于账号被盗用。

提链成功后才扣 1 次卡密次数。提交任务不立即扣次；后端在账号真正开始提链时预留 1 次，拿到有效提链链接时结算，失败/取消/超时自动释放。

① 快速开始（两步）

创建任务：POST /api/tasks，携带卡密 + 通道 + AT 列表 + 代理池，返回 task.id。
轮询状态：GET /api/tasks/{id}，直到任务结束，从返回体里读取每个账号的提链链接。

POST/api/tasks

创建一个提链任务。所有字段除标注可选外均为必填。

请求头

Content-Type: application/json
X-Tilian-CDK: TL-XXXX-XXXX-XXXX-XXXX   // 推荐：卡密放请求头

请求体

{
  "mode": "gopay",              // 提链通道，见下方「通道列表」
  "cardCode": "TL-XXXX-XXXX-XXXX-XXXX",  // 卡密（CDK），提链成功扣 1 次
  "accounts": [                    // 账号列表（推荐，含 AT 明文）
    { "email": "user@example.com", "at": "eyJhbGciOi…", "channel": "oa" }
  ],
  "proxiesText": "host:port:user:pass\nhost2:port2:user2:pass2",  // 建单代理池，每行一个
  "exitProxiesText": "",     // 可选，出口/账单侧代理池；留空复用主池
  "proxyMode": "custom",        // custom = 使用自定义代理；builtin = 内置代理池
  "concurrency": 3,            // 可选，请求并发；受卡密等级与全局上限约束
  "timeoutMs": 600000,        // 可选，固定 10 分钟有效提链窗口
  "paramsText": "{}"           // 可选，附加参数 JSON 字符串（国家/币种/强制项）
}

也可以用 atsText 替代 accounts：多行 AT 文本（每行一个 access_token）。但推荐用 accounts，这样能携带邮箱和渠道标记。

字段说明

字段	类型	必填	说明
`mode`	string	必填	提链通道 id，见下方「通道列表」
`cardCode`	string	必填	卡密 CDK；无登录体系，身份即卡密。也可改用 `X-Tilian-CDK` 请求头传入，避免卡密出现在请求体/日志里
`accounts`	array	必填*	账号对象数组，每项含 `email`、`at`（access_token）、`channel`（oa/cs，可选）
`atsText`	string	可选	与 `accounts` 二选一；多行 AT 文本
`proxiesText`	string	必填*	建单代理池，每行一个；未声明协议按 HTTP，SOCKS5 请带 `socks5://` 前缀
`exitProxiesText`	string	可选	出口/账单侧代理池；留空复用主池
`proxyMode`	string	可选	`custom`（默认）或 `builtin`（需管理员开启）
`concurrency`	number	可选	请求并发；最终受卡密等级和全局活跃租约封顶
`timeoutMs`	number	可选	固定 10 分钟，不可绕过
`paramsText`	string	可选	附加参数 JSON 字符串（如 `{"country":"ID","currency":"IDR"}`）

* 代理池必填：提链必须指定建单代理（出口 IP 决定会话类型与优惠资格）。proxyMode=bultin 时可不传 proxiesText。

成功响应 201 Created

{
  "id": "2cbb21e05434",          // 任务 ID，用于后续轮询
  "mode": "gopay",
  "modeName": "GoPay",
  "status": "queued",            // 初始状态为排队中
  "priorityTier": "normal",       // normal / high（按卡密剩余次数）
  "concurrency": 3,
  "createdAt": 1787800233289,
  "progress": { "total": 3, "done": 0, "success": 0, "failed": 0 },
  "items": [ ... ]               // 每个账号一个 item，见下方状态说明
}

错误响应

状态码	含义
400	参数错误（未知通道 / 缺少卡密 / 缺少 AT / 代理为空 / 重复账号 / 超出账号上限等）
402	卡密无效或已用完
409	账号已有正在执行的任务（GCash 等）
429	队列已满或账号触发风控冷却

错误响应体格式：{ "error": "错误描述" }

GET/api/tasks/{id}

查询单个任务状态，返回该任务及其所有账号的实时快照。

路径参数

参数	说明
`id`	创建任务时返回的 `id`

响应关键字段

字段	说明
`status`	任务整体状态，见下方「状态枚举」
`progress`	进度摘要：`total` / `done` / `success` / `failed` / `queued` / `percent`
`items[]`	每个账号一个对象，含 `email`、`status`、`link`、`error` 等
`items[].link`	提链成功后的有效链接（失败时为 `null`）
`items[].status`	该账号状态，见下方「状态枚举」

账号 item 示例（成功后）

{
  "index": 0,
  "email": "user@example.com",
  "status": "success",
  "link": "https://…",         // ← 你要拿的提链链接
  "error": null,
  "attempts": 2,
  "proxy1Country": "ID",
  "orderType": "OA"
}

也支持列表接口 GET /api/tasks?limit=20，配合请求头 X-Tilian-CDK: {卡密} 使用，按卡密返回最近任务。用于刷新页面后恢复还在执行的任务。

安全提示：请求必须携带卡密才能读写任务，服务端会校验任务归属；任务快照里的 uid 只是掩码（TL-****-****-****-XXXX），ownerKey 是不可逆指纹，两者都不能当凭证使用。请勿把卡密拼进 URL（如 ?uid=TL-…）：URL 会被 nginx / CDN / 浏览器历史原样记录，等于把凭证写进日志。

② 状态枚举

状态	含义	是否结束
queued	排队中，等待调度	否
running	正在提链	否
waiting_plus	已提链成功，等待 Plus 到账（GCash/UPI 等）	否
success	提链成功（已生成有效链接）	是
plus_success	提链成功且已到账	是
failed	失败	是
timed_out	超时	是
canceled	已取消	是

轮询建议：任务提交后每 1~3 秒 查询一次 GET /api/tasks/{id}，直到 status 进入结束状态（success / plus_success / failed / timed_out / canceled）。单个 item 可能先行结束，可结合 items[].status 逐个判断。

③ 通道列表（mode）

mode	名称
`paypal`	PayPal
`gopay`	GoPay（印尼）
`gcash`	GCash（菲律宾）
`momo`	MoMo（越南）
`upi`	UPI（印度）
`card`	直卡
`pix`	PIX（巴西）
`ideal`	ideal（荷兰，0 元优惠 + 二维码）

④ 完整示例（Node.js / fetch）

// 1. 创建任务
const res = await fetch('http://127.0.0.1:3000/api/tasks', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    mode: 'gopay',
    cardCode: 'TL-XXXX-XXXX-XXXX-XXXX',
    accounts: [{ email: 'user@example.com', at: 'eyJhbGciOi…', channel: 'oa' }],
    proxiesText: 'host:port:user:pass',
    exitProxiesText: '',
    proxyMode: 'custom',
    concurrency: 3,
    timeoutMs: 600000,
    paramsText: '{}'
  })
});
if (!res.ok) throw new Error((await res.json()).error);
const task = await res.json();
const taskId = task.id;

// 2. 轮询状态直到结束
while (true) {
  const snap = await (await fetch(`http://127.0.0.1:3000/api/tasks/${taskId}`)).json();
  const ended = ['success', 'plus_success', 'failed', 'timed_out', 'canceled'].includes(snap.status);
  for (const it of snap.items) {
    if (it.link) console.log('成功', it.email, it.link);
  }
  if (ended) break;
  await new Promise(r => setTimeout(r, 2000));
}

⑤ 其他辅助接口

POST/api/card/check

校验卡密（不消耗次数），用于在提交任务前确认卡密有效并查看剩余次数。

请求体

{ "code": "TL-XXXX-XXXX-XXXX-XXXX" }

成功响应 200

{
  "ok": true,
  "code": "TL-XXXX-XXXX-XXXX-XXXX",
  "quota": 100,          // 总次数
  "usedQuota": 23,        // 已扣次数
  "reservedQuota": 2,     // 运行中任务预留（未结算）次数
  "available": 75,        // 可用次数 = 总次数 - 已扣 - 预留
  "remain": 77            // 剩余次数 = 总次数 - 已扣
}

错误响应 400

{ "error": "卡密不存在" }  // 或 已禁用 / 已过期 / 已参与融合 / 次数已用完

字段	说明
`remain`	剩余次数（不含预留）
`available`	真正可用次数（扣掉运行中任务预留的）
`reservedQuota`	已被运行中任务预留但未结算的次数

POST/api/card/fuse

把一个或多个 CDK 的剩余次数合并成一个新 CDK（例如把几张零散卡并成一张）。 来源 CDK 会永久失效且不可撤销；正在执行/排队任务的 CDK、已兑换到账户的 CDK、已禁用或已过期的 CDK 都不能参与融合。

请求体

{
  "codes": [                     // 至少 2 个、最多 50 个，不能重复
    "TL-XXXX-XXXX-XXXX-XXXX",
    "TL-YYYY-YYYY-YYYY-YYYY"
  ]
}

成功响应 201

{
  "ok": true,
  "card": {
    "code": "TL-ZZZZ-ZZZZ-ZZZZ-ZZZZ",   // 新 CDK，请立即保存（不提供找回）
    "quota": 230,        // 各来源剩余次数之和
    "usedQuota": 0,
    "remain": 230,
    "expiresAt": 1791702584304   // 取来源中最早的到期时间（不会延长有效期）
  }
}

错误响应

状态码	含义
400	少于 2 个 / 重复 / 超过 50 个 / 卡密不存在 / 已禁用 / 已过期 / 已参与融合 / 已兑换到账户
409	来源 CDK 还有正在执行或排队的任务，请先取消任务再融合
429	融合过于频繁（30 次/分钟/IP）

融合是不可逆操作：请务必保存返回的新 CDK。前端页面的「CDK 融合」入口就是调用本接口。

GET/api/meta

获取服务元信息：可用通道列表、并发配置、内置代理状态、卡密规则等。无需鉴权。

成功响应 200

{
  "app": "DJB提链",
  "version": "V1.01",
  "simMode": false,
  "modes": [                     // 通道列表（用于渲染 mode 选择）
    { "id": "gopay", "name": "GoPay", "short": "GP", "color": "#00aed6", "desc": "GoPay 印尼电子钱包" }
  ],
  "countries": [ ... ],             // 建单国家目录（code / nameZh / nameEn / currency）
  "engine": {
    "maxConcurrency": 100,
    "defaultConcurrency": 3,   // 普通 CDK 运行时并发
    "cdkNormalConcurrency": 3,
    "cdkHighConcurrency": 10,
    "cdkHighRemainThreshold": 100,   // 剩余次数 > 100 进入高等级
    "globalMaxLiveLeases": 700,
    "builtinProxyEnabled": false,
    "builtinProxiesByMode": {},
    "maxRunningTasks": 700,
    "maxQueue": 10000
  },
  "card": {
    "requireCard": true,
    "costPerLink": 1        // 每成功生成 1 条链接扣 1 次
  },
  "serverTime": 1788180926326
}

GET/api/stats?mode={id}

累计统计。可选的 mode 参数按通道过滤「最近成功时间」。

成功响应 200

{
  "totalTasks": 128,
  "totalLinkSuccess": 23,     // 累计提链成功数（生成有效链接）
  "totalFailed": 105,
  "totalCallbackPaid": 0,     // 累计 Plus 回调到账数
  "totalLinks": 23,          // totalLinkSuccess 别名（兼容旧端）
  "totalPlusPaid": 0,        // totalCallbackPaid 别名（兼容旧端）
  "avgDurationMs": 43600,      // 平均成功耗时（毫秒）
  "successRate": 18,          // 成功率（百分比）
  "latestSuccessAt": 1787948282137,  // 指定 mode 的最近成功时间戳，未指定 mode 时为 null
  "latestSuccessAtByMode": { "gopay": 1787948282137 },
  "uptimeSec": 3600
}

POST/api/at/parse

AT 解析预览（脱敏），用于提交前确认 access_token 类型与有效期。

请求体

{ "text": "eyJhbGciOi…\neyJhbGciOi…" }  // 多行 AT，单次最多 200 条

成功响应 200

{
  "count": 2,
  "items": [
    {
      "mask": "eyJhbGc…xxxxxx",      // 脱敏后的 AT
      "kind": "jwt",                // jwt / plain
      "alg": "RS256",
      "aud": "...",
      "clientId": "...",
      "subject": "masked***",
      "expired": false,
      "expiresInSec": 3600
    }
  ]
}

POST/api/proxy/check

检测单个代理的连通性与真实出口。自动识别 HTTP / SOCKS5，通过代理隧道请求 ip-api.com 探测出口 IP 与国家。

请求体

{ "proxy": "host:port:user:pass" }

成功响应 200（无论可用与否都返回 200，看 `ok` 字段）

{
  "ok": true,
  "latencyMs": 842,          // 检测耗时
  "region": "US",             // 出口国家码
  "cc": "US",
  "ip": "1.2.3.4",           // 真实出口 IP
  "isp": "...",
  "scheme": "http",          // http / socks5
  "checkedAt": 1788180926326
}
// 不可用示例：
{ "ok": false, "region": "超时", "error": "timeout" }

GET/api/recent-success

最近 24 小时成功状态时间轴（用于热力格展示）。按 30 分钟分桶，返回每桶成功次数。

成功响应 200

{
  "updatedAt": 1788180926326,
  "bucketMs": 1800000,        // 每桶 30 分钟
  "buckets": 48,             // 48 桶 = 24 小时
  "cells": [
    { "start": 1788094800000, "end": 1788096600000, "total": 86, "byMode": { "gopay": 86 } },
    ...
  ],
  "modes": { "gopay": "GoPay", "momo": "MoMo" },
  "totals": { "all": 1685, "byMode": { "gopay": 1564, "momo": 121 } }
}

GET/api/plus-records?limit=20

Plus 回调到账记录（账号已脱敏），按时间倒序。

成功响应 200

{
  "records": [
    { "t": 1787948282137, "email": "us***e@example.com", "status": "plus_active" }
  ]
}

DELETE/api/tasks/{id}

取消任务。返回取消后的任务快照。任务已结束（success/failed/canceled）时直接返回当前快照。

以上接口均面向 CDK 自动化对接。请遵守服务条款，勿用于恶意或违规用途。卡密（CDK）即身份凭证，请勿泄露。

① 快速开始（两步）

请求头

请求体

字段说明

成功响应 201 Created

错误响应

路径参数

响应关键字段

账号 item 示例（成功后）

② 状态枚举

③ 通道列表（mode）

④ 完整示例（Node.js / fetch）

⑤ 其他辅助接口

请求体

成功响应 200

错误响应 400

请求体

成功响应 201

错误响应

成功响应 200

成功响应 200

请求体

成功响应 200

请求体

成功响应 200（无论可用与否都返回 200，看 ok 字段）

成功响应 200

成功响应 200

成功响应 200（无论可用与否都返回 200，看 `ok` 字段）