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 → 上游协议 → 返回授权跳转 URL / 扫码内容 / 托管页。支持 POOL 抢风控, 内部账单地址按后台开关切换 (NL/JP/随机)。

请求	类型	说明
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 \| concurrency-busy \| feature-disabled \| unauthorized \| rate-limited \| bad-request \| server-error
message	string?	面向终端用户的中文友好提示 (失败时附带)
next_action_type	string	redirect_to_url
ideal_redirect_url	string	★ 授权跳转链接 (浏览器打开继续后续步骤)
ideal_qr_url	string	扫码授权 URL (优先用此渲染二维码; 为空则用 redirect_url)
ideal_hosted_url	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

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`
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 · 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

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 \| 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 \| concurrency-busy \| feature-disabled \| unauthorized \| rate-limited \| server-error
message	string?	面向终端用户的中文友好提示 (失败时附带)
qr_url	string	★ PC 网页二维码实际编码内容 — `https://online-payment.kakaopay.com/bridge/mobile-pc/reseller/subscription/issue/{hash}`. 用 KakaoTalk app 扫码会被识别为付款请求, 自动唤起流程. 直接用 qrcode 库渲染这个 URL 即可
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 \| concurrency-busy \| feature-disabled \| unauthorized \| rate-limited \| server-error
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}]

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 契约