对接说明

存活探活。正式环境需 UC JWT；响应头可带 X-Request-Id。

请求头

Authorization	必填（正式 RS）：Bearer <UC access_token>

入参

无 Query / Body。

成功响应 · 200

{
  "status": "UP"
}

错误

401	无/无效 JWT

校验 UC JWT 并回显解析到的身份。不建户、不返回余额，适合联调冒烟。

请求头

Authorization	必填：Bearer <UC access_token>

入参

无 Query / Body。

成功响应 · 200

{
  "tenantId": "1",
  "userCode": "u_abc",
  "subject": "…",
  "clientId": "ftcs-desktop"
}

tenantId / userCode	必有；计费账户绑定键
subject / clientId	有 claim 时返回

错误

401	无/坏 Token，或缺少 tenant_id / user_code

按 name 签发或重置网关 API Key。无该 name → 创建（action=created）；已有 → 原地更新哈希，旧 sk 立即失效（action=rotated）。每次成功响应都含新明文。

请求头

Authorization	必填：Bearer <UC access_token>
Content-Type	application/json

入参 · Body

{
  "name": "ftcs-desktop"
}

name	必填。trim 后转小写，再校验：长度 1～64，仅 [a-z0-9._-]。非法 → 400 invalid_name。

成功响应 · 200

{
  "action": "created",
  "name": "ftcs-desktop",
  "api_key": "sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "prefix": "sk-xxxx",
  "status": "active",
  "user": {
    "tenant_id": "1",
    "user_code": "u_abc",
    "balance_li": 0,
    "status": "active"
  }
}

action	created | rotated
api_key	明文 sk；仅本响应返回，勿记入日志
prefix	与库中展示前缀一致（明文前 10 字符）
user.*	账户摘要；新建余额为 0

错误

401	无/坏 UC JWT
400	name 缺失或非法（invalid_name）
403	账户 disabled（account_disabled）
409	唯一冲突重试耗尽（极少）
500	未配置 GATEWAY_KEY_PEPPER

用 UC JWT 换取官方通道充值用的短时 ticket（前缀 rt_）。服务端只存哈希；明文仅本响应返回一次。过期前可多次用于充值页、微信 prepay / 查单。禁止把长效 access_token 挂在充值 URL。

请求头

Authorization	必填：Bearer <UC access_token>

入参

无 Query / Body。

成功响应 · 200

{
  "ticket": "rt_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "expires_in": 300,
  "expires_at": "2026-08-05T14:22:00.000Z"
}

ticket	明文 rt_ + Base64URL；仅本响应返回，勿记入日志
expires_in	有效秒数（与配置 TTL 一致；默认 300）
expires_at	UTC 到期时刻（ISO-8601）

错误

401	无/坏 UC JWT，或缺少身份 claim
429	同身份每小时签发超过 20 张（recharge_ticket_rate_limited）
503	未配置 GATEWAY_KEY_PEPPER（missing_gateway_key_pepper）

网关托管充值页。带 ?ticket=rt_… 时验票并 Set-Cookie 后 302 去 query；无有效 Cookie 时展示「缺少登录凭证」。页内调用下方 prepay / 查单。

微信 Native 预下单，返回付款码串 code_url。鉴权：Cookie tg_recharge_ticket 或 Authorization: Bearer rt_…（Cookie 优先）；不用 UC JWT / sk。

Body

{ "amount_yuan": 50.00 }

amount_yuan	必填；1.00～100.00，最多两位小数

成功 · 200

{
  "out_trade_no": "tg…",
  "code_url": "weixin://wxpay/bizpayurl?pr=…",
  "amount_yuan": "50.00",
  "amount_fen": 5000,
  "amount_li": 50000,
  "expires_in": 7200,
  "status": "created"
}

错误

401	invalid_recharge_ticket
400	invalid_amount / invalid_body
503	wechat_pay_unavailable（未启用或缺配置）
502	wechat_prepay_failed

微信支付结果通知。官方 SDK 验签解密。按 trade_state 处理：SUCCESS 幂等入账；CLOSED/REVOKED/PAYERROR 等将未入账单推到 closed/failed；中间态不改库。鉴权为微信签名，勿带 ticket / JWT / sk。

成功应答（微信约定）

{ "code": "SUCCESS", "message": "成功" }

按商户订单号读本地订单（须 ticket 且身份匹配，否则 404）。入账后可见 status=credited。主动查微信见下方 sync。

用户「我已支付」主动查单：向微信 queryOrderByOutTradeNo，再走与 notify 相同的 applyTradeState（写 last_sync_*）。本地已 credited/closed 可短路不查微信。鉴权同 prepay（ticket）。

成功 · 200（示例）

{
  "out_trade_no": "tg…",
  "status": "credited",
  "trade_state": "SUCCESS",
  "amount_yuan": "50.00",
  "amount_li": 50000,
  "credited_li": 50000,
  "balance_li": 125000,
  "last_sync_trade_state": "SUCCESS",
  "last_sync_result": "CREDITED"
}

错误

401	invalid_recharge_ticket
404	order_not_found（无单或不属于当前身份）
429	sync_rate_limited
503	wechat_pay_unavailable
502	wechat_query_failed

OpenAI 兼容 Chat：非流式 JSON 或 stream=true SSE，转发 DeepSeek 白名单模型。默认白名单：deepseek-v4-flash、deepseek-v4-pro（可配）。

请求头

Authorization	必填：Bearer sk-…
Content-Type	application/json

入参 · Body（代理层规则）

{
  "model": "deepseek-v4-flash",
  "messages": [{"role": "user", "content": "Hello"}],
  "stream": false
}

model	必填；须在白名单，否则 400 model_not_allowed
stream	缺省 / false → JSON；true → SSE（出站强制 include_usage=true）
其他	透传上游

成功响应

非流式：透传上游 JSON。流式：text/event-stream，透传 data: 事件至 [DONE]。

本阶段常见错误

401	missing_authorization / invalid_authorization / invalid_api_key
403	key_disabled / account_disabled
402	insufficient_balance（网关用户余额不足；非上游额度）
400	model_required / model_not_allowed
503	未配置 DEEPSEEK_API_KEY 或 GATEWAY_KEY_PEPPER
502/504	上游错误 / 超时（含上游限流等，短码 upstream_*）

用网关 sk 查询当前账户余额（厘）。本期不含今日用量汇总。余额为 0 / 负仍返回 200（不做预检）。

请求头

Authorization	必填：Bearer sk-…

成功响应 · 200

{
  "user_id": 20,
  "tenant_id": "1",
  "user_code": "u_abc",
  "balance_li": 12340,
  "currency": "CNY",
  "currency_subunit": "li",
  "li_per_yuan": 1000,
  "key": { "name": "ftcs-desktop", "prefix": "sk-ab12" }
}

错误

401 / 403 / 503	同 Chat sk 鉴权

返回配置白名单与有效价目的交集（OpenAI list 形态）。鉴权：网关 sk。不含单价。

请求头

Authorization	必填：Bearer sk-…

成功响应 · 200

{
  "object": "list",
  "data": [
    { "id": "deepseek-v4-flash", "object": "model", "owned_by": "deepseek" },
    { "id": "deepseek-v4-pro", "object": "model", "owned_by": "deepseek" }
  ]
}

列出当前用户 Key 元信息（不含明文）。