保存指定平台国家充值配置¶
请求参数¶
后台公共头固定admin/web/admin_web,独立管理员Cookie;App Bearer不能替代。OWNER拥有ADMIN_RECHARGE_READ和ADMIN_RECHARGE_WRITE,VIEWER只有ADMIN_RECHARGE_READ。写请求还必须同源Origin及X-Admin-CSRF。
路径与读取接口相同。请求正文为完整配置:
| 字段 | 必填/约束 | 说明 |
|---|---|---|
| currency | 是,大写三位 | 必须在配置目录currencies内 |
| expectedVersion | 是,JSON整数≥0 | 最近读取的该组version,不接受字符串或小数 |
| packages | 是,数组0–20项 | 全量替换,省略的旧套餐移除 |
| packages[].id | 可空,UUID | 新增省略或null;已有ID必须属于本组当前配置,不接受自行生成或已移除ID |
| packages[].diamonds | 是,JSON整数1–1000000000 | 同组数量唯一 |
| packages[].priceMinor | 是,JSON整数1–1000000000 | 最小货币单位,199 USD=1.99美元,199 JPY=199日元 |
| packages[].sortOrder | 是,JSON整数0–100000 | 展示排序 |
不接受enabled、paid、balance等未知字段。禁止负数、0价格、小数/指数数值、字符串金额、重复ID及重复钻石档位。
所有请求必须携带 Accept-Language 和八项公共头:X-Client-Type、X-Platform、X-App-Version、X-App-Build、X-Channel、X-Device-Id、X-Request-Id、X-Request-Timestamp。安装ID持久化、请求ID每次新建、时间戳为当前Unix毫秒。正式HTTPS与AES/JWE必需;GET使用X-Budyoo-JWE、PUT使用application/jose。以下展示加密前/解密后的业务内容,不是明文生产请求。
请求示例¶
示例客户端准备的完整请求头(实际凭据与JWE由统一传输层生成,示例值不应复用):
Accept-Language: zh-CN
X-Client-Type: admin
X-Platform: web
X-App-Version: 1.0.0
X-App-Build: 1
X-Channel: admin_web
X-Device-Id: 00000000-0000-4000-8000-000000000001
X-Request-Id: 00000000-0000-4000-8000-000000000002
X-Request-Timestamp: <发送时的13位Unix毫秒>
Cookie: <浏览器自动携带的管理员会话>
Content-Type: application/jose
Origin: <后台同源Origin>
X-Admin-CSRF: <当前管理员csrfToken>
PUT /api/v1/admin/recharge/android/us
{"currency":"USD","expectedVersion":0,"packages":[{"diamonds":60,"priceMinor":199,"sortOrder":0}]}
成功响应¶
HTTP200,标准外层code=SUCCESS、message为本地化提示、data如下、errors=[],Cache-Control:no-store。
{"platform":"android","country":"us","currency":"USD","currencyScale":2,"version":1,"updatedAt":"2026-11-06T00:00:00Z","packages":[{"id":"00000000-0000-4000-8000-000000000001","diamonds":60,"priceMinor":199,"sortOrder":0}]}
| 字段 | 类型/约束 | 说明 |
|---|---|---|
| platform/country | string | android或ios/目录中的小写两位国家代码 |
| currency | string或null | ISO币种;从未配置为null |
| currencyScale | integer,0–4 | 最小货币单位精度;JPY=0,USD/CNY=2,KWD=3;从未配置为0 |
| version | integer≥0 | 当前配置组版本,从未配置为0;每次保存加1,清空不重置 |
| updatedAt | ISO时间或null | 服务端保存时间,从未配置为null |
| packages | object[],0–20项 | 按sortOrder升序、id升序返回;为空不代表请求失败 |
| packages[].id | UUID | 服务端生成的套餐编号 |
| packages[].diamonds | integer,1–1000000000 | 钻石数量,同组不能重复 |
| packages[].priceMinor | integer,1–1000000000 | 最小货币单位金额,禁止浮点或字符串数字 |
| packages[].sortOrder | integer,0–100000 | 越小越靠前,可相同,以id稳定排序 |
失败响应¶
| HTTP | code | 条件 |
|---|---|---|
| 400 | INVALID_RECHARGE_CONFIGURATION | 平台、国家、币种、套餐范围或编号归属无效 |
| 400 | BAD_REQUEST/VALIDATION_FAILED/INVALID_CLIENT_HEADERS | JSON、字段类型/范围或公共头无效 |
| 400 | ENCRYPTION_REQUIRED/INVALID_ENCRYPTED_REQUEST | 缺少或无效JWE |
| 401/403 | UNAUTHORIZED/FORBIDDEN | 会话、安装绑定或权限校验失败 |
| 426/429 | HTTPS_REQUIRED/TOO_MANY_REQUESTS | 传输或限流拒绝 |
| 503 | SERVICE_UNAVAILABLE | 数据库或Redis不可用,不解释为空套餐 |
code固定;message和字段错误支持中英日韩,缺省/未知语言回退英文。
409 RECHARGE_CONFIGURATION_CONFLICT表示该组已经更新。403 ADMIN_CSRF_INVALID表示来源或CSRF未通过。
接入说明¶
该原平台入口保留原配置数据及版本,响应新增channel=null。正式后台改用渠道国家读取和渠道国家保存,两套配置独立,不互相覆盖。
后台按Android/iOS → 国家 → 套餐管理。同平台不同国家和不同平台相互隔离,不提供全局或分组充值开关。保存只改变套餐展示,不创建订单、核验付款、增加余额或授予VIP。国家参数是显式选择,不证明真实支付市场;IP、商店国家与自动匹配均未接入。不提供其他平台/国家回退或样例套餐。
同平台国家通过事务锁串行、版本校验、配置与RECHARGE_CONFIGURATION_SAVE审计同事务提交。审计失败不留配置修改。409或写入结果不确定时保留草稿,先重新读取核对,不自动改版本重试;不修改真实用户钱包。
2026-11-06服务器clean verify共768项全部通过,包含渠道白名单、Google三国、Apple四国含中国大陆、其他有效国家的美国展示兜底、无国家/无效国家、旧报价保留、越界读写及整批回滚。后台13项隔离交互及24组四语布局通过;真实受信HTTPS/JWE的6项页面检查、24组布局和6项只读接口核对通过,业务写入为0。运行库全部原有报价、套餐编号及版本的前后摘要一致。App配套19项相关测试与定向静态分析通过,未安装或运行设备;商店商品绑定、国家识别、订单核验和真实支付按用户安排留到最后接入。
真实后台验收使用本站明确受信证书,JSON经真实JWE认证解密。本次仅调整可运营国家及展示回退,保留既有报价、版本和审计,不批量重写套餐。