API 文档

Nerver 全部接口 — AC 资格预检 · 订阅查询 · 支付链接 · PIX · UPI · 测试通道 · PayPal · Outlook 邮箱 · 统计

认证状态加载中...

POST /api/v1/check

POST/api/v1/check

AC token 有效性 + 优惠资格检查。也支持 GET /api/v1/check?token=...&promoId=...

请求	类型	说明
token	string	单个 AC token (与 tokens 二选一)
tokens	string[]	批量 (上限 50)
promoId	string?	默认 plus-1-month-free

响应	类型	说明
token_ok	bool	AC 是否有效
eligible	bool	是否有优惠资格
reason	string	eligible \| not-eligible \| token-401 \| jwt-expired \| empty-token \| fetch-error \| http-error \| unknown-coupon-state
message	string?	面向终端用户的中文友好提示 (失败时附带, ok=true 时不返回)
coupon_state	string?	OpenAI state
status	number?	OpenAI HTTP 码
reg_type	string?	★ 注册方式: phone(手机号) \| email(邮箱) \| unknown — 离线解 JWT 得出, 无需额外请求
phone_number	string?	手机号注册账号的号码 (E.164, 如 +1702xxxxxxx); 邮箱注册为 null
phone_verified	bool	手机号是否已验证
upi_eligible	bool	★ 该 token 当前能否调 /api/v1/upi — 综合 UPI 总开关 + 后台「UPI 只接受手机号账户」开关 + reg_type 计算. `true`=允许提交 UPI; `false`=不允许 (看 upi_eligible_reason)
upi_eligible_reason	string?	不允许时的原因. `account-not-phone`=后台限制手机号且 reg_type 非 phone; `feature-disabled`=UPI 总开关关闭; `null`=允许. 值与 /api/v1/upi 的 reason 一致, 对接方可统一处理
email / account_id / plan_type	string?	JWT 解出 (手机号注册 email 为 null)
jwt_expired / jwt_exp_in_sec	bool/number	JWT 过期信息

curl -X POST -H 'content-type: application/json' -d '{"token":"eyJ..."}' https://YOUR_HOST/api/v1/check

POST /api/v1/subscription

POST/api/v1/subscription

查询 ChatGPT 账号实时订阅状态。

请求	类型	说明
token	string	AC token (必填)

响应	类型	说明
ok / reason	bool/string	ok \| empty-token \| jwt-expired \| token-401 \| http-error \| fetch-error \| no-account
message	string?	面向终端用户的中文友好提示 (失败时附带)
plan_type	string	实时套餐 (free/plus/pro/team)
subscription_plan	string	chatgptplusplan 等
has_active_subscription	bool	是否有活跃订阅
billing_period / billing_currency	string	monthly\|yearly / USD 等
expires_at / renews_at / days_left	string/number	时间线
will_renew / is_delinquent	bool	续费/欠费
purchase_origin_platform	string	chatgpt_web / chatgpt_ios / chatgpt_android
applied_discounts	array	[{promo_campaign_id, amount, ...}]
eligible_offers	string[]	可购买套餐列表

curl -X POST -H 'content-type: application/json' -d '{"token":"eyJ..."}' https://YOUR_HOST/api/v1/subscription

POST /api/v1/checkout

POST/api/v1/checkout

生成 ChatGPT Plus 优惠支付链接 (pay.openai.com)。

请求	类型	说明
token	string	AC token (必填)
promoId	string?	默认 plus-1-month-free
country	string?	ISO 国家码, 默认 ID
currency	string?	默认 IDR。支持: USD AUD CAD GBP EUR CLP JPY INR IDR PKR THB MYR TWD VND PHP NGN ZAR KZT TZS EGP BRL SEK CZK PLN DKK NOK KRW COP MXN PEN
planName	string?	默认 chatgptplusplan

响应	类型	说明
ok / reason	bool/string	ok \| empty-token \| jwt-expired \| token-401 \| coupon-not-eligible \| coupon-check-failed \| checkout-failed \| no-url \| fetch-error
message	string?	面向终端用户的中文友好提示 (失败时附带)
url	string?	pay.openai.com 支付链接 (仅 ok=true)
coupon_state / email / account_id	string?	附加信息

curl -X POST -H 'content-type: application/json' -d '{"token":"eyJ...","country":"US","currency":"USD"}' https://YOUR_HOST/api/v1/checkout

POST /api/v1/pix · PIX 巴西 (长链)

POST/api/v1/pix

巴西 PIX 即时支付 — 长链接模式: 输入 AC token → 自动生成 checkout → Stripe 短/长跳转链接, ~25s。
需要直接拿真实二维码请用 /api/v1/pix-short (PIX 内部支付)。

请求	类型	说明
token	string	AC token (必填)
promoId	string?	默认 plus-1-month-free

响应	类型	说明
ok / reason	bool/string	ok \| hosted-fallback \| empty-token \| jwt-expired \| checkout-failed \| coupon-not-eligible \| no-cs-id \| snapshot-failed \| approve-failed \| no-qr \| pix-protocol-error
mode	string	"short_emv" \| "long_link" — 标识本次响应来自哪种模式
message	string?	面向终端用户的中文友好提示 (失败时附带)
pix_qr_data	string	PIX EMV payload (内部支付模式有值; 长连接模式为空)
pix_qr_image_url	string	Stripe 托管 QR PNG 图片 URL (内部支付模式有值)
pix_hosted_url	string	Stripe 支付指引页面 (内部支付模式有值)
stripe_hosted_url	string	Stripe Checkout 长跳转链接 (两种模式都尽量填充, 兜底跳转用)
pix_expires_at	number	过期时间戳 (秒), 约 11 小时有效
pix_expires_iso	string	过期 ISO 时间
setup_intent_id / pm_id / session_id	string	Stripe 内部 ID
persona	object	自动生成的巴西身份 {name, cpf, city, state, ...}
email / account_id	string?	JWT 解出

curl -X POST -H 'content-type: application/json' -d '{"token":"eyJ..."}' https://YOUR_HOST/api/v1/pix

示例响应 (截断, pix_qr_data 就是页面 QR 下方那串可复制的 EMV 文本):

{
  "ok": true,
  "reason": "ok",
  "pix_qr_data": "00020126180014br.gov.bcb.pix5204000053039865802BR5911Ebanx LTDA.6008CURITIBA62070503***80720014br.gov.bcb.pix2550pix.ebanx.com/rec/A0239E59E6F9A9FDF7DD8F6A4BA8BC9163043B23",
  "pix_qr_image_url": "https://files.stripe.com/.../pix.png",
  "pix_hosted_url":   "https://pay.openai.com/c/.../pix_instructions",
  "pix_expires_at":   1780300800,
  "pix_expires_iso":  "2026-06-02T03:00:00.000Z",
  "session_id":  "cs_live_a1qxAW...",
  "pm_id":       "pm_1TdUeGC6...",
  "setup_intent_id": "seti_1TdUelC6...",
  "email": "user@example.com",
  "persona": { "name": "Pedro Ferreira", "cpf": "414.225.021-39", "city": "Curitiba", "state": "PR" }
}

# 提取 EMV 码 (jq):
curl -s -X POST .../api/v1/pix -d '{"token":"eyJ..."}' | jq -r .pix_qr_data

POST /api/v1/pix-short · PIX 内部支付

POST/api/v1/pix-short

巴西 PIX 内部支付模式 — 直接返回 QR 字符串(pix_qr_data)、QR 图片、托管页。完整 7 步协议, 含自动换 IP 重试(approve blocked / 网络失败时按重试次数换代理 SID 重试)。
独立鉴权 — 与全局 AUTH_TOKEN 解耦, 在 后台 → 运行配置 → 内部支付鉴权 token 配置(留空=不鉴权)。

鉴权	说明
Authorization: Bearer <token>	推荐, 与 `pix_short_service_token` 比对(timing-safe)
?key=<token>	等效, query 传参

请求	类型	说明
token	string	AC token (必填)
promoId	string?	默认 plus-1-month-free

响应	类型	说明
ok / reason	bool/string	失败时见下方「错误码与重试策略」 4 个分类模块
mode	string	固定 "short_emv"
pix_qr_data	string	PIX EMV payload (短码字符串, 直接渲染二维码)
pix_qr_image_url	string	Stripe 托管 QR PNG 图片 URL
pix_hosted_url	string	Stripe 支付指引页面
pix_expires_at / pix_expires_iso	number/string	过期时间
setup_intent_id / session_id	string	Stripe 内部 ID
persona / email / account_id	object/string	自动生成巴西身份 / JWT 解出
attempts	number	实际尝试次数 (1 = 首试就成功)
attempts_log	array	每次尝试的 {attempt, reason, session_id, proxyUrl(脱敏), error}

curl -X POST \
  -H 'content-type: application/json' \
  -H 'Authorization: Bearer YOUR_PIX_SHORT_TOKEN' \
  -d '{"token":"eyJ..."}' \
  https://YOUR_HOST/api/v1/pix-short

提示: 后台代理 URL 字段同时支持标准 http://user:pass@host:port 和购买面板原生 host:port:user:pass 格式(自动转换)。$RAND 占位符每次重试会替换为 8 位随机 hex, 用于 IPWEB 等按 SID 切换出口 IP 的代理。

📑 错误码与重试策略

服务端已在内部按 pix_short_retry_count 配置自动换 IP 重试。客户端再次重试前请参考下表:

✅ 业务成功 (1 个)HTTP 200

服务端返回 ok:true 且 pix_qr_data 非空, 直接渲染 QR 码即可。

reason	含义	动作
ok	成功生成 PIX EMV QR	✓ 完成

🔄 可重试 — 临时性错误 (5 个)HTTP 429 / 503 / 500

服务端因瞬时拥塞 / 限流 / 网络抖动失败, 同 token 重发即可, 但请遵守退避建议避免雪崩。

reason	HTTP	含义 / 出现场景	建议动作
rate-limited	429	客户端 IP 触发 `rate_rpm_pix_short` 上限 (默认 120/min)。响应头带 `retry-after` 秒数	读 retry-after 后重试
concurrency-busy	503	服务端 `pix_short_concurrency` 并发槽位用尽	立即重试 (随机退避 0.5-2s)
server-error	500	未捕获异常 / 内部 throw	退避 1-5s 重试; 持续触发请反馈
fetch-error	200	代理 / 上游网络失败 (cycletls connect/timeout)	退避 2-5s 重试 (服务端已换 IP 重试 N 次仍败)
pix-protocol-error	200	Stripe / OpenAI 协议非预期响应 (字段缺失等)	退避 3-10s 重试; 持续 3+ 次反馈

⚠️ 服务端已重试 — 客户端可换 IP 再试 1-2 次 (6 个)HTTP 200

这些失败服务端内部已经按 pix_short_retry_count (默认 6) 轮换 IP 重试过仍然失败, 客户端允许再试 1-2 次(同 token 换出口 IP 仍有概率成功):

低频客户: 等 30-60s 让代理池冷却后再试
同账号连续 3+ 次失败: 该账号事实上不可用, 停止重试以免被进一步打标
高频客户: 同时切换 token / 账号避免雪崩

reason	含义 / 触发场景	建议动作
checkout-failed	OpenAI POST /payments/checkout 非 200, 通常是 CF 403 / 出口被识别	换 IP 再试 1-2 次, 仍败则换 token
snapshot-failed	OpenAI POST /snapshot 落盘失败, 通常是 token 中途失效	换 IP 再试 1 次, 仍败则换 token
approve-failed	OpenAI /approve 返 blocked, 通常是账号风险 + 出口 IP 联合触发	换 IP/换 token 重试 1-2 次
no-qr	所有步骤成功但 polling 30s 内没拿到 pix QR / next_action	直接重试 (代理不稳)
risk-blocked	OpenAI 在某次调用层面识别为风险 (代理特征+账号叠加), 不一定是账号永久黑名单	换 IP 重试 1-2 次, 持续触发则换账号
coupon-not-eligible	优惠资格校验失败, 可能是出口 IP 区域识别 / 临时风控	换 IP 重试 1-2 次, 持续触发则换账号

🛑 永久失败 — 重试无意义, 必须换 token / 换账号 (7 个)HTTP 200 / 401 / 503

这些不要重试, 重试也是同样结果。客户端应直接切换 token / 提示用户更换账号 / 联系运营。

reason	HTTP	含义	建议动作
unauthorized	401	商务鉴权 token 缺失或错误	检查 Authorization 头
empty-token	200	请求体 `token` 字段为空	入参修复
invalid-token-format	400	token 不符合 JWT 形态 (非 eyJ 开头三段)	入参修复
jwt-expired	200	JWT exp 已过	让用户重新获取 token
token-invalidated	200	token 被 OpenAI 主动作废 (已退出登录 / 已撤销)	必须换 token
already-paid	200	账号已存在有效订阅, 不能再创建	无需重试, 提示用户「已支付」
feature-disabled	503	后台 `pix_short_enabled=0` 已禁用此端点	联系运营开启

POST /api/v1/pix-short/stream · PIX 内部支付 SSE 实时进度

POST/api/v1/pix-short/stream

与 /api/v1/pix-short 鉴权与请求体完全一致, 但响应为 text/event-stream SSE 流, 实时推送每次 attempt 与每个内部 step 进度, 适合前端展示等待界面。

事件	data 字段	含义
hello	{retry_count, max_attempts}	连接成功, 返回最大尝试次数
progress	{type:"attempt-start", attempt, max}	开始第 N 次尝试
progress	{type:"step", attempt, step}	step ∈ checkout / init / region / snapshot / confirm / approve / polling
progress	{type:"attempt-end", attempt, ok, reason, error}	第 N 次尝试结果(失败可重试)
done	同 /pix-short 的 200 响应体	整体完成 (ok 或失败终态), 之后服务端 close

curl -N -X POST \
  -H 'content-type: application/json' \
  -H 'accept: text/event-stream' \
  -H 'Authorization: Bearer YOUR_PIX_SHORT_TOKEN' \
  -d '{"token":"eyJ..."}' \
  https://YOUR_HOST/api/v1/pix-short/stream

POST /api/v1/upi

POST/api/v1/upi

印度 UPI 支付: 输入 AC token → checkout (IN/INR) → Stripe UPI 协议 → 返回授权链接或二维码。

请求	类型	说明
Authorization	header?	Bearer <upi_service_token \| upi_business_token>。后台两个 token 任一匹配即可放行,全空 = 不鉴权。
token	string	AC token (必填, JWT 格式)
promoId	string?	默认 plus-1-month-free
poolKeep	int?	并发参数 1~50 (默认后台配置)
poolMax	int?	尝试上限 1~2000 (默认后台配置)

响应	类型	说明
ok / reason	bool/string	ok \| empty-token \| jwt-expired \| invalid-token-format \| token-invalidated \| already-paid \| risk-blocked \| checkout-failed \| region-failed \| pm-unavailable \| snapshot-failed \| confirm-error \| confirm-failed \| approve-blocked \| no-next-action \| account-not-phone \| concurrency-busy \| feature-disabled \| unauthorized \| rate-limited \| cdk-busy \| bad-request \| server-error
retryable	bool	失败时附带。false = 不可重试(拿不到连接的终态 `approve-blocked` / `no-next-action`, 以及 token/账号类永久失败 `already-paid` / `token-invalidated` / `jwt-expired` / `unauthorized` / `account-not-phone` 等); true = 可重试(临时性错误 `concurrency-busy` / `rate-limited` / `server-error` / 网络类)。approve-blocked / no-next-action 表示已跑完整流程仍拿不到 UPI 连接, 重试同 token 也是同结果, 应换 token/账号; account-not-phone 表示后台开启「UPI 只接受手机号账户」开关而该 token 为邮箱注册, 应换手机号注册账户
message	string?	面向终端用户的中文友好提示 (失败时附带)
next_action_type	string	redirect_to_url \| upi_handle_redirect_or_display_qr_code \| display_upi_qr_code
upi_redirect_url	string	UPI 授权跳转链接
upi_qr_data	string	UPI deep-link payload (部分地区返回)
upi_qr_image_url	string	UPI 二维码图片 URL
upi_hosted_url	string	Stripe 托管支付指引页
request_id / duration_ms	string/int	请求追踪 id / 总耗时毫秒
⚠ 超时提示	POOL 枪数跑满可能耗时 ~3-5 分钟, HTTP 客户端超时请设为 ≥ 300秒。如需实时反馈, 推荐调 SSE 端点 /api/v1/upi/stream

curl -X POST \
  -H 'Authorization: Bearer YOUR_UPI_TOKEN' \
  -H 'content-type: application/json' \
  -d '{"token":"eyJ...","poolKeep":50,"poolMax":2000}' \
  https://YOUR_HOST/api/v1/upi

POST /api/v1/upi/stream

POST/api/v1/upi/stream

UPI 支付 SSE 实时进度流。鉴权 / 请求体同 /api/v1/upi。

SSE 事件	负载字段
event: hello	{request_id, pool_keep, pool_max, queue_length, inflight, capacity}
event: progress · attempt-start	{type:"attempt-start", pool_keep, pool_max}
event: progress · step	{type:"step", step:"<枚举>"} — step 枚举: `warmup` \| `sentinel` \| `checkout` \| `warmup-account` \| `region` \| `snapshot` \| `confirm` \| `approve` \| `polling`
event: progress · approve-tick	{type:"approve-tick", slot, max, blocked, exception, other, elapsed_ms} — 每 50 枪采样一次
event: progress · approve-hit	{type:"approve-hit", slot} — 某一枪命中, 后面仅有 polling 步骤
event: progress · attempt-end	{type:"attempt-end", ok, reason, error}
event: done	精简响应体 — 与 POST /api/v1/upi 同样结构
: ping (注释行)	每 15s 一个 keep-alive, 供越过代理/CDN 空闲超时

curl -N -X POST \
  -H 'Authorization: Bearer YOUR_UPI_TOKEN' \
  -H 'content-type: application/json' \
  -d '{"token":"eyJ..."}' \
  https://YOUR_HOST/api/v1/upi/stream

POST /api/v1/ideal · 测试通道

POST/api/v1/ideal

测试通道授权链接生成: 输入 AC token → 上游协议 → 返回 iDEAL 原生 QR 内容 / 服务端 PNG / 授权跳转 URL。支持 POOL 抢风控, 内部账单地址按后台开关切换 (NL/JP/随机)。
★ 字段命名跟 /api/v1/kakao-pay 对齐: pm / ideal_qr_data / ideal_qr_image_url — 跨渠道调用方代码可以共用。

请求	类型	说明
Authorization	header?	Bearer <ideal_service_token \| ideal_business_token>。后台两个 token 任一匹配即可放行,全空 = 不鉴权。
token	string	AC token (必填, JWT 格式)
promoId	string?	默认 plus-1-month-free
poolKeep	int?	并发参数 1~50 (默认后台配置)
poolMax	int?	尝试上限 1~2000 (默认后台配置)

响应	类型	说明
ok / reason	bool/string	ok \| empty-token \| jwt-expired \| invalid-token-format \| token-invalidated \| already-paid \| risk-blocked \| checkout-failed \| region-failed \| pm-unavailable \| snapshot-failed \| confirm-error \| confirm-failed \| approve-blocked \| no-next-action \| aborted \| concurrency-busy \| feature-disabled \| unauthorized \| rate-limited \| bad-request \| server-error
retryable	bool	★ 失败时附带. `false` = 不可重试 (同 token 重试也是同结果, 请换 token/账号). `true` = 可重试 (临时错: `concurrency-busy` / `rate-limited` / `server-error` / 网络类)
message	string?	面向终端用户的中文友好提示 (失败时附带)
pm	string	★ 渠道标识, 固定 `"ideal"` (跟 KakaoPay/PIX/UPI `pm` 字段对齐)
next_action_type	string	redirect_to_url
ideal_qr_data	string	★ 主字段: QR 字符串内容 — `https://tx.ideal.nl/2/<TX_ID>?sig=<SIG>`. 把它编码进二维码, 用户手机相机扫码 → 唤起银行 App / iDEAL App 直接付款 (跟 `kakao_qr_data` 同语义)
ideal_qr_image_url	string	★ 主字段: 服务端生成的 PNG 图 URL — 调用方一次 GET 拿图 (/api/v1/ideal/qr.png). 跟 `kakao_qr_image_url` / `pix_qr_image_url` 同语义
ideal_qr_url	string	[兼容] 与 `ideal_qr_data` 同值, 老调用方继续可用; 新接入建议用 `ideal_qr_data`
ideal_redirect_url	string	Stripe 原始 redirect URL (`pm-redirects.stripe.com/...`) — 浏览器跟跳到 ideal.nl 选银行页
ideal_hosted_url	string	iDEAL 托管支付页 URL (`pay.ideal.nl/transactions/...?sig=...`) — 浏览器直接打开
ideal_payload_uri	string	URL-encoded 交易 URI (`https%3A%2F%2Ftx.ideal.nl%2F2%2F...`) — 高级集成用
ideal_creditor	string	收款方名称 (例如 `"OpenAI Ireland Limited"`)
ideal_amount	int?	金额 (单位: cent, 例如 `1` = €0.01)
ideal_issuers_count	int	支持的荷兰银行数量 (例如 18)
billing_locale / billing_country	string	账单地址国家配置 / 实际生成持卡人国家
request_id / duration_ms	string/int	请求追踪 id / 总耗时毫秒
⚠ 超时提示	POOL 枪数跑满可能耗时 ~3-5 分钟, HTTP 客户端超时请设为 ≥ 300秒。如需实时反馈, 推荐调 SSE 端点 /api/v1/ideal/stream

curl -X POST \
  -H 'Authorization: Bearer YOUR_IDEAL_TOKEN' \
  -H 'content-type: application/json' \
  -d '{"token":"eyJ...","poolKeep":50,"poolMax":2000}' \
  https://YOUR_HOST/api/v1/ideal

# 成功响应示例:
# {
#   "ok": true,
#   "pm": "ideal",
#   "ideal_qr_data": "https://tx.ideal.nl/2/ADBC...?sig=CGBC...",
#   "ideal_qr_image_url": "https://YOUR_HOST/api/v1/ideal/qr.png?d=aHR0cHM6...",
#   "ideal_qr_url": "https://tx.ideal.nl/2/ADBC...?sig=CGBC...",
#   "ideal_redirect_url": "https://pm-redirects.stripe.com/...",
#   "ideal_hosted_url": "https://pay.ideal.nl/transactions/...?sig=...",
#   "ideal_creditor": "OpenAI Ireland Limited",
#   "ideal_amount": 1,
#   "ideal_issuers_count": 18,
#   "billing_country": "NL",
#   "request_id": "req_xxxx",
#   "duration_ms": 62000
# }

POST /api/v1/ideal/stream

POST/api/v1/ideal/stream

测试通道 SSE 实时进度流。鉴权 / 请求体同 /api/v1/ideal。

SSE 事件	负载字段
event: hello	{request_id, pool_keep, pool_max, queue_length, inflight, capacity}
event: progress · attempt-start	{type:"attempt-start", pool_keep, pool_max}
event: progress · step	{type:"step", step:"<枚举>"} — step 枚举: `warmup` \| `sentinel` \| `checkout` \| `warmup-account` \| `region` \| `snapshot` \| `confirm` \| `approve` \| `polling` \| `follow-redirect` \| `ideal-initiate`
event: progress · approve-tick	{type:"approve-tick", slot, max, blocked, exception, other, elapsed_ms} — 每 50 枪采样一次
event: progress · approve-hit	{type:"approve-hit", slot} — 某一枪命中, 后面仅有 polling/follow-redirect 步骤
event: progress · redirect-result	{final_qr_url, followed_to_ideal_nl, got_real_qr_code_url, qr_source, hops} — follow stripe 跳转 + 拆 / 调 initiate 的结果摘要
event: progress · attempt-end	{type:"attempt-end", ok, reason, error}
event: done	精简响应体 — 与 POST /api/v1/ideal 同样结构
: ping (注释行)	每 15s 一个 keep-alive, 供越过代理/CDN 空闲超时

curl -N -X POST \
  -H 'Authorization: Bearer YOUR_IDEAL_TOKEN' \
  -H 'content-type: application/json' \
  -d '{"token":"eyJ..."}' \
  https://YOUR_HOST/api/v1/ideal/stream

GET /api/v1/ideal/qr.png · iDEAL QR 图片

GET/api/v1/ideal/qr.png?d=<base64url>

服务端 PNG 图片端点 — 跟 /api/v1/kakao-pay/qr.png 同款。
调用方拿到响应里的 ideal_qr_image_url 字段, 一次 GET 即可拿 PNG (480x480, ~2-3KB)。无状态生成, 不存数据库, 无鉴权 (公开图片链接, 含 base64url 编码的 QR 字符串作为输入参数)。可缓存 5 分钟。

请求	类型	说明
d	query string	QR 字符串内容的 base64url 编码 (一般直接用响应里 `ideal_qr_image_url`, 不需自己构造)

响应	说明
200	image/png — 480x480 PNG, 错误纠正等级 M, 边距 2
400	缺少/超长/无效 base64url

# 通常不需要手动调, 拿响应里 ideal_qr_image_url 字段直接用
curl -o ideal-qr.png 'https://YOUR_HOST/api/v1/ideal/qr.png?d=aHR0cHM6Ly90eC5pZGVhbC5ubC8yLy4uLg'

POST /api/v1/blik · BLIK 波兰支付

POST/api/v1/blik

波兰 BLIK 内部支付 — 输入 ChatGPT AC token + 从手机银行 App 拿的 BLIK 6 位授权码 (2 分钟有效), 服务端完成 checkout/snapshot/confirm/PI-confirm/approve POOL 全流程。
setup 阶段 sticky IP: warmup→snapshot 五步共用一个 PL ipweb 出口 (避免 CF 风控同 token 多 IP 误判). pay 阶段才走 $RAND 旋出口.
性能: setup 阶段 sentinel 4 个 chatgpt 请求 + warmup-account/elements 三路全并发 (~22-24s 到 confirm; 之前 ~32s).
鉴权: blik_service_token / blik_business_token 任一区配合 (都空=不鉴权). 并发: blik_concurrency (入站) + blik_pool_keep/blik_pool_max (approve 抢风控).

请求	类型	说明
token	string	必填 — ChatGPT AC token (eyJ JWT)
blikCode	string	必填 — BLIK 6 位授权码 (仅数字, 可带空格/划线, 服务端会 normalize)
poolKeep	number?	approve 并发槽数覆盖 (默认读 settings.blik_pool_keep=50, 上限 50)
poolMax	number?	approve 累计枪数覆盖 (默认读 settings.blik_pool_max=2000, 上限 2000)
promoId	string?	优惠 ID (默认 plus-1-month-free)
⚠ 超时提示	POOL 枪数跑满可能耗时 ~3-5 分钟, HTTP 客户端超时请设为 ≥ 300 秒. 实时反馈请调 /api/v1/blik/stream

响应	说明
ok	true / false
reason	ok / empty-token / invalid-token-format / jwt-expired / missing-blik-code / invalid-blik-code / token-invalidated / already-paid / risk-blocked / checkout-failed / region-failed / pm-unavailable / snapshot-failed / confirm-error / confirm-failed / pi-confirm-failed / approve-blocked / no-next-action / concurrency-busy / feature-disabled / cdk-busy / unauthorized / rate-limited / server-error
retryable	true=业务侧可重试; false=终态 (重试也是同结果)
next_action_type	blik_authorize 等 stripe 返回类型
blik_redirect_url / blik_hosted_url	BLIK 授权跳转链接 (如有)
setup_intent_id	Stripe PI/SI id (approve 通过后可见; pi-confirm 阶段提交 BLIK code 时用到)
request_id / duration_ms	请求 ID 与耗时

curl -X POST -H 'content-type: application/json' \
  -H 'authorization: Bearer YOUR_SERVICE_TOKEN' \
  -d '{"token":"eyJ...","blikCode":"123456"}' \
  https://YOUR_HOST/api/v1/blik

POST /api/v1/blik/stream

POST/api/v1/blik/stream

BLIK 波兰支付 SSE 实时进度流。鉴权 / 请求体同 /api/v1/blik。
step 事件顺序: warmup → sentinel → checkout → warmup-account → region → snapshot → confirm → cfbody-dumped (调试模式) → approve → approve-body-dumped (调试模式) → approve-body-info → pi-confirm (有 PI 信息时) → pi-confirm-ok / pi-confirm-skipped → polling

SSE 事件	说明
event: hello	连接建立 {request_id, pool_keep, pool_max, queue_length, inflight, capacity}
event: progress	进度: step / approve-tick / approve-hit / attempt-start / attempt-end
event: done	精简响应体 — 与 POST /api/v1/blik 同样结构

curl -N -X POST -H 'content-type: application/json' \
  -H 'accept: text/event-stream' \
  -d '{"token":"eyJ...","blikCode":"123456"}' \
  https://YOUR_HOST/api/v1/blik/stream

POST /api/v1/paypal

POST/api/v1/paypal

PayPal 链接生成：输入 AC token + 地区 (US/JP) → Stripe 协议拿 BA token → 拼出 PayPal 授权链接。

请求	类型	说明
token	string	AC token (必填)
region	string	US (美区) 或 JP (日区), 默认 US
promoId	string?	默认 plus-1-month-free

响应	类型	说明
ok / reason	bool/string	ok \| empty-token \| jwt-expired \| invalid-region \| checkout-failed \| no-cs-id \| no-redirect \| no-ba-token \| paypal-protocol-error
message	string?	面向终端用户的中文友好提示 (失败时附带)
region	string	US / JP
ba_token	string	PayPal BA token (BA-xxx)
approve_url	string	PayPal 授权链接 (主链接)
pay_url / signup_url	string	PayPal /pay 与 guest 注册链接
pm_id / session_id	string	Stripe 内部 ID

curl -X POST -H 'content-type: application/json' -d '{"token":"eyJ...","region":"US"}' https://YOUR_HOST/api/v1/paypal

POST /api/v1/kakao-pay · 韩国 KakaoPay (二维码)

POST/api/v1/kakao-pay

韩国 KakaoPay 支付：输入 AC token → checkout (KR/KRW) → approve POOL 抢风控 → 跟 NicePay 8 hop → 拿到 KakaoPay bridge + tid + 真正可扫的 QR URL。详见 /docs/kakao-pay.md。

请求	类型	说明
Authorization	header?	Bearer <kr_service_token \| kr_business_token>。后台两个 token 任一匹配即可放行,全空 = 不鉴权。
token	string	AC token (必填, JWT 格式)
promoId	string?	默认 plus-1-month-free
poolKeep	int?	approve POOL 持续并发槽数 1~50 (默认后台 50)
poolMax	int?	approve POOL 累计尝试上限 1~2000 (默认后台 2000)
retryCount	int?	整轮失败重试次数 0~5 (默认后台 1)

响应	类型	说明
ok / reason	bool/string	ok \| empty-token \| jwt-expired \| invalid-token-format \| invalid-pm \| token-invalidated \| already-paid \| risk-blocked \| checkout-failed \| region-failed \| pm-unavailable \| snapshot-failed \| confirm-error \| confirm-failed \| approve-blocked \| no-redirect \| redirect-chain-failed \| payment-timeout \| aborted \| dump-only \| concurrency-busy \| feature-disabled \| unauthorized \| rate-limited \| bad-request \| server-error
retryable	bool	★ 失败时附带. `false` = 不可重试(同 token 重试也是同结果, 请换 token/账号或停止重试). `true` = 可重试(临时错: `concurrency-busy` / `rate-limited` / `server-error` / 网络类). 不可重试组: `already-paid` / `token-invalidated` / `jwt-expired` / `invalid-token-format` / `invalid-pm` / `unauthorized` / `feature-disabled` / `pm-unavailable` / `cdk-busy` / `approve-blocked`(2000 枪未过) / `no-redirect` / `redirect-chain-failed` / `risk-blocked` / `payment-timeout`(用户未付) / `aborted`(客户端断开) / `dump-only`(后台调试模式)
message	string?	面向终端用户的中文友好提示 (失败时附带)
kakao_qr_data	string	★ QR 字符串 — `https://online-payment.kakaopay.com/bridge/mobile-pc/reseller/subscription/issue/{hash}`. 用 KakaoTalk app 扫码会被识别为付款请求, 自动唤起流程. 跟 `pix_qr_data` / `upi_qr_data` 字段语义对齐
kakao_qr_image_url	string	★ QR PNG 图片 URL — 直接 `<img src="...">` 渲染. 跟 `pix_qr_image_url` / `upi_qr_image_url` 对齐. 内部走 GET /api/v1/kakao-pay/qr.png?d=<base64url> 无状态生成
qr_url	string	[兼容字段] 与 `kakao_qr_data` 同值, 老调用方继续可用. 新接入请用 `kakao_qr_data`
qr_https_url	string	iOS Safari fallback (`online-pay.kakaopay.com/pay/r1/{hash}`), 从 `ios_app_url` 解出。仅手机点击唤起 KakaoTalk, 不适合 PC 二维码
ios_app_url	string	移动端深链接 `kakaotalk://kakaopay/pg?...&url=...` — 移动浏览器内点击直接唤起 KakaoTalk
aos_app_url	string	Android Intent `intent://...#Intent;scheme=kakaotalk;...;end`
bridge_page_url	string	KakaoPay PC bridge 页面 URL (路径 `/bridge/pc/`, 浏览器打开看到 QR 图) — 不是扫码内容
kakaopay_bridge_url	string	同 bridge_page_url, 向后兼容字段
stripe_redirect_url	string	Stripe pm-redirects 中间链 (最保鲜, 备用)
kakao_tid	string	KakaoPay 交易 ID, 后续对账用
expired_at / expired_iso	int / string	QR 过期时间 (UTC 秒 / ISO), 通常 ~20 分钟有效
request_id / duration_ms	string / int	请求追踪 id / 总耗时毫秒
⚠ 超时提示	approve POOL 跑满可能耗时 ~3-5 分钟, HTTP 客户端超时请设为 ≥ 300秒。如需实时反馈, 推荐调 SSE 端点 /api/v1/kakao-pay/stream

curl -X POST \
  -H 'Authorization: Bearer YOUR_KR_TOKEN' \
  -H 'content-type: application/json' \
  -d '{"token":"eyJ...","poolKeep":50,"poolMax":2000}' \
  https://YOUR_HOST/api/v1/kakao-pay

POST /api/v1/kakao-pay/stream

POST/api/v1/kakao-pay/stream

KakaoPay 支付 SSE 实时进度流。鉴权 / 请求体同 /api/v1/kakao-pay。

SSE 事件	负载字段
event: hello	{request_id, pool_keep, pool_max, retry_count, queue_length, inflight, capacity}
event: progress · attempt-start	{type:"attempt-start", attempt, max}
event: progress · step	{type:"step", step:"<枚举>"} — step 枚举: `warmup` \| `sentinel` \| `checkout` \| `warmup-account` \| `region` \| `snapshot` \| `confirm` \| `approve` \| `polling` \| `redirect-chain` \| `bridge`
event: progress · approve-tick	{type:"approve-tick", slot, max, blocked, exception, other, elapsed_ms} — 每 50 枪采样一次
event: progress · approve-hit	{type:"approve-hit", slot} — 某一枪命中
event: progress · attempt-end	{type:"attempt-end", attempt, ok, reason, error}
event: done	精简响应体 — 与 POST /api/v1/kakao-pay 同样结构
: ping (注释行)	每 15s 一个 keep-alive, 越过代理/CDN 空闲超时

curl -N -X POST \
  -H 'Authorization: Bearer YOUR_KR_TOKEN' \
  -H 'content-type: application/json' \
  -d '{"token":"eyJ..."}' \
  https://YOUR_HOST/api/v1/kakao-pay/stream

POST /api/v1/naver-pay · 韩国 NaverPay

POST/api/v1/naver-pay

韩国 NaverPay 支付：输入 AC token → checkout (KR/KRW) → approve POOL 抢风控 → 跟 NicePay 8 hop → 拿到 NaverPay 启动页 + Stripe redirect。详见 /docs/naver-pay.md。

请求	类型	说明
Authorization	header?	Bearer <kr_service_token \| kr_business_token>。跟 KakaoPay 共用 token, 任一匹配即可。
token	string	AC token (必填, JWT 格式)
funding	string?	NaverPay 资金源 `card` \| `points` (默认 card; 也接受旧字段名 `naverFunding`)
promoId	string?	默认 plus-1-month-free
poolKeep / poolMax / retryCount	int?	同 /kakao-pay

响应	类型	说明
ok / reason	bool/string	ok \| empty-token \| jwt-expired \| invalid-token-format \| token-invalidated \| already-paid \| risk-blocked \| checkout-failed \| region-failed \| pm-unavailable \| snapshot-failed \| confirm-error \| confirm-failed \| approve-blocked \| no-redirect \| redirect-chain-failed \| invalid-funding \| payment-timeout \| aborted \| concurrency-busy \| feature-disabled \| unauthorized \| rate-limited \| bad-request \| server-error
retryable	bool	★ 失败时附带. `false` = 不可重试(同 token 重试也是同结果). `true` = 可重试(临时错). 字段语义同 KakaoPay (见上方)
funding	string	实际使用的资金源 (card / points)
naverpay_bridge_url	string	★ NaverPay 启动页 URL — 用浏览器跳转或手机点击都能进入 NaverPay app/网页支付
stripe_redirect_url	string	Stripe pm-redirects 中间链 (最保鲜, 备选)
nicepay_url	string	NicePay 启动页 (PC 浏览器完整跳转)
qr_url	string	兼容字段, NaverPay 当前 = naverpay_bridge_url
request_id / duration_ms	string / int	请求追踪 id / 耗时毫秒

curl -X POST \
  -H 'Authorization: Bearer YOUR_KR_TOKEN' \
  -H 'content-type: application/json' \
  -d '{"token":"eyJ...","funding":"card"}' \
  https://YOUR_HOST/api/v1/naver-pay

POST /api/v1/naver-pay/stream

POST/api/v1/naver-pay/stream

NaverPay 支付 SSE 实时进度流。鉴权 / 请求体同 /api/v1/naver-pay。

SSE 事件	负载字段
event: hello	{request_id, funding, pool_keep, pool_max, retry_count, queue_length, inflight, capacity}
event: progress · attempt-start / step / approve-tick / approve-hit / attempt-end	同 /kakao-pay/stream (枚举一致)
event: done	精简响应体 — 与 POST /api/v1/naver-pay 同样结构

curl -N -X POST \
  -H 'Authorization: Bearer YOUR_KR_TOKEN' \
  -H 'content-type: application/json' \
  -d '{"token":"eyJ...","funding":"card"}' \
  https://YOUR_HOST/api/v1/naver-pay/stream

POST /api/v1/kr-checkout · [兼容] 旧统一 KR 端点

POST/api/v1/kr-checkout

已拆分为 /api/v1/kakao-pay 与 /api/v1/naver-pay。仍可用以兼容旧调用 — 通过 body.pm 切换。新接入请使用拆分后的端点。

请求	类型	说明
token	string	AC token
pm	string?	`kakao_pay` \| `naver_pay` (默认 kakao_pay)
naverFunding	string?	NaverPay 资金源 (仅 pm=naver_pay)
其他	—	poolKeep / poolMax / retryCount / promoId 同上

响应字段是 KakaoPay + NaverPay 字段并集; 同步 + SSE (/api/v1/kr-checkout/stream) 都保留。

POST /api/v1/inbox

POST/api/v1/inbox

IMAP+OAuth2 连接 Outlook,拉取邮件列表 (所有邮件)。

请求	类型	说明
line	string?	单行: email----password----refresh_token----client_id
email / password / refreshToken / clientId	string?	分字段模式
folder	string?	默认 INBOX
limit	number?	默认 50, 上限 200

响应	类型	说明
ok / reason	bool/string	ok \| missing-email \| connect-failed \| fetch-failed
email / folder / total	string/number	元信息
messages	array	[{uid, subject, from, to, date, snippet}]

curl -X POST -H 'content-type: application/json' -d '{"line":"user@hotmail.com----pwd----rt----cid","limit":20}' https://YOUR_HOST/api/v1/inbox

POST /api/v1/inbox/message

POST/api/v1/inbox/message

获取单封邮件完整内容。

请求	类型	说明
凭据	-	同 /api/v1/inbox
folder	string?	默认 INBOX
uid	number	邮件 UID (必填)

响应	类型	说明
ok / subject / from / to / date	-	邮件元信息
text	string	纯文本正文
html	string	HTML 正文
attachments	array	[{filename, contentType, size}]

POST /api/v1/inbox/folders

POST/api/v1/inbox/folders

列出邮箱所有文件夹。

请求	说明
凭据	同 /api/v1/inbox

响应	说明
folders	[{path, name, specialUse, flags}]

POST /api/v1/totp/enable · ChatGPT 2FA 开通

POST/api/v1/totp/enable

用 ChatGPT accessToken + 同会话 sessionToken 自动调 OpenAI mfa/enroll → activate_enrollment → mfa_info 三步, 为账号开通 TOTP 二步验证, 返回原始 Base32 secret 与 otpauth URI。
★ 默认会把成功开通的 (email, secret) 持久化到 totp_secrets 表 (PK = email, 重复开通会覆盖), 供 /lookup 按邮箱查实时 OTP。可在 admin 后台 settings.totp_store_enabled=0 关闭落库。
★ 调用前需确保账号已设密码 (OAuth 注册账号默认无密码 — 先去 ChatGPT 设置加密码, 否则即使开 2FA 下次登录仍要邮箱接码)。
★ OpenAI 安全策略 recent_auth_required: 必须在「最近一次密码登录后 5~10 分钟内」操作, 否则返回 reason=recent-auth-required。

请求	类型	说明
token	string	必填 — `chatgpt.com/api/auth/session` 返回的 `accessToken` (eyJ 开头 JWT)
sessionToken	string?	推荐 — 同接口返回的 `sessionToken` (next-auth JWE), 服务端会自动拼成 `__Secure-next-auth.session-token=...` cookie
cookie	string?	高级 — 直接传完整 cookie 头, 优先级高于 `sessionToken`
deviceId	string?	可选 — `oai-device-id` 头, 不传则自动生成 UUID

响应	说明
ok	true / false
reason	ok / already-enabled / empty-token / invalid-token-format / jwt-expired / token-401 / recent-auth-required / enroll-failed / mfa-not-enabled / fetch-error / http-error
alreadyEnabled	true = 账号已绑 2FA (不重置), 仅返回 factor_id
secret	Base32 原始密钥 (新开通才返回)
otpauthUrl	`otpauth://totp/...` URI, 可生成二维码
factorId / sessionId	OpenAI 内部 ID
email / account_id / plan_type	从 JWT 解出的账号信息
persisted	true = 已落库 totp_secrets 表

curl -X POST -H 'content-type: application/json' \
  -d '{"token":"eyJhbGciOi...","sessionToken":"eyJhbGciOiJkaXIi..."}' \
  https://YOUR_HOST/api/v1/totp/enable

POST /api/v1/totp/code · 本地 OTP 生成

POST/api/v1/totp/code

纯本地 RFC 6238 计算 (HMAC-SHA1, 30s 周期, 6 位), 输入 Base32 secret 返回当前 OTP 与剩余秒数。不发任何外网请求, 不查询/落库任何数据。也支持 GET /api/v1/totp/code?secret=...。

请求	类型	说明
secret	string	Base32 密钥 (A-Z 2-7, 可带空格 / 小写, 服务端自动 normalize)

响应	说明
code	6 位 OTP
secondsRemaining	当前 OTP 还能用几秒
period / digits / algorithm / epoch	固定 30 / 6 / sha1 / unix 秒
secretMasked / otpauthUrl	用于显示 / 二维码

curl -X POST -H 'content-type: application/json' \
  -d '{"secret":"JBSWY3DPEHPK3PXP"}' \
  https://YOUR_HOST/api/v1/totp/code

POST /api/v1/totp/lookup · 按邮箱查实时 OTP

POST/api/v1/totp/lookup

默认开放查询 (仅 IP 限速保护), 输入邮箱即可拿到该账号当前 OTP。
★ 仅能查通过 /enable 在本站开通过 2FA 的账号 (secret 必须先落库)。
★ admin 后台可配 settings.totp_lookup_token 切换为强保护模式 — 配了之后必须传 key 才能查。
★ IP 级 RPM 限速 (默认 20 RPM/IP), 超出返回 HTTP 429 + reason=rate-limited。在 admin 后台 settings.rate_rpm_totp_lookup 调整 (-1 = 不限, 0 = 继承全局)。

请求	类型	说明
email	string	必填 — 已开通过 2FA 的账号邮箱 (大小写不敏感)
key	string?	查询密钥; 仅在 admin 配了 `totp_lookup_token` 时必填

响应	说明
ok	true / false
reason	ok / not-found / unauthorized / invalid-email / invalid-stored-secret / totp-fail / rate-limited / server-error
code	当前 6 位 OTP
secondsRemaining	OTP 剩余可用秒数
secret / secretMasked / otpauthUrl	原始密钥 / 打码版 / 二维码 URI
email / account_id / plan_type / factor_id	账号信息
created_at / updated_at	首次开通 / 最近一次更新时间

# 默认开放模式
curl -X POST -H 'content-type: application/json' \
  -d '{"email":"user@example.com"}' \
  https://YOUR_HOST/api/v1/totp/lookup

# 强保护模式 (admin 配了 totp_lookup_token)
curl -X POST -H 'content-type: application/json' \
  -d '{"email":"user@example.com","key":"tlt_xxxx"}' \
  https://YOUR_HOST/api/v1/totp/lookup

GET /api/v1/channels

GET/api/v1/channels

渠道存活榜单 (公开只读, 匿名可访问)。返回各渠道账号的订阅存活状态。严格脱敏 — 不含任何 token / refresh_token / client_id / account_id / email。数据由后台定时刷新。

响应	类型	说明
ok	bool	是否成功
last_refreshed_at	string?	最后一次刷新时间 (ISO)
channels	array	渠道列表 (见下)
channels[].label	string	渠道备注名
channels[].status	string	alive_paid \| alive_free \| expiring \| dead \| error \| pending
channels[].plan_type	string?	套餐 (free/plus/pro/team)
channels[].active_start / expires_at	string?	开通 / 截止时间
channels[].days_left	number?	剩余天数
channels[].will_renew / is_delinquent	bool	是否续费 / 是否欠费
channels[].purchase_origin_platform	string?	渠道来源 (chatgpt_web/ios/android)

curl https://YOUR_HOST/api/v1/channels

GET /api/v1/stats

GET/api/v1/stats

全局统计 (需鉴权)。

响应	说明
total / eligible / not_eligible / ac_invalid / errors	累计计数
success_rate	0~1
uptime_sec / since_sec	运行/统计时长

GET /healthz

GET/healthz

探活,无需鉴权。

{"ok":true,"service":"ac-checker","brand":"Nerver","time":1780024498,"promo_id":"plus-1-month-free","stats":{"total":1234,"eligible":800}}

通用说明

鉴权	设置 AUTH_TOKEN 后, /api/v1/* 需带 Authorization: Bearer xxx 或 ?key=xxx
限流	单 IP 60 次/分钟, 超限 429 + retry-after
CORS	默认 *, 可通过 CORS_ORIGIN 限制
超时	OpenAI 30s, IMAP 60s
批量上限	/api/v1/check 最多 50 token
错误格式	{"ok":false,"reason":"...","error":"...","message":"..."}
message 字段	失败响应附带的中文友好提示 (面向终端用户)。客户端建议优先显示 `message`, 回退到 `reason`。`reason` 字段不变, 完全向后兼容。
机器可读	GET /api/v1/docs 返回完整 JSON 契约