PUT/api/v1/admin/agreements/{id}
管理员Cookie/HTTPS/JWE,ADMIN_AGREEMENTS_WRITE及CSRFJSON 响应接入指南 ↗

保存协议并立即生效

请求参数

仅OWNER。要求独立Cookie、HTTPS、真实JWE、Origin、X-Admin-CSRF及完整八项公共头,固定admin/web/admin_web。路径id为当前正文UUID,无查询参数;历史记录不可作为保存目标。

字段 类型/必填 约束及省略语义
expectedVersion integer(int64),是 当前详情version,非负;字符串、小数、负数拒绝
type string,是 原terms/privacy/recharge/vip,不可变更
locale string,是 原正文语言;国内zh-CN,国际四语之一
serviceRegion string,是 原domestic/overseas,不可变更
jurisdiction string,否 省略按地区归一CN/GLOBAL;不能更改归属
title string,是 非空,原输入最多120个UTF-16代码单元
bodyHtml string,是 最多60000个UTF-16代码单元、160000个UTF-8字节,净化后非空
contentVersion string,否 可省略;传入时必须为读取的原版本。新版本由服务器自动生成
summary string,否 省略/null保留,空字符串清除,最多500个UTF-16代码单元
publicationFields object,否 省略/null保留,{}清除;键来自类型目录,每值string且最多2000个UTF-16代码单元
legalReviewed boolean,否 省略/null为false;不会因保存自动生成审核结论
effectiveAt ISO8601或null,否 兼容旧字段;生效时间始终由本次保存确定

这是完整正文保存,不是任意字段PATCH。状态、publicEnabled、currentRevision、发布时间及其他未知字段拒绝。HTML净化、国内重要区保护和四语错误保持。

请求示例

await request('agreements/11111111-1111-4111-8111-111111111111', 'PUT', {
  expectedVersion: 2, type: 'terms', locale: 'en', serviceRegion: 'overseas',
  title: 'Terms of Service', bodyHtml: '<p>填写修改后的实际正文。</p>'
});

统一后台封装提供Accept-Language及八项X-*元数据、Cookie、Origin、CSRF、JWE;不在页面拼接凭据。

成功响应

HTTP200及no-store,data为完整详情。有实际内容修改时:

  • 返回新的id和自动生成的contentVersion,version为原版本加1。
  • status=PUBLISHED、currentRevision=true、publicEnabled=true;publishedAt/effectiveAt为本次服务端保存时间。
  • 旧id的正文、内容版本和阅读地址保持,currentRevision变为false。
  • 当前正文、同意版本快照及AGREEMENT_UPDATE审计同事务提交。

正文、标题、摘要、附加资料和复核声明都没有变化时返回原记录,不新增版本或无故使用户同意失效。请求超时后不能假定未保存。

失败响应

HTTP code 条件
400 INVALID_AGREEMENT/BAD_REQUEST 字段、长度、归属、JSON类型或未知字段非法
400 AGREEMENT_IMPORTANT_REQUIRED 国内重要区和法定例外不完整
400 INVALID_CLIENT_HEADERS/加密错误码 元数据或JWE不合法
401 UNAUTHORIZED Cookie失效或身份不符
403 FORBIDDEN/ADMIN_CSRF_INVALID 角色、Origin或CSRF不符
404 NOT_FOUND id不存在
409 AGREEMENT_CONFLICT expectedVersion过期,或id已是历史正文
426 HTTPS_REQUIRED 非HTTPS
503 SERVICE_UNAVAILABLE 持久化、Redis或审计失败,事务回滚
{"code":"AGREEMENT_CONFLICT","message":"协议已变化,请重新读取后保存。","data":null,"errors":[]}

code固定,提示中英日韩;409、超时和未知结果保留输入,暂停重复提交并先读取当前正文核对。

接入说明

后台直接编辑当前正文,保存后采用响应的新id/version继续编辑;不要继续PUT旧id,也不再以PUBLISHED触发用户手填下一版本。历史选择只读,可返回当前版本。网页/手机复用同一编辑器,切换尺寸与取消不写入。

App下一次读取目录即取得新链接。用户协议和隐私政策保存会自动切换登录同意版本,旧登录配置收到CONSENT_VERSION_CHANGED后刷新并要求重新明确同意。阅读不自动替用户勾选。

2026-11-04已随V19与新版后台配套部署,417项服务器Java回归零失败/错误/跳过,覆盖保存生效、旧正文保留、同意版本、并发、权限/JWE/CSRF、审计回滚与迁移。公网60组旧渠道语言组合、7项访问边界及20个独立HTML链接只读验证通过;运行库原20份正文与UUID保持,未伪造法律复核。后台保存交互另通过18项浏览器夹具及24组四语布局,真实运行库未写入测试正文。