海外子账号-编辑

本文档介绍海外代理子账号管理系列接口，支持子账号的编辑操作，涵盖请求参数、响应格式及完整错误码说明。

一、公共说明

1.1 请求域名

所有 OpenAPI 接口统一通过以下域名访问：

https://openapi.fanproxy.com

1.2 请求头要求

所有 OpenAPI 接口均通过 网关（Gateway） 进行签名认证，请求必须携带以下请求头。

• 必填请求头

请求头名称	类型	必填	说明
X-Api-Key	String	是	用户账号，即手机号
X-Api-Signature	String	是	API 签名凭证，由平台生成，可前往官网控制台查看
X-Api-Timestamp	String	是	请求时间戳（秒），用于防重放攻击

• 请求头示例

1.3 统一响应格式

所有接口均返回统一的 JSON 结构，便于客户端统一解析处理：

• 响应字段说明

字段	类型	说明
code	Integer	状态码，200 表示成功
success	Boolean	操作是否成功，true / false
data	Object/Array/null	响应数据，成功时返回业务数据，失败时为 null
message	String	错误描述信息，成功时为 null

• 成功响应示例
• 失败响应示例

1.4 错误码说明

业务层统一使用 OpenApiApiExceptionEnum（一般为 2000xxxx 段）。部分接口在调用内部 Facade 失败时，会透传下游返回的 code 与 message（非 200 且非下表枚举值时，以响应体为准）。

• 全局错误码表

错误码	说明	来源
200	成功	业务层
401	签名认证失败（缺少 Key、签名无效、请求过期、重复请求等）	网关层
20000001	用户信息缺失（如缺少 X-Api-User-Id）	业务层（@OpenApiAuth 校验 / 子账号锁）
20000002	缺少开放接口账号头信息（缺少 X-Api-App-Key）	业务层（@OpenApiAuth）
20000003	用户中心查询失败	业务层（@OpenApiAuth）
20000004	密钥与签名归属账号不一致	业务层（@OpenApiAuth）
20000005	系统繁忙，请稍后重试（或同类前缀的详细 message）	业务层（通用失败/异常兜底）
20000101	操作频繁，请稍候（子账号接口分布式锁未获取到）	业务层
20000102	子账号不存在	业务层
20000301	未找到指定的子账号（认证账号流量信息）	业务层
20001001~20001014	参数校验（账户名、密码、套餐类型、时间等；含流量记录时间窗与区间）	业务层
20002001	无效的套餐类型（订单查询 mealType）	业务层
其他整数	内部服务 R 返回的非 200 code	下游 Facade

网关认证失败（401）时的响应体格式：

二、编辑子账号

接口地址：POST /open-api/open/overseas/subaccount/edit

接口描述：编辑子账号的密码、状态、使用上限等信息。

2.1 请求参数（Body - JSON）

参数名	类型	必填	说明
authAccount	String	是	子账号账号名
authPassword	String	是	新密码，数字或字母，6~8 位
status	Boolean	是	状态：true-正常，false-禁用
useLimit	BigDecimal	否	使用上限（单位：G）
remark	String	否	备注，不超过 100 个字符

2.2 请求示例

2.3 返回字段说明

与本接口 1.1 一致，data 字段固定为 null，仅通过 code 和 success 判断是否成功。

2.4 返回示例

2.5 错误码

错误码	说明 / 触发条件
200	成功
401	网关签名认证失败
20000001	缺少 X-Api-User-Id（@OpenApiAuth 或子账号锁）
20000002	缺少 X-Api-App-Key
20000003	用户中心查询失败
20000004	密钥与签名归属账号不一致
20000101	操作频繁（子账号锁）
20000005	锁中断或系统异常（message 如「编辑子账号异常: …」）
20001001	账户名为空
20001002	账户名格式须为 6～10 位数字或字母
20001003	密码为空
20001004	密码须为 6～8 位数字或字母
20001006	状态（status）为空
20000102	当前用户下不存在该子账号
非 200	保存/更新 Facade 失败时透传下游 code 与 message