读取钱包充值套餐¶
请求参数¶
App公共头为app/android或ios及当前会话绑定渠道,Bearer、安装及平台必须与会话一致。平台从已校验X-Platform读取,不允许query覆盖。可选查询country为目录中的小写两位国家代码;不传只读可选国家,传入则按渠道运营范围解析配置。国内七渠道仅cn,其他国家返回400;Google为us/jp/kr,Apple为cn/us/jp/kr,商店渠道其余有效国家读取同渠道us配置,无效代码仍400,不跨渠道借价。
所有请求必须携带 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: app
X-Platform: android
X-App-Version: 1.0.0
X-App-Build: 1
X-Channel: dev
X-Device-Id: 00000000-0000-4000-8000-000000000001
X-Request-Id: 00000000-0000-4000-8000-000000000002
X-Request-Timestamp: <发送时的13位Unix毫秒>
Authorization: Bearer <当前会话accessToken>
X-Budyoo-JWE: <本请求GET信封>
本例dev仅用于非prod配置下的开发联调;正式包使用对应发行渠道,iOS固定app_store。
GET /api/v1/me/wallet/recharge 或 GET /api/v1/me/wallet/recharge?country=us。例如Google请求country=de时,selectedCountry与configuration.country均为us;Apple请求country=cn仍为cn。统一客户端注入当前会话Bearer及完整公共头,不保存请求凭据。
成功响应¶
HTTP200,标准外层code=SUCCESS、message为本地化提示、data如下、errors=[],Cache-Control:no-store。
| data字段 | 类型/约束 | 说明 |
|---|---|---|
| platform | android或ios | 当前会话平台 |
| countries | object[] | 当前渠道运营范围内至少有一档套餐的国家,空配置不列出;国内每渠道最多1国(cn)、Google最多3国、Apple最多4国 |
| countries[].id/name/names/flagUrl | string/string/object/string | 小写国家代码、当前语言名称、四语名称、国旗相对路径 |
| selectedCountry | string或null | 实际配置国家;未传为null,Google/Apple范围外有效国家返回us |
| requestedCountry | string或null | 原样回显本次显式country参数;未传为null,用于核对请求,可能与selectedCountry不同 |
| configuration | object或null | 未传国家为null,已传国家返回下表完整配置,即使未配置 |
configuration对象:
| 字段 | 类型/约束 | 说明 |
|---|---|---|
| platform/country | string | android或ios/目录中的小写两位国家代码 |
| channel | string或null | 正式发行渠道代码,旧平台独立配置为null |
| 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–1000000000000,旧平台1–1000000000 | 最小货币单位金额,禁止浮点或字符串数字 |
| packages[].sortOrder | integer,0–100000 | 越小越靠前,可相同,以id稳定排序 |
首次无配置的示例:
{"platform":"android","countries":[],"selectedCountry":null,"configuration":null,"requestedCountry":null}
指定国家且有配置时configuration示例:
{"platform":"android","country":"us","channel":"google_play","currency":"USD","currencyScale":2,"version":1,"updatedAt":"2026-11-06T00:00:00Z","packages":[{"id":"00000000-0000-4000-8000-000000000001","diamonds":100,"priceMinor":177,"sortOrder":0}]}
失败响应¶
| HTTP | code | 条件 |
|---|---|---|
| 400 | INVALID_APP_CHANNEL | 渠道无效或平台不匹配,不能回退为零扣费渠道 |
| 400 | INVALID_RECHARGE_CONFIGURATION | 平台、国家、币种、套餐范围或编号归属无效 |
| 400 | BAD_REQUEST/VALIDATION_FAILED/INVALID_CLIENT_HEADERS | JSON、字段类型/范围或公共头无效 |
| 400 | ENCRYPTION_REQUIRED/INVALID_ENCRYPTED_REQUEST | 缺少或无效JWE |
| 401/403 | UNAUTHORIZED/FORBIDDEN/ACCOUNT_DISABLED/VIP_REQUIRED | 会话、安装绑定或权限校验失败 |
| 426/429 | HTTPS_REQUIRED/TOO_MANY_REQUESTS | 传输或限流拒绝 |
| 503 | SERVICE_UNAVAILABLE | 数据库或Redis不可用,不解释为空套餐 |
code固定;message和字段错误支持中英日韩,缺省/未知语言回退英文。
接入说明¶
正式发行渠道从服务端已绑定会话读取,选择对应渠道与国家配置;平台须匹配该渠道,不接受查询参数指定另一渠道。configuration新增可空channel,正式配置为九渠道代码,旧平台配置为null。priceMinor在正式渠道配置范围扩至1–1000000000000,仍为准确整数,原平台兼容范围保持1–1000000000。客户端按币种精度格式化。开发dev或旧空渠道会话优先保留已有旧平台配置,未配置的平台在开发展示时读取google_play/app_store对应套餐。该兼容来源不证明真实商店或市场身份。
后台按九个正式发行渠道 → 国家 → 套餐管理。各渠道、国家独立,旧平台配置单独兼容,不提供全局或分组充值开关。保存只改变套餐展示,不创建订单、核验付款、增加余额或授予VIP。国家参数是显式选择,不证明真实支付市场;IP、真实商店地区识别仍未接入。美国兜底只用于当前套餐展示。Google/Apple的范围外有效国家使用同渠道美国配置;美国组为空时返回美国空组,不借其他渠道或其他国家价格。国内七渠道只允许中国大陆cn,显式请求其他国家返回400;旧平台兼容仍精确读取。
钱包充值入口和按钮始终保留。首次让用户显式选择国家,再请求对应套餐;不自动选择第一国家或使用资料国籍。成功空结果显示暂无套餐,失败显示重试并保留上一成功快照。旧余额字段rechargeAvailable=false仍表示实际支付未接入,不能用于隐藏入口;点击按钮不得模拟到账。价格用priceMinor与currencyScale准确格式化,国家切换清理旧套餐选择,退出/切换账号后取消旧请求。
2026-11-06国内范围修正后服务器clean verify共786项全部通过。充值相关14项覆盖七个国内渠道仅cn、旧海外报价保留及不可读写、混合国家初始化整批回滚、正式App越界400,以及Google三国、Apple四国和美国展示回退。真实受信HTTPS/JWE的6项只读接口检查和6项页面检查通过,实际逐个切换七个国内渠道均为中国大陆1/1、CNY及六档1:10报价;四语桌面/手机12组布局通过。当前14组/84档可运营,全库存量2241组/13446档的价格、稳定编号和版本摘要保持一致。本次业务写入为0,未安装或运行客户端设备。商店商品绑定、国家识别、订单核验和真实支付继续留到最后接入。
真实后台验收使用本站明确受信证书,JSON经真实JWE认证解密。本次仅调整可运营国家及展示回退,保留既有报价、版本和审计,不批量重写套餐。