获取四类协议网页地址¶
请求参数¶
供登录前、注册、充值和VIP开通页获取协议地址。八项公共请求头全部必填,X-Client-Type=app,X-Platform=android或ios;无需Bearer,主动携带时仍校验凭证。返回成功/业务错误均不缓存,合法请求ID回传。
X-Channel仍由安装包配置提供,只表示发行来源;已知渠道的平台必须匹配。新客户端先读取闪屏布局,再请求GET /api/v1/agreements?layoutPolicy=ip-v1:CN来源IP选择国内协议,其他已识别地区选择国际协议,无法识别默认国内。布局与目录使用同一离线国家库,不接受客户端指定IP、地区、法域或商店国家。国内中文/国际四语的正文规则保持;资料国家与界面语言不用于判断布局。
兼容旧客户端:省略layoutPolicy仍按以下原渠道规则。全球苹果渠道在该旧模式继续映射国际,不让旧App解析突然改变。
| 发行渠道 | 平台 | 协议集 | 正文语言 |
|---|---|---|---|
| xiaomi、vivo、huawei、oppo、yingyongbao、honor、baidu | android | 国内domestic | 固定zh-CN,四类各一份中文 |
| google_play | android | 国际overseas | 按Accept-Language选择zh-CN/en/ja/ko,四类各四语 |
| app_store | ios | 国际overseas | 同上 |
| dev及其他未知渠道 | 合法App平台 | 不选择协议集 | 不猜国内/国际,四类均不可用 |
Accept-Language继续发送当前App界面语言。国内即使请求英文/日文,data.language和各项正文仍固定中文;成功/错误message继续按请求语言本地化。国际接受en-US、ja-JP、ko-KR等地区标签,缺省或不支持时回退英文。国际中文独立于国内中文,缺少该译文时不拿国内稿或其他语言代替。
无路径参数和业务正文,不分页。查询只允许可选layoutPolicy,必须唯一且精确为ip-v1;空值、重复、其他值或额外ip/jurisdiction/serviceRegion/locale等参数均400 BAD_REQUEST。参数置于原始query,沿用现有JWE上下文绑定,不增加加密签入头。国内4份、国际16份是配置位数量,不代表已发布20份正文,不限制历史版本数量。
目录是JSON,遵循AES/JWE,正式环境要求HTTPS及JWE,加密GET信封放在X-Budyoo-JWE;当前固定码dev保留明文兼容。返回的网页是独立HTML阅读入口,不属于JSON加密接口。
请求示例¶
base_url='https://api.budyoo.cn' # 当前dev,正式使用HTTPS与JWE
curl --fail-with-body "$base_url/api/v1/agreements?layoutPolicy=ip-v1" \
-H 'Accept: application/json' -H 'Accept-Language: zh-CN' \
-H 'X-Client-Type: app' -H 'X-Platform: android' \
-H 'X-App-Version: 1.0.0' -H 'X-App-Build: 1' -H 'X-Channel: xiaomi' \
-H 'X-Device-Id: 4d4ae3ea-6a4a-4f34-a292-8e94551851d7' \
-H "X-Request-Id: $(uuidgen | tr '[:upper:]' '[:lower:]')" \
-H "X-Request-Timestamp: $(date +%s)000"
新IP模式下国内来源改变Accept-Language仍返回中文;国际正文需实际国际来源,改变渠道不会改变布局。无query旧模式才按google_play/app_store选择国际。开发包如实使用dev,正式包从打包配置读取实际渠道。
成功响应¶
HTTP200。固定返回四项,顺序为terms、privacy、recharge、vip。后台保存即生效,下次读取目录返回当前正文链接。以下仍保留全新环境尚未配置任何正文时的不可用结构示例;版本值只作占位,不写死到客户端:
{
"code": "SUCCESS",
"message": "操作成功。",
"data": {
"channel": "xiaomi",
"channelSupported": true,
"language": "zh-CN",
"supportedLanguages": ["zh-CN"],
"jurisdiction": "CN",
"serviceRegion": "domestic",
"agreements": [
{"type":"terms","title":"用户协议","language":"zh-CN","available":false,"requiredVersion":"2026-11-02-draft","contentVersion":null,"url":null,"effectiveAt":null},
{"type":"privacy","title":"隐私政策","language":"zh-CN","available":false,"requiredVersion":"2026-11-02-draft","contentVersion":null,"url":null,"effectiveAt":null},
{"type":"recharge","title":"充值服务协议","language":"zh-CN","available":false,"requiredVersion":null,"contentVersion":null,"url":null,"effectiveAt":null},
{"type":"vip","title":"VIP开通协议","language":"zh-CN","available":false,"requiredVersion":null,"contentVersion":null,"url":null,"effectiveAt":null}
]
},
"errors": []
}
下列为正式内容存在时的一项合成示例,地址并非当前可用发布:
{"type":"vip","title":"VIP Membership Agreement","language":"en","available":true,"requiredVersion":null,"contentVersion":"2026-11-04.1","url":"https://api.example.test/legal/agreements/11111111-1111-4111-8111-111111111111","effectiveAt":"2026-11-04T00:00:00Z"}
| 字段 | 类型 | 可空 | 说明 |
|---|---|---|---|
| data.channel | string | 否 | 本次公共头X-Channel |
| data.channelSupported | boolean | 否 | 是否属于支持的九个发行渠道;dev为false |
| data.language | string | 否 | 实际正文语言;国内固定zh-CN,国际按请求归一;仅旧模式未知渠道回显归一语言而无正文 |
| data.supportedLanguages | string[] | 否 | 国内仅[zh-CN],国际[zh-CN,en,ja,ko];仅旧模式未知渠道[];不表示正文均已发布 |
| data.jurisdiction | string | 是 | 国内CN、国际GLOBAL;仅旧模式未知渠道null;GLOBAL是协议集标记,不代表国家或法律结论 |
| data.serviceRegion | string | 是 | 新模式按IP选定domestic/overseas;仅旧模式未知渠道为null |
| data.agreements | object[] | 否 | 固定四项;类型用固定code判断,不按翻译标题判断 |
| agreements[].type | string | 否 | terms用户协议、privacy隐私、recharge充值、vipVIP |
| agreements[].title | string | 否 | 正式文档标题;不可用时只返回对应语言的通用标题,不泄露草稿标题 |
| agreements[].language | string | 否 | 正文语言,与data.language一致;国内不要求等于界面语言。不同地区和译文分别对应不同UUID地址 |
| agreements[].available | boolean | 否 | 已存在符合条件、已发布且生效的正文 |
| agreements[].requiredVersion | string | 是 | terms/privacy的当前同意版本,与auth/options对应值一致;代表一套地区/语言正文快照,充值和VIP为null |
| agreements[].contentVersion | string | 是 | 当前语言这份正文的独立内容版本,允许不同于requiredVersion;available=false时null |
| agreements[].url | string | 是 | 可直接用WebView加载的绝对网页地址;available=false时null。不能把此字段当JSON接口或在地址后附加Token |
| agreements[].effectiveAt | string(date-time) | 是 | 该版本的生效时间,带时区ISO8601;不可用时null |
国际示例的data外层为channel=google_play、channelSupported=true、language=en、supportedLanguages=[zh-CN,en,ja,ko]、jurisdiction=GLOBAL、serviceRegion=overseas,仍返回四项。channelSupported仅表示渠道是否在发行目录;新IP模式下dev/未知渠道也可得到实际IP范围及可用正文,不能据此强制不可用。仅无参数旧模式的未知渠道仍返回空supportedLanguages、null范围及四个不可用条目。
每个类型/地区/语言只返回currentRevision标记的当前生效正文。用户协议或隐私政策任一语言保存后,同一事务生成新的同意版本,记录当时该类型全部地区/语言对应的正文UUID;auth/options和本目录requiredVersion共同读取这份快照。contentVersion是单份正文版本,不要求等于requiredVersion。目录正文与同意版本在同一读取快照中生成,其他语言不被覆盖;旧的已生效UUID地址继续读取原文。充值/VIP不使用登录同意版本。
失败响应¶
| HTTP | code | 原因与处理 |
|---|---|---|
| 400 | INVALID_CLIENT_HEADERS | 八项公共头缺失、重复、格式非法,或已知渠道与平台不匹配 |
| 400 | BAD_REQUEST | layoutPolicy非唯一ip-v1,或携带其他查询参数 |
| 401 | UNAUTHORIZED | 主动携带无效或格式错误的Bearer |
| 403 | FORBIDDEN | 调用端不是App |
| 426 | HTTPS_REQUIRED | 当前策略要求HTTPS却使用HTTP |
| 503 | SERVICE_UNAVAILABLE | 数据库暂不可用,或存在正式内容但阅读源站尚未配置 |
JWE错误按公共协议处理,code固定、message与字段错误四语。例如:
{"code":"BAD_REQUEST","message":"请求格式不正确。","data":null,"errors":[]}
没有正式文档不是401/404,而是目录HTTP200及对应条目available=false;直接读取草稿、未知ID或未生效网页返回404。
接入说明¶
国际版四类×四语的前端测试素材和清单继续保留来源。按保存即生效的新规则,V19将后台各配置位最近保存的国内4份、国际16份正文接入当前阅读;原正文、UUID和实际复核标记保留。国际内容仍标注测试用途,可读不代表法律审核完成。App必须使用本接口返回的/legal链接,不从文档站静态素材拼接或伪造地址。
- 复用统一请求层查询目录,找到需要的type,确认available=true且url非空,再交给WebView。
- 网页URL固定到该版本和语言,直接匿名GET,无需八项App头、Bearer、管理员Cookie或JWE;不要让网络拦截器对网页强制解密。正式网页仍要求有效HTTPS,不忽略证书错误;仅明确启用固定码及HTTP联调的dev允许HTTP读取公开协议。
- 切换App语言后可重新查询目录:国内仍是中文,国际返回相应译文。解析应信任已验证响应中的data.language,不要求它总等于界面语言。不修改旧URL猜译文,不用另一协议集/语言或本地旧稿伪装正式正文。
- terms/privacy只将requiredVersion与本次登录期望版本比较,contentVersion保留独立正文版本语义,不能因为两者字符串不同拒绝合法正文。requiredVersion不符或认证接口返回CONSENT_VERSION_CHANGED时刷新登录配置、清除旧勾选/挑战并重新取得明确同意;不自动替用户同意,不重用旧验证码挑战。协议不可用或加载失败不记录已阅读/同意;充值/VIP订单同意仍由支付业务另行实现。
- 不由前端填写jurisdiction或serviceRegion。新客户端固定传layoutPolicy=ip-v1,按响应serviceRegion和language解析,取消app_store固定海外及channelSupported=false强制不可用的旧断言;目录范围与本轮闪屏layoutRegion不符时重新读取并阻止混用、自动同意,不在在途表单中静默切换。无参数旧客户端保留渠道选版。地址来自API公开源站,不拼到文档站;后台保存成功后下次读取即生效。
IP仅用于产品展示选版,不能证明用户实际所在地或法律适用。IP库署名与更新、默认回退及网络失败边界见闪屏配置。
正文缺少时仍available=false,不跨语或地区补内容。保存后的可读状态、内容是否完成实际审核和用户是否明确同意分别记录,自动生效不会自动标记legalReviewed=true或写用户同意。客户端须配套支持requiredVersion与contentVersion独立;原来要求两者相等的客户端需要更新。
2026-11-04已配套部署V19和新版后台,417项服务器Java回归零失败/错误/跳过,覆盖保存即生效、同意版本联动、旧挑战拒绝、历史正文、迁移、权限/JWE/CSRF及审计回滚。公网60组旧渠道语言组合、7项访问边界及20个独立HTML链接只读验证通过;原20份正文与UUID、复核标记均保持,当前全部可读。此前IP模式与来源防伪验证保留,海外真实设备切网未验收。