PUT/api/v1/admin/recharge/{platform}/{country}
管理员Cookie、HTTPS、JWE、同源CSRF、ADMIN_RECHARGE_WRITEJSON 响应接入指南 ↗

保存指定平台国家充值配置

请求参数

后台公共头固定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认证解密。本次仅调整可运营国家及展示回退,保留既有报价、版本和审计,不批量重写套餐。