请求、响应与标识约定

本页定义各接口复用的协议规则。接口页描述业务字段；调用前请同时确认该接口的凭据类型、数据范围和响应类型。

服务地址与请求头

BASE_URL 为部署方交付的 HTTPS 服务地址，不含接口路径。公有云、专有云和私有部署可能不同，不使用官网域名代替 API 地址。

请求头	使用规则
`Authorization`	平台 API Key、应用 Token、租户契约使用 `Bearer {凭据}`；不同类型不可互换
`token`	渠道租户管理使用平台 Token；页面登录态使用登录 Token，两者身份与用途不同
`Content-Type`	JSON 写入为 `application/json`；上传用 `multipart/form-data`，由 HTTP 客户端生成 boundary
`Accept-Language`	可选：`zh-CN`、`zh-TW`、`en`、`vi`；只影响提示语言，不改变字段名
`Accept`	JSON 接口可用 `application/json`；流式对话使用 `text/event-stream`

同一请求只提交目标接口需要的凭据，不把多种 Token 同时发送来尝试认证。完整凭据不进入浏览器源码、分析平台或日志。

{
  "code": 8200,
  "message": "SUCCESS",
  "data": {}
}

空字符串的写入响应也可表示成功；false、空数组和 null 不可统一解释为请求失败。先判断 code，再按具体业务处理。

{
  "code": 8200,
  "message": "SUCCESS",
  "pageNo": 1,
  "pageSize": 10,
  "total": 0,
  "totalPage": 0,
  "data": []
}

字段	JSON 类型	含义
`code`	integer	业务状态，成功为 8200
`message`	string	提示信息
`pageNo`	integer	当前页，从 1 开始
`pageSize`	integer	每页条数；接口未另行说明时默认 10
`total`	integer	满足查询条件的记录总数
`totalPage`	integer	总页数；无结果时可为 0
`data`	array[object]	当前页记录，不是 `data.records`；条目结构见各接口

顺序读取至总页数，不把每页都有 pageSize 条当成保证。分页查询期间发生新增或删除时，不应假设它提供数据快照。

接口类型	成功响应	处理方式
非流式 Chat	对话对象	读取 `choices`、`conversationId` 等
流式 Chat	SSE 事件	按事件边界解析 JSON，处理结束事件与中断
Dify 外部检索	`{"records":[]}`	读取 records 数组
QA 模板下载	Excel 文件流	按 Content-Type 和下载响应处理，不解析为 JSON

以上接口失败时可能返回 JSON 错误体；应先检查 HTTP 状态和实际 Content-Type。详见错误处理。

标识	代表什么	从哪里获得	常见使用位置
租户 `code`	租户业务编码	渠道开户/查询	契约 `tenantCode`
用户 `code`	用户业务编码	员工或访客创建	契约 `userCode`、应用对话 `user`
知识库 `code`	知识库业务编码	知识库创建/列表	检索、文件请求的 `containerId`
文件 `code`	知识资源业务编码	文件导入/列表	查询 `code`、检索 `dataIds`
`id`	数据库记录主键	对应资源查询	明确要求按 id 的更新/删除
`conversationId`	会话标识	Chat 响应/主题列表	多轮续聊、历史查询
`messageId`	单条消息标识	Chat 响应/记录	消息关联
`appid`	应用标识	应用配置或渠道初始化	应用主题、记录筛选

编码按不透明字符串保存，不解析其内部格式。引用中的 dataSetId 与分片中的 dataId 都可能指向文件 code，但字段名不同。不要将数字主键替代业务编码。

表中的类型是 JSON 类型，不是 Java 类型。integer 可能来自 64 位主键；JavaScript 客户端涉及大整数时应使用无损 JSON 解析，不先转浮点数再转字符串。
请求日期使用接口指定格式。契约 expireAt、V2 签名时间戳是 Unix 秒；检索标准时间字段是 Unix 毫秒；不要混用。
LocalDateTime 类业务字段为日期时间字符串，例如 2026-09-05T10:30:00，不自带时区偏移。租户合同等旧日期字段受部署序列化配置影响，联调时确认；不得作为 Token 时间戳使用。
可选字段可能为 null、空字符串或未输出；数组可能为空。字段是否有值取决于资源类型和接口是否填充该字段，数据字典中的可选扩展不代表每次必有。
金额、空间、时长分别按字段标注的元、字节/MB/GB、秒/毫秒处理。显示用的格式化文本不参与数值运算。
响应示例是脱敏结构示例，不是可直接用于生产的资源、凭据或有效日期。

只读请求遇到短暂网络错误可有限退避重试。创建操作超时先按稳定 code 查询；充值、状态切换和全量权限更新不要自动重放。保存接口路径、调用时间、业务编码、HTTP 状态和业务码用于排查，脱敏保存错误摘要。

未知响应字段应允许兼容；未知枚举值应保留并降级显示，不直接当成成功状态。实际开放能力以交付版本与授权为准。