创建协议并立即生效¶
请求参数¶
仅OWNER可写。要求独立Cookie、可信HTTPS、真实JWE、同源Origin及X-Admin-CSRF。八项公共头必填,固定admin/web/admin_web;App身份不可调用。
无路径和查询参数。仅用于尚未配置的类型/地区/语言;已有当前正文应使用保存接口并带原id及expectedVersion。不得提交expectedVersion、status、currentRevision、publicEnabled或publishedAt。
| 字段 | 类型/必填 | 约束 |
|---|---|---|
| type | string,是 | terms/privacy/recharge/vip |
| locale | string,是 | 国内仅zh-CN,国际zh-CN/en/ja/ko |
| serviceRegion | string,是 | domestic/overseas |
| jurisdiction | string,否 | 省略自动取CN/GLOBAL;传值必须与地区一致 |
| title | string,是 | 非空,原输入最多120个UTF-16代码单元,保存trim |
| bodyHtml | string,是 | 最多60000个UTF-16代码单元及160000个UTF-8字节;净化后文本非空 |
| contentVersion | string,否 | 省略或空白由服务器生成;兼容传入1–64位ASCII字母数字及点、下划线、短横线,首位字母数字 |
| summary | string,否 | 默认空,最多500个UTF-16代码单元 |
| publicationFields | object,否 | 默认{};只接受类型目录列出的键,字符串值最多2000个UTF-16代码单元 |
| legalReviewed | boolean,否 | 兼容复核声明,默认false;自动生效不会伪造true,字符串/数字拒绝 |
| effectiveAt | ISO8601或null,否 | 兼容旧请求;保存时统一使用服务端当前时间,不支持延迟生效 |
四类协议共20个当前配置位,历史版本另行保留。服务端净化HTML,国内重要区及法定例外完整性校验保持;主体、联系信息、复核等缺项以missingFields提示,不再作为第二次发布门槛。
请求示例¶
通过后台统一封装发送下列业务JSON:
await request('agreements', 'POST', {
type: 'terms', locale: 'en', serviceRegion: 'overseas',
title: 'Terms of Service', bodyHtml: '<p>填写实际协议正文。</p>'
});
统一封装注入Accept-Language、X-Client-Type、X-Platform、X-App-Version、X-App-Build、X-Channel、持久X-Device-Id、每次新的X-Request-Id/X-Request-Timestamp,以及Cookie、Origin、CSRF和JWE。示例正文仅说明参数,不代表运营内容。
成功响应¶
HTTP200,Cache-Control:no-store,外层JWE;data为完整详情。首次version=0、status=PUBLISHED、currentRevision=true、publicEnabled=true,publishedAt和effectiveAt非空。无需再调用发布接口。
创建正文、当前标记、用户协议/隐私政策同意版本快照及管理员审计同事务;任何一步失败整体回滚。正文版本与登录同意版本独立,App目录requiredVersion与auth/options对应值保持一致;具体见App目录。
失败响应¶
| HTTP | code | 条件 |
|---|---|---|
| 400 | INVALID_AGREEMENT/BAD_REQUEST | 类型、语言组合、长度、JSON或未知字段非法 |
| 400 | AGREEMENT_IMPORTANT_REQUIRED | 国内重要区或同区法定例外被移除 |
| 400 | INVALID_CLIENT_HEADERS/加密错误码 | 元数据或JWE不合法 |
| 401 | UNAUTHORIZED | 管理员会话失效或误用App身份 |
| 403 | FORBIDDEN/ADMIN_CSRF_INVALID | 角色、来源或CSRF不符 |
| 409 | AGREEMENT_DUPLICATE | 同配置位已存在传入的内容版本 |
| 409 | AGREEMENT_CONFLICT | 已有当前正文,必须读取后按版本保存 |
| 426 | HTTPS_REQUIRED | 后台禁止HTTP |
| 503 | SERVICE_UNAVAILABLE | 数据库、Redis或审计不可用 |
{"code":"AGREEMENT_CONFLICT","message":"协议已变化,请重新读取后保存。","data":null,"errors":[]}
提示四语,code固定;网关失败按公共传输规则处理。
接入说明¶
保存成功即可由App下一次目录查询取得链接。保存失败保留输入;超时不代表未执行,不自动重发,先读取当前配置位核对。法律复核、真实支付和用户明确同意仍按各自实际状态记录,保存内容本身不执行付款或替用户同意。
2026-11-04已随V19与新版后台配套部署,417项服务器Java回归零失败/错误/跳过,覆盖保存生效、旧正文保留、同意版本、并发、权限/JWE/CSRF、审计回滚与迁移。公网60组旧渠道语言组合、7项访问边界及20个独立HTML链接只读验证通过;运行库原20份正文与UUID保持,未伪造法律复核。后台保存交互另通过18项浏览器夹具及24组四语布局,真实运行库未写入测试正文。