端点清单

全部客户 API 端点，按功能分组，标注认证要求。

这一篇是端点索引。认证机制、Origin 要求、响应结构和分页约定在认证与调用约定。

系统与公开入口

方法	路径	用途	认证
`GET`	`/healthz`	存活检查	公开
`GET`	`/readyz`	MySQL / Redis 就绪检查	公开
`GET`	`/api/v1/settings/public`	公开站点配置	公开
`GET`	`/api/v1/proxy/extract`	提取代理	API Key + 白名单
`GET`	`/api/v1/client-ip`	查询调用方出口 IP	客户

认证

方法	路径	用途	认证
`GET`	`/api/v1/auth/registration-policy`	注册策略	公开
`GET`	`/api/v1/auth/challenge/config`	人机验证配置	公开
`POST`	`/api/v1/auth/challenge/ticket`	获取验证票据	公开
`POST`	`/api/v1/auth/register/code`	发送注册验证码	公开
`POST`	`/api/v1/auth/register`	注册并登录	公开
`POST`	`/api/v1/auth/login`	密码登录	公开
`POST`	`/api/v1/auth/login/two-factor`	两步验证第二步	公开
`POST`	`/api/v1/auth/refresh`	换取新 access token	refresh Cookie
`POST`	`/api/v1/auth/logout`	注销当前会话	客户
`POST`	`/api/v1/auth/logout-all`	注销全部会话	客户
`GET`	`/api/v1/auth/me`	当前用户信息	客户
`POST`	`/api/v1/auth/password/reset/code`	发送重置密码验证码	公开
`POST`	`/api/v1/auth/password/reset`	重置密码	公开
`POST`	`/api/v1/auth/change-password/code`	发送改密验证码	客户
`POST`	`/api/v1/auth/change-password`	改密（撤销旧会话）	客户
`GET`	`/api/v1/auth/oauth/:provider/start`	OAuth 发起	公开
`GET`	`/api/v1/auth/oauth/:provider/callback`	OAuth 回调	公开

两步验证

方法	路径	用途
`GET`	`/api/v1/auth/two-factor`	TOTP 状态
`POST`	`/api/v1/auth/two-factor/setup`	创建 TOTP 密钥
`POST`	`/api/v1/auth/two-factor/confirm`	确认启用
`DELETE`	`/api/v1/auth/two-factor`	关闭（需验证 TOTP）

方法	路径	用途
`GET`	`/api/v1/proxy/accounts`	列表（`pageSize` 默认 10）
`POST`	`/api/v1/proxy/accounts`	创建
`PATCH`	`/api/v1/proxy/accounts/:id`	修改（状态、流量上限、备注）
`DELETE`	`/api/v1/proxy/accounts/:id`	软删除（状态改为 `deleted`）

方法	路径	用途
`GET`	`/api/v1/proxy/ip-whitelist`	列表
`POST`	`/api/v1/proxy/ip-whitelist`	添加（每账号上限 10 条）
`DELETE`	`/api/v1/proxy/ip-whitelist/:id`	删除

方法	路径	用途
`GET`	`/api/v1/proxy/usage/summary`	余额、累计购买、本月与上月计费量
`GET`	`/api/v1/proxy/usage/daily`	逐日统计（1–90 天）
`GET`	`/api/v1/proxy/usage/series`	用量曲线，可按目标域名筛选
`GET`	`/api/v1/proxy/usage/domains`	访问过的域名（最多 500 个）

地理目录

拿定位参数的准确写法用这几个接口，别猜。

方法	路径	用途
`GET`	`/api/v1/proxy/geography/catalog`	完整目录
`GET`	`/api/v1/proxy/geography/countries`	国家列表
`GET`	`/api/v1/proxy/geography/countries/:countryCode/states`	某国的州省
`GET`	`/api/v1/proxy/geography/states/:stateId/cities`	某州省的城市

公开版本（不需要登录）：

方法	路径
`GET`	`/api/v1/catalog/geography/countries`
`GET`	`/api/v1/catalog/geography/countries/:countryCode/states`

产品目录与下单

公开目录

方法	路径	产品线
`GET`	`/api/v1/catalog/residential`	动态住宅
`GET`	`/api/v1/catalog/static-residential/countries`	静态住宅
`GET`	`/api/v1/catalog/static-datacenter/countries`	数据中心
`GET`	`/api/v1/catalog/unlimited-residential`	不限量住宅

动态住宅

方法	路径	用途
`GET`	`/api/v1/residential/catalog`	目录
`POST`	`/api/v1/residential/quote`	询价（报价 5 分钟有效）
`POST`	`/api/v1/residential/purchases`	下单
`GET`	`/api/v1/residential/purchases`	订单列表

静态住宅

方法	路径	用途
`GET`	`/api/v1/static-residential`	已持有的资源
`GET`	`/api/v1/static-residential/countries`	国家与库存
`POST`	`/api/v1/static-residential/orders`	下单

数据中心

方法	路径	用途
`GET`	`/api/v1/static-datacenter`	已持有的资源
`GET`	`/api/v1/static-datacenter/countries`	国家与库存

不限量住宅

方法	路径	用途
`GET`	`/api/v1/unlimited-residential/catalog`	套餐目录
`GET`	`/api/v1/unlimited-residential/orders`	订单列表

支付与钱包

方法	路径	用途
`GET`	`/api/v1/wallet`	余额与最近账本
`GET`	`/api/v1/payments/methods`	可用支付方式
`GET`	`/api/v1/payments/channels`	支付渠道
`POST`	`/api/v1/payments/topups`	创建充值单
`GET`	`/api/v1/payments/topups/:id`	查询充值单
`POST`	`/api/v1/payments/checkouts`	创建结账单（30 分钟过期）
`GET`	`/api/v1/payments/checkouts/:id`	查询结账单
`POST`	`/api/v1/payments/checkouts/:id/retry`	重试结账
`GET`	`/api/v1/promotions/available`	可用优惠
`GET`	`/api/v1/transactions`	交易记录（分页）
`GET`	`/api/v1/transactions/metrics`	充值 / 消费 / 退款指标

方法	路径	用途
`POST`	`/api/v1/proxy/traffic-cdks`	生成
`GET`	`/api/v1/proxy/traffic-cdks`	列表
`GET`	`/api/v1/proxy/traffic-cdks/metrics`	统计
`POST`	`/api/v1/proxy/traffic-cdks/redeem`	兑换（20 次/分钟）
`GET`	`/api/v1/proxy/traffic-cdks/:id/secret`	查看明文
`POST`	`/api/v1/proxy/traffic-cdks/:id/cancel`	作废

方法	路径	用途
`GET`	`/api/v1/notifications`	站内通知列表
`POST`	`/api/v1/notifications/:id/read`	标记已读
`POST`	`/api/v1/notifications/read-all`	全部标记已读
`GET`	`/api/v1/notification-channels`	通知渠道列表
`POST`	`/api/v1/notification-channels`	创建渠道
`PATCH`	`/api/v1/notification-channels/:id`	修改渠道
`DELETE`	`/api/v1/notification-channels/:id`	删除渠道
`GET`	`/api/v1/traffic-alert-settings`	流量预警设置
`PUT`	`/api/v1/traffic-alert-settings`	更新流量预警

推广

方法	路径	用途
`GET`	`/api/v1/affiliate`	推广概览
`PUT`	`/api/v1/affiliate/code`	设置推广码
`POST`	`/api/v1/affiliate/convert`	佣金转入钱包
`POST`	`/api/v1/affiliate/withdrawals`	申请提现（USDT）
`GET`	`/api/v1/affiliate/withdrawals`	提现记录
`GET`	`/api/v1/affiliate/referrals/:code`	校验推广码（公开）

客服工单

方法	路径	用途
`GET`	`/api/v1/support/tickets`	工单列表
`POST`	`/api/v1/support/tickets`	创建（未关闭上限 20 个）
`GET`	`/api/v1/support/tickets/:id`	详情
`POST`	`/api/v1/support/tickets/:id/replies`	回复
`POST`	`/api/v1/support/tickets/:id/close`	关闭
`GET`	`/api/v1/support/chat-identity`	在线客服签名身份

Telegram 绑定

方法	路径	用途
`GET`	`/api/v1/telegram/binding`	绑定状态
`POST`	`/api/v1/telegram/bind-code`	获取绑定码
`DELETE`	`/api/v1/telegram/binding`	解绑

控制台聚合接口

这些是给控制台页面用的聚合视图，一次返回一个页面需要的全部数据。自己写集成时通常用上面的细粒度接口更合适。

方法	路径
`GET`	`/api/v1/dashboard/header`
`GET`	`/api/v1/dashboard/home`
`GET`	`/api/v1/dashboard/generator`
`GET`	`/api/v1/dashboard/rotating`
`GET`	`/api/v1/dashboard/wallet`
`GET`	`/api/v1/dashboard/checkout-context`
`GET`	`/api/v1/dashboard/account-settings`

不对外的路由

以下路由不是客户 API，列在这里是为了避免误用：

/internal/gateway/v1/* —— 网关数据面与控制面之间的内部接口，需要网关专用 token
/api/v1/admin/* —— 管理端接口，需要管理员角色
/api/v1/payments/*/notify、/webhook —— 支付渠道回调，靠签名校验
/api/v1/telegram/webhook/:secret —— Telegram Bot 回调
/metrics —— Prometheus 指标，需要网关 token

这里的 401 / 403 是 REST 接口鉴权或访问校验。代理 HTTP / CONNECT 的凭据错误使用 407，参数 400、额度 402、账号/策略 403、并发 429、内部 500、连接失败 502、暂不可用 503、连接超时 504；通过 X-NextProxy-Error 读取细分原因。SOCKS5 使用协议协商码。见错误码对照。

端点清单

系统与公开入口

认证

两步验证

代理子账号

IP 白名单

用量统计

地理目录

产品目录与下单

公开目录

动态住宅

静态住宅

数据中心

不限量住宅

支付与钱包

流量 CDK

通知

推广

客服工单

Telegram 绑定

控制台聚合接口

不对外的路由

代理端口的错误另行判断

这一类的其他文档