# 云蝠接口接入手册

## 开始接入

1. 企业管理员创建最小权限密钥；仅在服务端保存，以 HTTPS 调用。企业机器接入策略、账号状态与套餐限制继续生效。
2. 调用 GET /v1/capabilities 核对企业、有效期与 allowedOperations。
3. 按业务场景选择操作。POST 必带 8–100 位 Idempotency-Key；重试保持原键、操作、查询与正文。

```sh
curl --fail-with-body --show-error --max-time 15 --include "${YUNFU_BASE_URL:?Set your service origin}/v1/capabilities" \
  -H "Authorization: Bearer ${YUNFU_API_KEY:?Set your server API key}"
```

- 保留 X-Request-Id、时间和状态；提前拒绝时可能没有编号。异步受理不代表执行完成。
- 按接口使用 page/pageSize 或服务端返回的 cursor，不混用。文本与语音记录 pageSize 最大 100。
- 错误正文按接口解析，常见格式 {error:string}。409 先核对版本与原结果；429 按 Retry-After 等待。
- 时间按字段说明使用 Unix 毫秒或带时区 ISO 字符串；未知值保留 null 或省略。

## 推荐流程

- **会话接待**: `desk.read` → `desk.claim` → `desk.send`
- **客户资料**: `customers.read` → `customers.save` → `customers.crmFollowup`
- **知识检索**: `knowledge.save` → `knowledge.index` → `knowledge.publish`
- **电话外呼**: `phone-calls.dial` → `phone-detail.read` → `phone-records.export`
- **服务结果**: `voice-records.read` → `analysis.read` → `billing.read`
- **邮件接待**: `email.read` → `email.saveDraft` → `email.sendDraft`
- **事件回调**: `callbacks.save` → `callbacks.test` → `callbacks.read`

实时语音和洞察请查看各自专题；渠道与智能体先在控制台完成配置。

## 错误与重试

有 X-Request-Id 时，由有权的管理员在请求日志核对；提前拒绝的请求可能没有编号，此时记录时间、操作路径和状态。/v1/capabilities 的编号不进入业务日志。错误正文按接口解析，不依赖错误文案自动重试。

| 状态 | 含义 | 处理 |
| --- | --- | --- |
| 400 | 参数错误 | 按当前操作检查字段、格式和固定参数；修正后再提交。 |
| 401 | 凭据失效 | 检查密钥是否过期、撤销或轮换，以及站点是否匹配。 |
| 402 | 余额或额度不足 | 核对余额、套餐和接待额度；恢复可用后再确认是否提交。 |
| 403 | 权限或来源不符 | 核对操作授权、账号权限和请求来源；不要关闭认证绕过。 |
| 404 | 资源不存在或不可见 | 核对路径、资源编号和所属企业。 |
| 405 | 请求方法不符 | 按该操作文档和 Allow 响应头使用 GET 或 POST。 |
| 408 | 读取请求超时 | 检查网络和正文上传；写入重试前核对原结果并保留原幂等键。 |
| 409 | 版本、幂等或状态冲突 | 先读回业务结果；有 Retry-After 时等待。修改配置先合并最新版本，结果未知不换键重做。 |
| 413 | 请求过大 | 按接口限制缩小请求或使用该业务提供的分批导入入口。 |
| 415 | 正文格式不支持 | 开放网关 POST 使用 Content-Type: application/json 和有效 JSON 正文。 |
| 422 | 业务条件不满足 | 按错误提示补齐配置或业务状态；不要重复提交相同无效请求。 |
| 429 | 调用限流 | 按 Retry-After 等待，降低调用频率；写入重试仍使用原幂等键。 |
| 503 | 依赖不可用 | 稍后核对服务状态；只读可有界重试，写入先确认原结果。 |

- 同一幂等键改了操作、查询或正文 · 409；幂等键在同一个 API Key 记录下跨操作共享，不是每个接口各自独立。 · 先核对原请求。重试必须保持同一操作、查询、正文与键；另一笔已确认业务提交才用另一键。
- 密钥已轮换 · 密钥轮换后，旧回执的密钥版本与当前不同时返回 409。 · 用当前获准凭据查询业务并由管理员核对原日志，不以换密钥或换键强行重复执行。
- 请求仍在执行或结果未知 · 409 可含 requestId / state，并给 Retry-After: 2；state 可能为 running 或 unknown。 · 等待后读回业务和原请求日志，不把 409 当作执行失败，也不换新键盲重做。
- 已完成但不能重放 · 回执完整正文最多缓存 256000 字节、窗口 24 小时；超限、过期或无缓存时不能重放。 · 查询业务结果；缓存过期不表示业务已撤销，也不授权再次执行。Idempotency-Replayed: true 仅表示返回原缓存。
- 业务 revision 冲突 · 业务接口也可能返回 409，与网关幂等冲突不同；revision 不是幂等键。 · 先重读并合并他人变更。确认原业务没有完成、形成新的提交内容后，才由用户确认新的逻辑提交与新键。
- 429、超时或断流 · 429 按 Retry-After 处理；网络异常、HTTP 状态与业务完成状态是三回事。 · 只读调用可做有界重试；写入先核对原结果。SDK 不自动重试写入，客户端取消也不保证服务端已回滚。

### 网关错误码

网关自身的拒绝（认证、授权、限流、幂等、格式）在 JSON 正文中返回稳定的 code，按 code 分支处理，不要解析 error 文案。没有 code 的错误由业务接口返回，按该接口说明处理。每次响应都带 X-RateLimit-Limit / X-RateLimit-Remaining / X-RateLimit-Reset，可在收到 429 前主动降速。

| code | HTTP | 含义 | 处理方式 |
| --- | --- | --- | --- |
| INVALID_REQUEST | 400 | 请求参数、查询或正文不符合网关要求 | 按错误说明修正后再提交；不要原样重试。 |
| ACTION_MISMATCH | 400 | 正文 action 与所调用操作固定的 action 不一致 | 省略 action，或使用操作文档中的固定值。 |
| QUERY_MISMATCH | 400 | 查询参数试图覆盖操作的固定查询 | 删除该查询参数；需要其他分支时改用对应操作。 |
| IDEMPOTENCY_KEY_INVALID | 400 | 写请求缺少 Idempotency-Key 或格式无效 | 提供 8–100 位字母、数字、下划线、连字符、点或冒号。 |
| API_KEY_INVALID | 401 | 缺少 Bearer 密钥，或密钥不存在、已到期、已撤销 | 核对 Authorization 请求头与密钥有效期；必要时由管理员创建新密钥。 |
| API_KEY_OWNER_INACTIVE | 401 | 创建密钥的管理员账号已停用、移出企业或变更身份 | 由当前企业管理员重新创建密钥。 |
| API_KEY_ROTATED | 401 | 请求执行期间密钥被轮换 | 用新密钥读回业务结果后再决定是否重试。 |
| API_KEY_SITE_MISMATCH | 403 | 密钥不属于当前站点域名 | 使用创建密钥时的站点地址作为 YUNFU_BASE_URL。 |
| ORIGIN_NOT_ALLOWED | 403 | 请求携带了与站点不同源的 Origin | 从服务端调用并去掉浏览器 Origin；密钥不得在浏览器中使用。 |
| ACCOUNT_PERMISSION_DENIED | 403 | 密钥所属账号已不具备该操作所需权限 | 由企业管理员恢复账号权限，或改用其权限范围内的操作。 |
| TENANT_DISABLED | 403 | 密钥所属企业已停用 | 联系平台方恢复企业后再调用。 |
| OPERATION_NOT_GRANTED | 403 | 密钥未勾选该操作 | 调用 GET /v1/capabilities 核对 allowedOperations；需要时创建包含该操作的新密钥。反复调用未授权操作会触发请求防护。 |
| OPERATION_NOT_FOUND | 404 | 操作 ID 不存在 | 按接口参考核对操作 ID 的拼写与大小写。 |
| METHOD_NOT_ALLOWED | 405 | HTTP 方法与操作不符 | 按 Allow 响应头使用 GET 或 POST。 |
| REQUEST_TIMEOUT | 408 | 读取请求正文超时或被取消 | 检查网络后用原幂等键重试。 |
| IDEMPOTENCY_KEY_REUSED | 409 | 同一幂等键被用于不同的操作、查询或正文 | 重试保持原请求完全一致；新的业务提交使用新键。 |
| REQUEST_IN_PROGRESS | 409 | 同一幂等键的原请求仍在执行 | 按 Retry-After 等待后用原键重试，或在调用记录中按 requestId 核对。 |
| REQUEST_OUTCOME_UNKNOWN | 409 | 原请求中断，执行结果未知 | 先读取业务数据确认是否生效；确认未生效后才用新键重新提交。 |
| REPLAY_UNAVAILABLE | 409 | 原请求已完成，但响应超过缓存上限或已过 24 小时 | 原请求不会再次执行；通过业务读取操作获取结果。 |
| ORIGINAL_KEY_ROTATED | 409 | 原请求由轮换前的密钥发起，不重放旧回执 | 用当前密钥读回业务结果，不换键强行重做。 |
| PAYLOAD_TOO_LARGE | 413 | 请求正文超过该操作的大小上限 | 缩小正文，或使用该业务的分批导入操作。 |
| UNSUPPORTED_MEDIA_TYPE | 415 | POST 未使用 application/json | 设置 Content-Type: application/json 并发送 JSON 正文。 |
| RATE_LIMITED | 429 | 超过密钥的每分钟调用限额 | 按 Retry-After 等待到下一分钟窗口；可用 X-RateLimit-Remaining 提前降速。 |
| API_BUSY | 429 | 超过短时突发或并发上限（也可能以 503 返回） | 降低并发，按 Retry-After 退避；写入用原幂等键重试。 |
| REQUEST_BLOCKED | 429 | 账号因高频、重复越权或连续协议错误被临时封禁 | 停止调用直到 blockedUntil；修正调用方后再恢复，换密钥不能解除。 |
| MFA_REQUIRED | 403 | 企业强制 MFA，当前不允许 API Key 机器接入 | 联系企业管理员确认接入方案；重新登录或轮换密钥无效。 |
| SERVICE_UNAVAILABLE | 503 | 操作处理器暂不可用 | 稍后重试；写入用原幂等键。 |
| INTERNAL_ERROR | 503 | 服务内部异常，正文含排查编号 reference | 只读可有界重试；写入先核对业务结果，并向支持提供 reference。 |

## 回调验签

X-Yunfu-Event-Id, X-Yunfu-Timestamp, X-Yunfu-Signature, X-Yunfu-Delivery-Id, X-Yunfu-Attempt

sha256=hex(HMAC-SHA256(secret, timestamp + "." + raw_body))；timestamp 为 Unix 秒。接收方应以常量时间比较签名并限制 ±300 秒重放窗口。

同事务事件队列，默认本人范围，可显式选择本企业事件。涵盖构建、记忆、配置、发布、工作流、服务状态、总结和 API 结果；仅登记的事件有效。最多自动尝试 5 次，间隔 30 秒、2 分钟、10 分钟、1 小时，依赖原生 scheduled。人工最多 10 次；可能重复或乱序，按事件 ID 去重；停用或变更不补发历史。

## 业务接口

### 读取智能体

`GET /v1/operations/agents.read`

权限：agent
费用：按业务权限与套餐执行。

```sh
# cURL 7.76+；请先在服务端设置环境变量。
: "${YUNFU_BASE_URL:?请设置服务端 HTTPS 地址}"
: "${YUNFU_API_KEY:?请设置已获授权的 API 密钥}"
curl --fail-with-body --show-error "$YUNFU_BASE_URL/v1/operations/agents.read" \
  -H "Authorization: Bearer $YUNFU_API_KEY"
```

响应示例：
```json
{
  "revision": 7,
  "agents": [
    {
      "id": "default",
      "name": "售后助手",
      "description": "",
      "modelId": "text-model",
      "archived": false,
      "publishedVersion": 0,
      "dirty": true,
      "updated": 1789603200000,
      "channels": []
    }
  ],
  "workflows": [],
  "channels": [],
  "publicKnowledgeLibraries": []
}
```

- 权限由当前登录账号、企业及支持访问范围决定，不能通过传 tenant、actor 或 owner 扩大访问范围。

### 读取文本对话记录

`GET /v1/operations/conversations.read`

权限：service
费用：按业务权限与套餐执行。

```sh
# cURL 7.76+；请先在服务端设置环境变量。
: "${YUNFU_BASE_URL:?请设置服务端 HTTPS 地址}"
: "${YUNFU_API_KEY:?请设置已获授权的 API 密钥}"
curl --fail-with-body --show-error "$YUNFU_BASE_URL/v1/operations/conversations.read?scope=all&page=1&pageSize=20&sort=newest" \
  -H "Authorization: Bearer $YUNFU_API_KEY"
```

| 字段 | 类型 | 要求 | 说明 |
| --- | --- | --- | --- |
| query | string | 可选 | 搜索关键词，最多 200 字符；字段覆盖范围见各接口说明。 |
| scope | all \| test \| service | 可选 | 记录范围，默认 all；演练记录和正式服务分别归类。 |
| page | integer | 可选 | 从 1 开始，最大 10000。 |
| pageSize | integer | 可选 | 1–100；默认值见接口说明。 |
| start / end | string | 可选 | 开始/结束时间：YYYY-MM-DD 按 UTC 整日；ISO 时间必须带时区。结束日期包含整日，结束时间包含指定毫秒。 |
| sort | newest \| oldest \| replies-desc \| replies-asc \| messages-desc \| duration-desc \| waiting-first | 可选 | 默认 newest；可按回复、消息数、时长和待处理优先排序。 |
| agentId | string | 可选 | 仅查询指定智能体的对话，最多 100 字符；省略查询全部可见智能体。 |

响应示例：
```json
{
  "conversations": [
    {
      "id": "conv_example",
      "name": "示例客户",
      "scope": "service",
      "isTest": false,
      "testType": null,
      "hasVoiceRecord": false,
      "channel": "网页",
      "unit": "客服部",
      "tag": "咨询",
      "handling": "AI",
      "lifecycle": "OPEN",
      "owner": "",
      "ownerId": null,
      "priority": "normal",
      "summary": "咨询订单进度",
      "messageCount": 2,
      "time": "09:00",
      "createdAt": "2026-09-17T01:00:00Z",
      "updatedAt": "2026-09-17T01:01:00Z",
      "closedAt": null,
      "textService": {
        "policy": {
          "version": 1,
          "source": "agent",
          "agentVersion": 3
        },
        "idleClose": {
          "enabled": true,
          "minutes": 30
        }
      },
      "idleCloseEvidence": null,
      "closeReason": null,
      "createdTime": 1789606800000
    }
  ],
  "total": 1,
  "page": 1,
  "pageSize": 20,
  "filters": {
    "query": "",
    "agentId": "",
    "scope": "all",
    "start": "",
    "end": "",
    "sort": "newest",
    "page": 1,
    "pageSize": 20
  },
  "asOf": 1789606860000
}
```

- 权限由当前登录账号、企业及支持访问范围决定，不能通过传 tenant、actor 或 owner 扩大访问范围。
- query 搜索编号、姓名、渠道、摘要和完整消息正文；最多 200 字符。
- 按有效 createdAt 排序，未知创建时间排末尾，同时间按 id 升序；有日期筛选时排除未知创建时间。
- 通过 service 权限及服务台可见范围过滤，普通坐席不会因此看到其他坐席私有记录。
- 这是服务台消息记录接口，没有 kind=text 过滤；可能包含 testType=voice 的演练会话和语音关联文字会话，不能据此统计纯文本通话。语音主记录请使用 /v1/operations/voice-records.read。

### 读取语音记录

`GET /v1/operations/voice-records.read`

权限：service
费用：按业务权限与套餐执行。

```sh
# cURL 7.76+；请先在服务端设置环境变量。
: "${YUNFU_BASE_URL:?请设置服务端 HTTPS 地址}"
: "${YUNFU_API_KEY:?请设置已获授权的 API 密钥}"
curl --fail-with-body --show-error "$YUNFU_BASE_URL/v1/operations/voice-records.read?scope=all&page=1&pageSize=10&inputKind=all&status=all&mode=all&sort=newest" \
  -H "Authorization: Bearer $YUNFU_API_KEY"
```

| 字段 | 类型 | 要求 | 说明 |
| --- | --- | --- | --- |
| query | string | 可选 | 搜索关键词，最多 200 字符；字段覆盖范围见各接口说明。 |
| scope | all \| test \| service | 可选 | 记录范围，默认 all；演练记录和正式服务分别归类。 |
| page | integer | 可选 | 从 1 开始，最大 10000。 |
| pageSize | integer | 可选 | 1–100；默认值见接口说明。 |
| start / end | string | 可选 | 开始/结束时间：YYYY-MM-DD 按 UTC 整日；ISO 时间必须带时区。结束日期包含整日，结束时间包含指定毫秒。 |
| sort | newest \| oldest | 可选 | 默认 newest；排序依据见各接口说明。 |
| agentId | string | 可选 | 智能体 ID，最多 100 字符。 |
| conversationId | string | 可选 | 关联对话 ID，最多 100 字符；使用时另外要求 service 权限及该对话可见。 |
| inputKind | all \| audio \| text \| mixed \| none | 可选 | 默认 all。 |
| status | all \| active \| ended \| handoff | 可选 | 默认 all。 |
| mode | all \| draft \| published | 可选 | 默认 all。 |
| minSeconds / maxSeconds | integer | 可选 | 通话时长下限 / 上限，单位秒，范围 0 至 31536000；下限不能大于上限。进行中通话按最近更新时间计算。 |
| sessionIds | JSON string[] | 可选 | 仅 action=export 时使用，导出所选通话。最多 100 个唯一 ID，仍受当前筛选和访问权限限制，不能与 sessionId 同传。 |
| pagination | offset \| cursor | 可选 | 默认 offset 兼容旧客户端；大数据列表建议 cursor。 |
| cursor | string | 可选 | cursor 模式下一页使用 nextCursor；第一页面省略。绑定当前身份、权限和筛选，不能跨账户复用。 |

响应示例：
```json
{
  "calls": [
    {
      "sessionId": "voice_example",
      "agentId": "agent_example",
      "agentName": "售后助手",
      "conversationId": "",
      "mode": "draft",
      "scope": "test",
      "created": 1789603200000,
      "ended": 1789603260000,
      "updated": 1789603260000,
      "status": "ended",
      "sourceStatus": null,
      "inputKind": "audio",
      "turns": 1
    }
  ],
  "total": 1,
  "page": 1,
  "pageSize": 10,
  "scope": {
    "query": "",
    "agentId": "",
    "conversationId": "",
    "inputKind": "all",
    "scope": "all",
    "recordScope": "all",
    "status": "all",
    "mode": "all",
    "start": "",
    "end": "",
    "sort": "newest",
    "page": 1,
    "pageSize": 10
  },
  "filterKey": "服务端生成的筛选指纹",
  "options": {
    "agents": [
      {
        "id": "agent_example",
        "name": "售后助手"
      }
    ]
  },
  "asOf": 1789603260000
}
```

- 权限由当前登录账号、企业及支持访问范围决定，不能通过传 tenant、actor 或 owner 扩大访问范围。
- 非 tenant_admin 额外限制为本人 actor 的通话。传 conversationId 还会检查真实服务台可见性。
- query 搜索 sessionId、agentName、问句和回答；按 created 和 sessionId 同向排序。
- cursor 模式的 query 或 inputKind 检索必须提供不超过 31 天的 start/end，避免无限扫描历史正文。普通无正文筛选列表不要求日期。游标不是一致性快照，新增导入的旧时间记录可能在后续页出现。
- 详情和导出不按游标截断；导出仍限 500 条及 5 MB，海量导出应使用独立后台任务。
- 详情内容不在 calls 中；用 sessionId 获取完整 turns。新语音会话的录音通过 控制台录音授权入口（不接受 API Key） 授权播放和下载，旧记录可能没有音频。

### 读取总结分析

`GET /v1/operations/analysis.read`

权限：service, agent
费用：按业务权限与套餐执行。

```sh
# cURL 7.76+；请先在服务端设置环境变量。
: "${YUNFU_BASE_URL:?请设置服务端 HTTPS 地址}"
: "${YUNFU_API_KEY:?请设置已获授权的 API 密钥}"
curl --fail-with-body --show-error "$YUNFU_BASE_URL/v1/operations/analysis.read?kind=voice&id=voice_example" \
  -H "Authorization: Bearer $YUNFU_API_KEY"
```

| 字段 | 类型 | 要求 | 说明 |
| --- | --- | --- | --- |
| kind | conversation \| voice \| workflow | 必填 | 来源类型。 |
| id | string | 必填 | 来源 ID，最多 150 字符。 |
| format | md \| json | 可选 | 下载附件；省略时返回 {report}。 |

响应示例：
```json
{
  "report": null
}
```

- 导出只接受 completed 且非 stale 的分析，否则返回 409。
- Markdown 导出返回 text/markdown 附件，不是 JSON 响应。

### 总结分析 · 生成

`POST /v1/operations/analysis.generate`

权限：service, agent
费用：可能产生模型、工具或通话费用。

```sh
# cURL 7.76+；请先在服务端设置环境变量。
: "${YUNFU_BASE_URL:?请设置服务端 HTTPS 地址}"
: "${YUNFU_API_KEY:?请设置已获授权的 API 密钥}"
: "${YUNFU_IDEMPOTENCY_KEY:?请设置本次写入的唯一编号，重试沿用原编号}"
curl --fail-with-body --show-error "$YUNFU_BASE_URL/v1/operations/analysis.generate" \
  -H "Authorization: Bearer $YUNFU_API_KEY" \
  -H "Idempotency-Key: $YUNFU_IDEMPOTENCY_KEY" \
  -H 'Content-Type: application/json' \
  --data-binary '{
  "action": "generate",
  "kind": "conversation",
  "id": "conversation_example"
}'
```

| 字段 | 类型 | 要求 | 说明 |
| --- | --- | --- | --- |
| action | generate \| finish-test | 可选 | 可省略，系统固定为 generate；传入其他值返回 400。 |
| kind | conversation \| voice \| workflow | 必填 | 来源类型。 |
| id | string | 必填 | 来源 ID。 |
| retry | boolean | 可选 | 明确请求重新尝试生成。 |

响应示例：
```json
{
  "report": {
    "status": "queued"
  }
}
```

- 生成可能调用模型并计费；语音演练会话必须先挂断。

### 读取历史记忆

`GET /v1/operations/memory.read`

权限：service
费用：按业务权限与套餐执行。

```sh
# cURL 7.76+；请先在服务端设置环境变量。
: "${YUNFU_BASE_URL:?请设置服务端 HTTPS 地址}"
: "${YUNFU_API_KEY:?请设置已获授权的 API 密钥}"
curl --fail-with-body --show-error "$YUNFU_BASE_URL/v1/operations/memory.read?kind=conversation&id=TEST-TEXT-xxx" \
  -H "Authorization: Bearer $YUNFU_API_KEY"
```

| 字段 | 类型 | 要求 | 说明 |
| --- | --- | --- | --- |
| kind | string | 必填 | conversation / voice / phone / workflow |
| id | string | 必填 | 已授权的原记录编号 |
| all | boolean | 可选 | 分页查询全部关联 |
| format | string | 可选 | json 导出 |

响应示例：
```json
{
  "status": "manual",
  "items": [],
  "usage": []
}
```

- 仅能从有权访问的会话解析主体，不接受任意手机号或设备查询。导出再次检查源权限。

### 历史记忆 · 忽略一条记录

`POST /v1/operations/memory.ignore`

权限：service, memory.manage
费用：按业务权限与套餐执行。

```sh
# cURL 7.76+；请先在服务端设置环境变量。
: "${YUNFU_BASE_URL:?请设置服务端 HTTPS 地址}"
: "${YUNFU_API_KEY:?请设置已获授权的 API 密钥}"
: "${YUNFU_IDEMPOTENCY_KEY:?请设置本次写入的唯一编号，重试沿用原编号}"
curl --fail-with-body --show-error "$YUNFU_BASE_URL/v1/operations/memory.ignore" \
  -H "Authorization: Bearer $YUNFU_API_KEY" \
  -H "Idempotency-Key: $YUNFU_IDEMPOTENCY_KEY" \
  -H 'Content-Type: application/json' \
  --data-binary '{
  "action": "ignore",
  "kind": "conversation",
  "id": "YOUR_CONVERSATION_ID",
  "revision": 1,
  "requestId": "YOUR_STABLE_REQUEST_ID"
}'
```

| 字段 | 类型 | 要求 | 说明 |
| --- | --- | --- | --- |
| kind | string | 必填 | 记忆来源类型：conversation（文字会话）、voice（语音会话）、phone（电话记录）、workflow（工作流运行）。与 memory.read 的查询参数 kind 相同。API Key 身份不能操作 workflow 来源（见说明）。 |
| id | string | 必填 | 来源记录编号，最多 150 字符，与 memory.read 的查询参数 id 相同：conversation 为会话编号，voice 为语音会话编号，phone 为电话记录编号。 |
| revision | integer | 必填 | 当前来源的记忆索引版本：先调用 memory.read?kind=…&id=…，取返回的 row.revision（不小于 1 的整数）。不是 row.policyVersion，也不是 items[].revision。任何一次记忆操作成功后该值都会变化。 |
| requestId | string | 必填 | 业务幂等编号，1–100 字符。同一 requestId 且 kind、id、revision、historyId 都相同的重试直接返回成功、不重复执行；内容不同返回 409。与请求头 Idempotency-Key 相互独立，两者都必须提供。 |

响应示例：
```json
{
  "ok": true
}
```

- 调用前先读取 memory.read?kind=…&id=…：返回的 row 为 null（status 为 no_identity）表示该来源没有记忆索引，本操作会返回 404；否则使用 row.revision。操作成功后 revision 会变化，继续操作前需重新读取。
- 忽略标记写入后，开放操作中没有取消它的方法。生效后 memory.read 对该来源返回 status 为 ignored。
- 公共错误：400「记忆来源无效」（kind 不在四个取值内）；400「会话编号格式无效」（id 为空或超过 150 字符）；400「记忆修订号无效」（revision 不是不小于 1 的整数）；400「请求编号格式无效」（requestId 为空或超过 100 字符）；404「对话不存在或无权查看」「通话不存在或无权查看」「电话记录不存在」（来源记录不存在或当前身份不可见）；404「此会话没有记忆索引」；404「演练记忆不属于当前账号」；409「记忆状态已变化，请刷新」（revision 过期）；409「操作编号已用于其他内容」（requestId 已用于不同内容）；413（请求正文超过 6000 字符）。
- API Key 身份：密钥需同时具备 service 与 memory.manage 权限。kind 为 workflow 的来源还要求 agent 权限，而 memory.* 操作登记的权限不含 agent，因此 API Key 调用会返回 403「无权查看工作流分析」。演练（test）环境的记忆只有创建它的账号本人可以操作，其他情况返回 404。
- 成功后会向已订阅的回调地址发送 memory.invalidated 事件，data 含 sourceKind、sourceId 和 status（此处为 ignore）；同一 requestId 的重复请求不会再次发送。

### 历史记忆 · 排除一条历史记录

`POST /v1/operations/memory.unlink`

权限：service, memory.manage
费用：按业务权限与套餐执行。

```sh
# cURL 7.76+；请先在服务端设置环境变量。
: "${YUNFU_BASE_URL:?请设置服务端 HTTPS 地址}"
: "${YUNFU_API_KEY:?请设置已获授权的 API 密钥}"
: "${YUNFU_IDEMPOTENCY_KEY:?请设置本次写入的唯一编号，重试沿用原编号}"
curl --fail-with-body --show-error "$YUNFU_BASE_URL/v1/operations/memory.unlink" \
  -H "Authorization: Bearer $YUNFU_API_KEY" \
  -H "Idempotency-Key: $YUNFU_IDEMPOTENCY_KEY" \
  -H 'Content-Type: application/json' \
  --data-binary '{
  "action": "unlink",
  "kind": "conversation",
  "id": "YOUR_CONVERSATION_ID",
  "revision": 1,
  "requestId": "YOUR_STABLE_REQUEST_ID",
  "historyId": "YOUR_HISTORY_INDEX_ID"
}'
```

| 字段 | 类型 | 要求 | 说明 |
| --- | --- | --- | --- |
| kind | string | 必填 | 记忆来源类型：conversation（文字会话）、voice（语音会话）、phone（电话记录）、workflow（工作流运行）。与 memory.read 的查询参数 kind 相同。API Key 身份不能操作 workflow 来源（见说明）。 |
| id | string | 必填 | 来源记录编号，最多 150 字符，与 memory.read 的查询参数 id 相同：conversation 为会话编号，voice 为语音会话编号，phone 为电话记录编号。 |
| revision | integer | 必填 | 当前来源的记忆索引版本：先调用 memory.read?kind=…&id=…，取返回的 row.revision（不小于 1 的整数）。不是 row.policyVersion，也不是 items[].revision。任何一次记忆操作成功后该值都会变化。 |
| requestId | string | 必填 | 业务幂等编号，1–100 字符。同一 requestId 且 kind、id、revision、historyId 都相同的重试直接返回成功、不重复执行；内容不同返回 409。与请求头 Idempotency-Key 相互独立，两者都必须提供。 |
| historyId | string | 必填 | 要排除的历史记录的记忆索引编号，最多 100 字符：取 memory.read 返回的 items[].indexId（加 all=true 可分页列出全部历史）。它必须与当前来源属于同一记忆主体，且不能是当前来源自己。 |

响应示例：
```json
{
  "ok": true
}
```

- 调用前先读取 memory.read?kind=…&id=…：返回的 row 为 null（status 为 no_identity）表示该来源没有记忆索引，本操作会返回 404；否则使用 row.revision。操作成功后 revision 会变化，继续操作前需重新读取。
- 被排除的历史记录没有开放操作可以恢复。核对结果：重新读取 memory.read，该 indexId 不再出现在 items 中。
- 公共错误：400「记忆来源无效」（kind 不在四个取值内）；400「会话编号格式无效」（id 为空或超过 150 字符）；400「记忆修订号无效」（revision 不是不小于 1 的整数）；400「请求编号格式无效」（requestId 为空或超过 100 字符）；404「对话不存在或无权查看」「通话不存在或无权查看」「电话记录不存在」（来源记录不存在或当前身份不可见）；404「此会话没有记忆索引」；404「演练记忆不属于当前账号」；409「记忆状态已变化，请刷新」（revision 过期）；409「操作编号已用于其他内容」（requestId 已用于不同内容）；413（请求正文超过 6000 字符）。 本操作另有：404「关联不存在」（historyId 缺失、不是字符串、不属于同一主体，或就是当前来源）；400「关联编号格式无效」（historyId 为空字符串或超过 100 字符）；被排除的历史记录本身对当前身份不可见时，同样返回上述 404。
- API Key 身份：密钥需同时具备 service 与 memory.manage 权限。kind 为 workflow 的来源还要求 agent 权限，而 memory.* 操作登记的权限不含 agent，因此 API Key 调用会返回 403「无权查看工作流分析」。演练（test）环境的记忆只有创建它的账号本人可以操作，其他情况返回 404。
- 成功后会向已订阅的回调地址发送 memory.invalidated 事件，data 含 sourceKind、sourceId 和 status（此处为 unlink）；同一 requestId 的重复请求不会再次发送。

### 历史记忆 · 遗忘

`POST /v1/operations/memory.forget`

权限：service, memory.manage
费用：按业务权限与套餐执行。

```sh
# cURL 7.76+；请先在服务端设置环境变量。
: "${YUNFU_BASE_URL:?请设置服务端 HTTPS 地址}"
: "${YUNFU_API_KEY:?请设置已获授权的 API 密钥}"
: "${YUNFU_IDEMPOTENCY_KEY:?请设置本次写入的唯一编号，重试沿用原编号}"
curl --fail-with-body --show-error "$YUNFU_BASE_URL/v1/operations/memory.forget" \
  -H "Authorization: Bearer $YUNFU_API_KEY" \
  -H "Idempotency-Key: $YUNFU_IDEMPOTENCY_KEY" \
  -H 'Content-Type: application/json' \
  --data-binary '{
  "action": "forget",
  "kind": "conversation",
  "id": "TEST-TEXT-xxx",
  "revision": 1,
  "requestId": "uuid"
}'
```

| 字段 | 类型 | 要求 | 说明 |
| --- | --- | --- | --- |
| action | string | 可选 | 可省略，系统固定为 forget；传入其他值返回 400。 |
| revision | number | 必填 | 当前记忆修订号 |
| requestId | string | 必填 | 幂等操作编号 |

响应示例：
```json
{
  "ok": true
}
```

- 演练记录仅创建人可操作；正式记录需要独立记忆管理权限。清除不删除原始对话，已发给供应商的材料不能物理撤回。

### 历史记忆 · 遗忘并禁止再次使用

`POST /v1/operations/memory.block`

权限：service, memory.manage
费用：按业务权限与套餐执行。

```sh
# cURL 7.76+；请先在服务端设置环境变量。
: "${YUNFU_BASE_URL:?请设置服务端 HTTPS 地址}"
: "${YUNFU_API_KEY:?请设置已获授权的 API 密钥}"
: "${YUNFU_IDEMPOTENCY_KEY:?请设置本次写入的唯一编号，重试沿用原编号}"
curl --fail-with-body --show-error "$YUNFU_BASE_URL/v1/operations/memory.block" \
  -H "Authorization: Bearer $YUNFU_API_KEY" \
  -H "Idempotency-Key: $YUNFU_IDEMPOTENCY_KEY" \
  -H 'Content-Type: application/json' \
  --data-binary '{
  "action": "block",
  "kind": "conversation",
  "id": "YOUR_CONVERSATION_ID",
  "revision": 1,
  "requestId": "YOUR_STABLE_REQUEST_ID"
}'
```

| 字段 | 类型 | 要求 | 说明 |
| --- | --- | --- | --- |
| kind | string | 必填 | 记忆来源类型：conversation（文字会话）、voice（语音会话）、phone（电话记录）、workflow（工作流运行）。与 memory.read 的查询参数 kind 相同。API Key 身份不能操作 workflow 来源（见说明）。 |
| id | string | 必填 | 来源记录编号，最多 150 字符，与 memory.read 的查询参数 id 相同：conversation 为会话编号，voice 为语音会话编号，phone 为电话记录编号。 |
| revision | integer | 必填 | 当前来源的记忆索引版本：先调用 memory.read?kind=…&id=…，取返回的 row.revision（不小于 1 的整数）。不是 row.policyVersion，也不是 items[].revision。任何一次记忆操作成功后该值都会变化。 |
| requestId | string | 必填 | 业务幂等编号，1–100 字符。同一 requestId 且 kind、id、revision、historyId 都相同的重试直接返回成功、不重复执行；内容不同返回 409。与请求头 Idempotency-Key 相互独立，两者都必须提供。 |

响应示例：
```json
{
  "ok": true
}
```

- 调用前先读取 memory.read?kind=…&id=…：返回的 row 为 null（status 为 no_identity）表示该来源没有记忆索引，本操作会返回 404；否则使用 row.revision。操作成功后 revision 会变化，继续操作前需重新读取。
- 禁用是针对整个主体的，开放操作中没有解除禁用的方法，执行前请确认范围；只想清空已有历史而保留今后的记忆能力时，请改用 memory.forget。生效后 memory.read 对该主体已有的来源返回 status 为 blocked；之后新产生的会话不再建立记忆索引，读取时 status 为 no_identity。
- 公共错误：400「记忆来源无效」（kind 不在四个取值内）；400「会话编号格式无效」（id 为空或超过 150 字符）；400「记忆修订号无效」（revision 不是不小于 1 的整数）；400「请求编号格式无效」（requestId 为空或超过 100 字符）；404「对话不存在或无权查看」「通话不存在或无权查看」「电话记录不存在」（来源记录不存在或当前身份不可见）；404「此会话没有记忆索引」；404「演练记忆不属于当前账号」；409「记忆状态已变化，请刷新」（revision 过期）；409「操作编号已用于其他内容」（requestId 已用于不同内容）；413（请求正文超过 6000 字符）。
- API Key 身份：密钥需同时具备 service 与 memory.manage 权限。kind 为 workflow 的来源还要求 agent 权限，而 memory.* 操作登记的权限不含 agent，因此 API Key 调用会返回 403「无权查看工作流分析」。演练（test）环境的记忆只有创建它的账号本人可以操作，其他情况返回 404。
- 成功后会向已订阅的回调地址发送 memory.invalidated 事件，data 含 sourceKind、sourceId 和 status（此处为 block）；同一 requestId 的重复请求不会再次发送。

### 读取客户资料

`GET /v1/operations/customers.read`

权限：customers
费用：按业务权限与套餐执行。

```sh
# cURL 7.76+；请先在服务端设置环境变量。
: "${YUNFU_BASE_URL:?请设置服务端 HTTPS 地址}"
: "${YUNFU_API_KEY:?请设置已获授权的 API 密钥}"
curl --fail-with-body --show-error "$YUNFU_BASE_URL/v1/operations/customers.read" \
  -H "Authorization: Bearer $YUNFU_API_KEY"
```

响应示例：
```json
{
  "customers": [],
  "links": [],
  "page": 1,
  "total": 0
}
```

- 响应示例仅展示其中一个分支的部分字段；其他字段依查询与 action 返回，不能据此生成严格 DTO。
- GET 依照 view 等查询读取客户、字段、导入任务与已有分页；不是统一 cursor/limit REST 协议。批量导入必须按后台分批协议执行，失败项不代表全部成功。客户写入同时受字段、客户和目录版本约束。
- 应用接口沿用原业务去重规则；Bearer 网关增加操作级幂等，不取代 revision 校验。

### 客户资料 · 保存

`POST /v1/operations/customers.save`

权限：customers
费用：按业务权限与套餐执行。

```sh
# cURL 7.76+；请先在服务端设置环境变量。
: "${YUNFU_BASE_URL:?请设置服务端 HTTPS 地址}"
: "${YUNFU_API_KEY:?请设置已获授权的 API 密钥}"
: "${YUNFU_IDEMPOTENCY_KEY:?请设置本次写入的唯一编号，重试沿用原编号}"
curl --fail-with-body --show-error "$YUNFU_BASE_URL/v1/operations/customers.save" \
  -H "Authorization: Bearer $YUNFU_API_KEY" \
  -H "Idempotency-Key: $YUNFU_IDEMPOTENCY_KEY" \
  -H 'Content-Type: application/json' \
  --data-binary '{
  "requestId": "customer_example_1",
  "revision": 12,
  "fieldRevision": 3,
  "customer": {
    "name": "示例客户",
    "phone": "+8613800138000",
    "email": "customer@example.test",
    "company": "示例企业"
  },
  "action": "save"
}'
```

| 字段 | 类型 | 要求 | 说明 |
| --- | --- | --- | --- |
| requestId | string | 必填 | 业务操作编号，8–70 位字母、数字、下划线或连字符；重试保持不变，仍须请求头 Idempotency-Key。 |
| revision | integer | 必填 | 先查询 customers.read?schema=1，使用 catalog.revision。 |
| fieldRevision | integer | 必填 | 同一查询返回的 catalog.fieldRevision。 |
| customer | object | 必填 | 本次保存的客户资料。 |
| customer.name | string | 条件必填：新建客户 | 姓名，最多 200 字符；更新时省略则保留旧值。 |
| customer.phone | string | 可选 | 手机号，最多 200 字符。 |
| customer.email | string | 可选 | 邮箱，最多 200 字符；非空时须为有效邮箱。 |
| customer.company | string | 可选 | 公司名称，最多 200 字符。 |
| customer.id | string | 条件必填：更新已有客户 | 先查询 customers.read?id=客户编号，使用 customer.id。 |
| customer.revision | integer | 条件必填：更新已有客户 | 同一查询返回的 customer.revision，与目录 revision 不同。 |
| customer.values | object | 见说明 | 按 catalog.fields 的键、类型和必填规则校验；更新时省略则保留旧值，新建默认为空对象。 |
| customer.namespace | string | 条件必填：externalId 非空且原档案没有 namespace | 外部客户编号的来源范围，最多 200 字符；更新时省略则沿用原值。 |
| customer.externalId | string | 可选 | 外部客户编号，最多 200 字符；与 namespace 共同唯一。 |
| validateOnly | boolean | 可选 | 默认 false；true 只校验，不保存客户。 |

响应示例：
```json
{
  "ok": true,
  "ids": [
    "USR_EXAMPLE"
  ],
  "count": 1
}
```

- 示例中的版本号须替换为读取值；保存不返回新版本，后续更新前须重新读取。
- 更新时未提供的资料保留旧值；清空可选文本传空字符串，自定义字段按键更新。客户不会按手机号自动合并，重复外部身份会拒绝保存。

### 客户资料 · 批量导入客户

`POST /v1/operations/customers.import`

权限：customers
费用：按业务权限与套餐执行。

```sh
# cURL 7.76+；请先在服务端设置环境变量。
: "${YUNFU_BASE_URL:?请设置服务端 HTTPS 地址}"
: "${YUNFU_API_KEY:?请设置已获授权的 API 密钥}"
: "${YUNFU_IDEMPOTENCY_KEY:?请设置本次写入的唯一编号，重试沿用原编号}"
curl --fail-with-body --show-error "$YUNFU_BASE_URL/v1/operations/customers.import" \
  -H "Authorization: Bearer $YUNFU_API_KEY" \
  -H "Idempotency-Key: $YUNFU_IDEMPOTENCY_KEY" \
  -H 'Content-Type: application/json' \
  --data-binary '{
  "action": "import",
  "requestId": "YOUR_STABLE_REQUEST_ID",
  "revision": 12,
  "fieldRevision": 3,
  "strategy": "create",
  "rows": [
    {
      "name": "示例客户",
      "namespace": "crm-main",
      "externalId": "CUST-1001",
      "phone": "13800138000",
      "email": "customer@example.test",
      "company": "示例企业"
    }
  ]
}'
```

| 字段 | 类型 | 要求 | 说明 |
| --- | --- | --- | --- |
| requestId | string | 必填 | 业务幂等编号，8–70 位字母、数字、下划线或连字符。同一 requestId 加完全相同的正文重试时直接返回首次结果、不重复写入；正文不同返回 409。它与请求头 Idempotency-Key 相互独立，两者都必须提供。 |
| revision | integer | 必填 | 客户目录版本号：先调用 customers.read?schema=1，取返回的 catalog.revision。本企业每次客户资料写入成功后该值都会 +1，而写入响应不返回新值，所以每次写入前都要重新读取。 |
| fieldRevision | integer | 必填 | 自定义字段版本：同一次 customers.read?schema=1 返回的 catalog.fieldRevision；不一致返回 409。 |
| rows | object[] | 必填 | 客户行数组。不带 jobId 时 1–200 行；带 jobId 时 1–100 行，且不能超出任务剩余行数。整个请求正文还受网关 150000 字符上限限制，超出返回 413，应减少每批行数。 |
| rows[].name | string | 条件必填：该行是新建客户（没有命中已有的 namespace + externalId） | 客户姓名，去掉首尾空格后不能为空，最多 200 字符。覆盖已有客户时省略则保留原值。 |
| rows[].namespace | string | 条件必填：该行填写了 externalId | 外部编号的来源范围（例如店铺或 CRM 连接的标识），最多 200 字符。 |
| rows[].externalId | string | 可选 | 外部客户编号，最多 200 字符。namespace + externalId 在企业内唯一，是导入识别已有客户的唯一依据；同一批内不能重复。省略则该行总是新建客户，不会按手机号或姓名合并。 |
| rows[].phone | string | 可选 | 联系电话，最多 200 字符，不校验号码格式；但不能提交带 * 号的脱敏号码（覆盖已有客户且与原号码的脱敏形式一致时视为未修改）。 |
| rows[].email | string | 可选 | 电子邮箱，最多 200 字符；非空时必须是 name@domain.tld 形式。 |
| rows[].wechat | string | 可选 | 微信号，最多 200 字符。 |
| rows[].company | string | 可选 | 所属企业，最多 200 字符。 |
| rows[].category | string | 可选 | 用户分类，最多 200 字符。 |
| rows[].notes | string | 可选 | 资料备注，最多 2000 字符。 |
| rows[].values | object | 见说明 | 自定义字段值，键为 catalog.fields[].key（未停用的字段）。text、select 最多 500 字符，textarea 最多 2000 字符；number 为数字或数字字符串（绝对值不超过 1e15）；boolean 接受 true、false、"是"、"否"、"1"、"0"；date 为 YYYY-MM-DD；select 必须在该字段 options 内；multiselect 为 options 内的字符串数组（最多 30 项，也可传 JSON 数组字符串）。传 null 或空字符串清除该键。定义为必填的字段每行都必须有值。 |
| rows[].tags | string[] | 可选 | 客户标签，最多 20 个，每个 1–30 字符。省略则保留已有客户的标签（新建客户为空）。企业启用了标签组管理（catalog.tagGroupsManaged 为 true）时，只能使用 catalog.tagGroups 中适用于客户且未停用的标签。 |
| strategy | string | 条件必填：携带 jobId | 重复数据策略：update 表示命中已有 namespace + externalId 的行覆盖该客户（行内未提供的资料保留原值）；create 或省略表示命中即报错「外部来源和编号已存在」。带 jobId 时必须与创建任务时的 strategy 相同。 |
| jobId | string | 可选 | customers.importStart 返回的 jobId。携带后本次请求作为该任务的一个分批，写入成功后推进任务进度；只能由创建任务的同一账号使用。 |
| offset | integer | 条件必填：携带 jobId | 本批第一行在任务中的位置，必须等于任务当前的 processed（首批为 0）：通过 customers.read?importJobs=1&jobId=任务编号 读取 jobs[0].processed。 |
| validateOnly | boolean | 可选 | 为 true 时只执行相同的校验并返回 valid、count、fieldRevision，不写入客户、不推进任务。默认 false。 |

响应示例：
```json
{
  "ok": true,
  "ids": [
    "USR-00000000-0000-4000-8000-000000000000"
  ],
  "count": 1
}
```

- 调用前先读取 customers.read?schema=1，取 catalog.revision、catalog.fieldRevision 和字段定义 catalog.fields。revision 在每次写入成功后 +1，连续提交多批时每一批之前都要重新读取。
- 本操作特有的错误：400 且响应带 errors[]（有行不合格，整批未写入，任务进度不变）；400「每批支持 1–200 位用户」（rows 为空、不是数组或超过 200 行）；400「分批大小或进度超出任务范围」（带 jobId 时超过 100 行或超出任务总行数）；404「导入任务不存在」（jobId 不存在或不属于当前账号）；409「资料已变化，请刷新后重试」（revision 过期）；409「字段定义已变化，请重新校验」（fieldRevision 过期）；409「任务进度已变化，请刷新任务后继续」（offset 不等于任务的 processed，或任务已完成）；409「导入字段定义或策略已变化，任务已暂停」（任务创建后字段定义有变化，或 strategy 与任务不一致）；413（正文超过 150000 字符）。
- 重试：结果未知时保持原 requestId 和原正文重试，不会重复写入。没有 externalId 的行如果换一个 requestId 重发，会再次新建客户。
- rows[] 里的 id、revision、confirmation 不生效：导入不能按客户编号更新；写入的客户一律标记为未确认（confirmation 为 unconfirmed），来源记为「CSV 导入」。
- API Key 身份可以调用，没有额外限制；写入的操作人记为密钥所属的企业管理员。

### 客户资料 · 创建分批导入任务

`POST /v1/operations/customers.importStart`

权限：customers
费用：按业务权限与套餐执行。

```sh
# cURL 7.76+；请先在服务端设置环境变量。
: "${YUNFU_BASE_URL:?请设置服务端 HTTPS 地址}"
: "${YUNFU_API_KEY:?请设置已获授权的 API 密钥}"
: "${YUNFU_IDEMPOTENCY_KEY:?请设置本次写入的唯一编号，重试沿用原编号}"
curl --fail-with-body --show-error "$YUNFU_BASE_URL/v1/operations/customers.importStart" \
  -H "Authorization: Bearer $YUNFU_API_KEY" \
  -H "Idempotency-Key: $YUNFU_IDEMPOTENCY_KEY" \
  -H 'Content-Type: application/json' \
  --data-binary '{
  "action": "importStart",
  "requestId": "YOUR_STABLE_REQUEST_ID",
  "revision": 12,
  "fileName": "customers.csv",
  "fileHash": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
  "total": 250,
  "mapping": [
    "name",
    "phone",
    "email",
    "company"
  ],
  "strategy": "create"
}'
```

| 字段 | 类型 | 要求 | 说明 |
| --- | --- | --- | --- |
| requestId | string | 必填 | 业务幂等编号，8–70 位字母、数字、下划线或连字符。同一 requestId 加完全相同的正文重试时直接返回首次结果、不重复写入；正文不同返回 409。它与请求头 Idempotency-Key 相互独立，两者都必须提供。 |
| revision | integer | 必填 | 客户目录版本号：先调用 customers.read?schema=1，取返回的 catalog.revision。本企业每次客户资料写入成功后该值都会 +1，而写入响应不返回新值，所以每次写入前都要重新读取。 |
| fileName | string | 必填 | 源文件名，1–200 字符，仅用于在任务列表中识别。 |
| fileHash | string | 必填 | 源文件指纹：64 个字符，只能包含小写十六进制字符（0-9、a-f）或连字符，例如文件的 SHA-256。之后可用它找回任务；服务端不核对它与实际数据是否对应。 |
| total | integer | 必填 | 任务总行数，1–100000 的整数。任务创建后不能修改。 |
| mapping | string[] | 必填 | 源文件各列对应的目标键，按列顺序排列，1–60 项；要跳过的列填空字符串。必须包含 name 或 enterpriseName，非空项不能重复。可用的键：name、namespace、externalId、phone、email、wechat、company、category、notes、tags、enterpriseName、enterpriseCreditCode、enterprisePhone、enterpriseEmail、values.<未停用自定义字段的 key>、notes:<URL 编码后的列名>。enterpriseName 不能与 company 同时使用，enterprisePhone 不能与 phone 同时使用，enterpriseEmail 不能与 email 同时使用，enterpriseCreditCode 不能与 namespace 或 externalId 同时使用。服务端只保存这份映射，不会用它转换 customers.import 提交的 rows。 |
| strategy | string | 必填 | 重复数据策略，create 或 update，含义同 customers.import；任务的每一批都必须使用相同的值。 |

响应示例：
```json
{
  "ok": true,
  "jobId": "IMPORT-00000000-0000-4000-8000-000000000000"
}
```

- 调用前先读取 customers.read?schema=1，取 catalog.revision。任务会记下创建时的 catalog.fieldRevision；之后字段定义一旦变化，该任务就不能继续，需要重新创建。
- 后续步骤：调用 customers.import，携带 jobId、offset（等于任务当前的 processed）、与任务相同的 strategy，以及每批最多 100 行的 rows。进度通过 customers.read?importJobs=1&jobId=任务编号 读取 jobs[0].processed 与 jobs[0].status（ready → running → completed）；也可以用 importJobs=1&fileHash=文件指纹 找回任务。该查询只返回当前账号最近更新的 30 个任务。
- 本操作特有的错误：400「文件信息无效，单任务最多 100000 行」（total 不是 1–100000 的整数，或 fileHash 格式不符）；400「字段映射无效或重复」；400「重复数据策略无效」；400「文件名格式无效」（fileName 为空或超过 200 字符）；409「资料已变化，请刷新后重试」（revision 过期）。
- API Key 身份可以调用。任务归属于密钥所属的企业管理员账号，只有同一账号可以继续提交和查询。开放操作中没有取消或删除导入任务的操作。

### 客户资料 · 保存跟进设置

`POST /v1/operations/customers.crmSave`

权限：customers
费用：按业务权限与套餐执行。

```sh
# cURL 7.76+；请先在服务端设置环境变量。
: "${YUNFU_BASE_URL:?请设置服务端 HTTPS 地址}"
: "${YUNFU_API_KEY:?请设置已获授权的 API 密钥}"
: "${YUNFU_IDEMPOTENCY_KEY:?请设置本次写入的唯一编号，重试沿用原编号}"
curl --fail-with-body --show-error "$YUNFU_BASE_URL/v1/operations/customers.crmSave" \
  -H "Authorization: Bearer $YUNFU_API_KEY" \
  -H "Idempotency-Key: $YUNFU_IDEMPOTENCY_KEY" \
  -H 'Content-Type: application/json' \
  --data-binary '{
  "action": "crmSave",
  "requestId": "YOUR_STABLE_REQUEST_ID",
  "customerId": "YOUR_CUSTOMER_ID",
  "customerRevision": 4,
  "crmRevision": 0,
  "crm": {
    "ownerId": "YOUR_MEMBER_ID",
    "stage": "following",
    "priority": "normal",
    "nextAt": 0
  }
}'
```

| 字段 | 类型 | 要求 | 说明 |
| --- | --- | --- | --- |
| requestId | string | 必填 | 业务幂等编号，8–70 位字母、数字、下划线或连字符。同一 requestId 加完全相同的正文重试时直接返回首次结果、不重复写入；正文不同返回 409。它与请求头 Idempotency-Key 相互独立，两者都必须提供。 |
| customerId | string | 必填 | 客户编号，最多 100 字符：取 customers.read 或 customer-crm.read 返回的 customer.id。已归档的客户按不存在处理。 |
| customerRevision | integer | 必填 | 客户档案版本：先调用 customer-crm.read?id=客户编号，取返回的 customer.revision。 |
| crmRevision | integer | 必填 | 跟进设置版本：同一次 customer-crm.read 返回的 crm.revision；从未保存过跟进设置的客户为 0。 |
| crm | object | 必填 | 完整的跟进设置。四个子字段每次都必须全部提供，不支持只传有变化的项。 |
| crm.ownerId | string | 必填 | 负责人的成员编号，最多 100 字符：取 customer-crm.read 返回的 owners[].id；空字符串表示不指定负责人。必须是本企业启用中且拥有客户或客服权限的成员。 |
| crm.stage | string | 必填 | 跟进阶段：new（新客户）、following（跟进中）、qualified（意向客户）、customer（已成交）、inactive（暂不跟进）。 |
| crm.priority | string | 必填 | 跟进优先级：normal（普通）、high（重点）、low（低优先）。 |
| crm.nextAt | integer | 必填 | 下次跟进时间，Unix 毫秒；0 表示不安排。大于 0 时必须晚于当前时间（与已保存的值相同时除外）、必须已指定负责人、且 stage 不能是 inactive；上限 4133980800000。 |
| tags | string[] | 可选 | 提供时整体替换该客户的标签：最多 20 个，每个 1–30 字符。省略则保留现有标签。企业启用了标签组管理（catalog.tagGroupsManaged 为 true）时，只能使用 catalog.tagGroups 中适用于客户且未停用的标签，客户已有的标签可以保留。 |

响应示例：
```json
{
  "ok": true,
  "customerId": "YOUR_CUSTOMER_ID",
  "crmRevision": 1
}
```

- 调用前先读取 customer-crm.read?id=客户编号，取 customer.revision、crm.revision 和可选负责人 owners；本操作不需要目录 revision 和 fieldRevision。
- 与 customers.save 的关系：customers.save 修改档案字段（姓名、联系方式、自定义字段），本操作修改跟进设置和标签；两者都会让同一客户的 customer.revision +1，交替调用时每次都要重新读取。
- 本操作特有的错误：400「客户编号无效」；404「客户不存在」（含已归档）；409「客户或跟进资料已更新，请重新载入后编辑」（customerRevision 或 crmRevision 过期）；400「跟进设置格式无效」「请选择有效负责人、跟进状态和优先级」「下次跟进时间无效」「下次跟进时间须晚于当前时间」「设置跟进计划前，请先指定负责人」「暂不跟进的客户请清空下次跟进时间」（crm 校验）；400「负责人须为本企业启用且有客户或客服权限的成员」；400（tags 超过 20 个、单个标签为空或超过 30 字符，或启用标签组管理时选了已停用、不适用于客户的标签）；400「请先由企业管理员在标签管理创建标签，再重新选择」（启用标签组管理时使用了目录中没有的标签）；409「资料或权限已更新，请重新加载；输入已保留」（提交瞬间客户、跟进设置、负责人或密钥状态发生变化）。
- API Key 身份可以调用，没有额外限制：密钥身份具备客户管理权限，可以转派负责人、调整优先级和修改标签。

### 客户资料 · 添加跟进记录

`POST /v1/operations/customers.crmFollowup`

权限：customers
费用：按业务权限与套餐执行。

```sh
# cURL 7.76+；请先在服务端设置环境变量。
: "${YUNFU_BASE_URL:?请设置服务端 HTTPS 地址}"
: "${YUNFU_API_KEY:?请设置已获授权的 API 密钥}"
: "${YUNFU_IDEMPOTENCY_KEY:?请设置本次写入的唯一编号，重试沿用原编号}"
curl --fail-with-body --show-error "$YUNFU_BASE_URL/v1/operations/customers.crmFollowup" \
  -H "Authorization: Bearer $YUNFU_API_KEY" \
  -H "Idempotency-Key: $YUNFU_IDEMPOTENCY_KEY" \
  -H 'Content-Type: application/json' \
  --data-binary '{
  "action": "crmFollowup",
  "requestId": "YOUR_STABLE_REQUEST_ID",
  "customerId": "YOUR_CUSTOMER_ID",
  "customerRevision": 4,
  "crmRevision": 1,
  "crm": {
    "ownerId": "YOUR_MEMBER_ID",
    "stage": "following",
    "priority": "normal",
    "nextAt": 0
  },
  "followup": {
    "kind": "phone",
    "content": "已电话确认需求，客户希望下周收到报价。"
  }
}'
```

| 字段 | 类型 | 要求 | 说明 |
| --- | --- | --- | --- |
| requestId | string | 必填 | 业务幂等编号，8–70 位字母、数字、下划线或连字符。同一 requestId 加完全相同的正文重试时直接返回首次结果、不重复写入；正文不同返回 409。它与请求头 Idempotency-Key 相互独立，两者都必须提供。 |
| customerId | string | 必填 | 客户编号，最多 100 字符：取 customers.read 或 customer-crm.read 返回的 customer.id。已归档的客户按不存在处理。 |
| customerRevision | integer | 必填 | 客户档案版本：先调用 customer-crm.read?id=客户编号，取返回的 customer.revision。 |
| crmRevision | integer | 必填 | 跟进设置版本：同一次 customer-crm.read 返回的 crm.revision；从未保存过跟进设置的客户为 0。 |
| followup | object | 必填 | 本次要追加的跟进记录。 |
| followup.kind | string | 必填 | 沟通方式：note（跟进备注）、phone（电话沟通）、wechat（微信沟通）、email（邮件沟通）、meeting（会议沟通）。 |
| followup.content | string | 必填 | 跟进内容，1–3000 字符，去掉首尾空格后不能为空。 |
| crm | object | 必填 | 完整的跟进设置，必须提供。只想追加记录时，原样回传 customer-crm.read 返回的 crm.ownerId、crm.stage、crm.priority、crm.nextAt；修改其中的值会随本次请求一起保存。 |
| crm.ownerId | string | 必填 | 负责人的成员编号，最多 100 字符：取 customer-crm.read 返回的 owners[].id；空字符串表示不指定负责人。必须是本企业启用中且拥有客户或客服权限的成员。 |
| crm.stage | string | 必填 | 跟进阶段：new（新客户）、following（跟进中）、qualified（意向客户）、customer（已成交）、inactive（暂不跟进）。 |
| crm.priority | string | 必填 | 跟进优先级：normal（普通）、high（重点）、low（低优先）。 |
| crm.nextAt | integer | 必填 | 下次跟进时间，Unix 毫秒；0 表示不安排。大于 0 时必须晚于当前时间（与已保存的值相同时除外）、必须已指定负责人、且 stage 不能是 inactive；上限 4133980800000。 |
| tags | string[] | 可选 | 提供时整体替换该客户的标签：最多 20 个，每个 1–30 字符。省略则保留现有标签。企业启用了标签组管理（catalog.tagGroupsManaged 为 true）时，只能使用 catalog.tagGroups 中适用于客户且未停用的标签，客户已有的标签可以保留。 |

响应示例：
```json
{
  "ok": true,
  "customerId": "YOUR_CUSTOMER_ID",
  "crmRevision": 2
}
```

- 调用前先读取 customer-crm.read?id=客户编号，取 customer.revision、crm.revision 和可选负责人 owners；本操作不需要目录 revision 和 fieldRevision。
- 响应不返回新跟进记录的编号。需要时调用 customer-crm.read?id=客户编号 读取 followups[]（按时间倒序，每页 20 条，用返回的 nextCursor 作为 cursor 参数翻页）；每条记录含 id、kind、content、actorId、actorName、created、nextAt。
- 本操作特有的错误：400「客户编号无效」；404「客户不存在」（含已归档）；409「客户或跟进资料已更新，请重新载入后编辑」（customerRevision 或 crmRevision 过期）；400「跟进设置格式无效」「请选择有效负责人、跟进状态和优先级」「下次跟进时间无效」「下次跟进时间须晚于当前时间」「设置跟进计划前，请先指定负责人」「暂不跟进的客户请清空下次跟进时间」（crm 校验）；400「负责人须为本企业启用且有客户或客服权限的成员」；400（tags 超过 20 个、单个标签为空或超过 30 字符，或启用标签组管理时选了已停用、不适用于客户的标签）；400「请先由企业管理员在标签管理创建标签，再重新选择」（启用标签组管理时使用了目录中没有的标签）；409「资料或权限已更新，请重新加载；输入已保留」（提交瞬间客户、跟进设置、负责人或密钥状态发生变化）。 另有 400「请填写跟进记录（1–3000 字）并选择沟通方式」（followup 缺失、kind 无效或 content 为空、超长）。
- 重试：结果未知时保持原 requestId 和原正文重试，不会重复追加。如果首次请求其实已经成功，换一个 requestId 重发会因版本号已过期返回 409；重新读取版本后再提交才会追加第二条。
- 与 customers.save 的关系：customers.save 修改档案字段（姓名、联系方式、自定义字段），本操作修改跟进设置和标签；两者都会让同一客户的 customer.revision +1，交替调用时每次都要重新读取。
- API Key 身份可以调用，没有额外限制；跟进记录的操作人（actorId、actorName）记为密钥所属的企业管理员。

### 客户资料 · 保存自定义字段定义

`POST /v1/operations/customers.fields`

权限：customers
费用：按业务权限与套餐执行。

```sh
# cURL 7.76+；请先在服务端设置环境变量。
: "${YUNFU_BASE_URL:?请设置服务端 HTTPS 地址}"
: "${YUNFU_API_KEY:?请设置已获授权的 API 密钥}"
: "${YUNFU_IDEMPOTENCY_KEY:?请设置本次写入的唯一编号，重试沿用原编号}"
curl --fail-with-body --show-error "$YUNFU_BASE_URL/v1/operations/customers.fields" \
  -H "Authorization: Bearer $YUNFU_API_KEY" \
  -H "Idempotency-Key: $YUNFU_IDEMPOTENCY_KEY" \
  -H 'Content-Type: application/json' \
  --data-binary '{
  "action": "fields",
  "requestId": "YOUR_STABLE_REQUEST_ID",
  "revision": 12,
  "fields": [
    {
      "key": "memberLevel",
      "label": "会员等级",
      "group": "业务资料",
      "type": "select",
      "options": [
        "普通",
        "黄金"
      ],
      "required": false,
      "ai": true,
      "archived": false
    }
  ]
}'
```

| 字段 | 类型 | 要求 | 说明 |
| --- | --- | --- | --- |
| requestId | string | 必填 | 业务幂等编号，8–70 位字母、数字、下划线或连字符。同一 requestId 加完全相同的正文重试时直接返回首次结果、不重复写入；正文不同返回 409。它与请求头 Idempotency-Key 相互独立，两者都必须提供。 |
| revision | integer | 必填 | 客户目录版本号：先调用 customers.read?schema=1，取返回的 catalog.revision。本企业每次客户资料写入成功后该值都会 +1，而写入响应不返回新值，所以每次写入前都要重新读取。 |
| fields | object[] | 必填 | 完整的字段定义列表，0–50 项：必须包含 customers.read?schema=1 返回的 catalog.fields 中全部已有字段（按 key 对应），再加上要新增的字段；缺少任何一个已有 key 都会被拒绝。数组顺序就是保存后的顺序。 |
| fields[].key | string | 必填 | 字段标识：字母开头，只含字母、数字、下划线，1–50 字符，列表内唯一，不能是 constructor、prototype 或 __proto__。它就是客户资料 values 对象里的键，创建后不能更改。 |
| fields[].label | string | 必填 | 字段显示名称，1–60 字符，不能全是空白。 |
| fields[].type | string | 必填 | 字段类型：text（单行文本）、textarea（多行文本）、number（数值）、boolean（是 / 否）、date（日期）、select（单选）、multiselect（多选）。已有字段不能更改类型。 |
| fields[].options | string[] | 条件必填：type 为 select 或 multiselect | 选项列表：去掉空白和重复后 1–30 项，每项最多 80 字符。已有字段原来的选项必须全部保留，只能追加。 |
| fields[].group | string | 可选 | 分组名称，超过 40 字符的部分会被截断；省略或为空时为「业务资料」。 |
| fields[].required | boolean | 见说明 | 是否必填，只有 true 生效；省略即为 false，不会沿用旧值。设为必填后，之后每次保存或导入客户都必须提供该字段的值。 |
| fields[].ai | boolean | 可选 | 是否允许作为客户变量提供给智能体。省略时已有字段沿用旧值，新字段默认为 true。 |
| fields[].archived | boolean | 见说明 | 是否停用，只有 true 生效；省略即为 false，会把已停用的字段重新启用。停用后的字段不再接受新值，也不再做必填检查。 |

响应示例：
```json
{
  "ok": true
}
```

- 调用前先读取 customers.read?schema=1，取 catalog.revision 和现有的 catalog.fields；在现有列表的基础上修改后整体提交。
- 响应只有 ok，不返回新的 fieldRevision：保存后重新读取 customers.read?schema=1，再把新的 fieldRevision 用于 customers.save 和 customers.import。
- 副作用：fieldRevision 变化后，尚未完成的分批导入任务不能继续（customers.import 返回 409），其他调用方持有的旧 fieldRevision 也会返回 409。
- 本操作特有的错误：400「最多 50 个自定义字段」（fields 不是数组或超过 50 项）；400「字段标识无效或重复」；400「字段名称或类型无效」；400「已有字段不能更改类型，请创建新字段」；400「单选或多选字段需 1–30 个有效选项」；400「已有选项需保留，避免历史资料失效」；400「已有字段请停用，不可删除历史定义」；409「资料已变化，请刷新后重试」（revision 过期）。
- API Key 身份可以调用，没有额外限制。

### 客户资料 · 将会话关联到客户

`POST /v1/operations/customers.bind`

权限：customers, service
费用：按业务权限与套餐执行。

```sh
# cURL 7.76+；请先在服务端设置环境变量。
: "${YUNFU_BASE_URL:?请设置服务端 HTTPS 地址}"
: "${YUNFU_API_KEY:?请设置已获授权的 API 密钥}"
: "${YUNFU_IDEMPOTENCY_KEY:?请设置本次写入的唯一编号，重试沿用原编号}"
curl --fail-with-body --show-error "$YUNFU_BASE_URL/v1/operations/customers.bind" \
  -H "Authorization: Bearer $YUNFU_API_KEY" \
  -H "Idempotency-Key: $YUNFU_IDEMPOTENCY_KEY" \
  -H 'Content-Type: application/json' \
  --data-binary '{
  "action": "bind",
  "requestId": "YOUR_STABLE_REQUEST_ID",
  "revision": 12,
  "conversationId": "YOUR_CONVERSATION_ID",
  "conversationVersion": 5,
  "linkRevision": 0,
  "customerId": "YOUR_CUSTOMER_ID",
  "customerRevision": 4,
  "reason": "客户来电确认与该档案为同一人"
}'
```

| 字段 | 类型 | 要求 | 说明 |
| --- | --- | --- | --- |
| requestId | string | 必填 | 业务幂等编号，8–70 位字母、数字、下划线或连字符。同一 requestId 加完全相同的正文重试时直接返回首次结果、不重复写入；正文不同返回 409。它与请求头 Idempotency-Key 相互独立，两者都必须提供。 |
| revision | integer | 必填 | 客户目录版本号：先调用 customers.read?schema=1，取返回的 catalog.revision。本企业每次客户资料写入成功后该值都会 +1，而写入响应不返回新值，所以每次写入前都要重新读取。 |
| conversationId | string | 必填 | 要调整关联的会话编号，必须是当前身份可见的会话。 |
| conversationVersion | integer | 必填 | 该会话当前的 version：取 customers.bindPreview 返回的 conversationVersion。 |
| linkRevision | integer | 必填 | 该会话当前客户关联的版本：同一次 customers.bindPreview 返回的 linkRevision；会话还没有关联任何客户时为 0。 |
| customerId | string | 可选 | 目标客户编号，最多 100 字符。省略或传空字符串表示解除该会话的客户关联。不能与会话当前关联的客户相同。 |
| customerRevision | integer | 条件必填：customerId 非空 | 目标客户档案的当前版本：同一次 customers.bindPreview 返回的 customerRevision。 |
| reason | string | 必填 | 关联原因，1–300 字符，会写入关联变更记录。 |

响应示例：
```json
{
  "ok": true,
  "identityEvent": {
    "id": "00000000-0000-4000-8000-000000000000",
    "conversationId": "YOUR_CONVERSATION_ID",
    "fromCustomerId": "",
    "toCustomerId": "YOUR_CUSTOMER_ID",
    "fromName": "",
    "toName": "示例客户",
    "linkRevision": 1,
    "reason": "客户来电确认与该档案为同一人",
    "actor": "示例管理员",
    "created": 1791201600000,
    "source": {
      "platformId": "web",
      "platformName": "网页客服",
      "channelId": "YOUR_CHANNEL_ID",
      "channelName": "官网客服",
      "entryId": "YOUR_ENTRY_ID",
      "entryName": "默认入口",
      "entryKind": "web",
      "accountId": "",
      "externalId": "",
      "capturedAt": "2026-10-08T02:00:00.000Z",
      "configRevision": 3,
      "provenance": "web_entry",
      "channelKey": "YOUR_CHANNEL_ID",
      "entryKey": "[\"YOUR_CHANNEL_ID\",\"YOUR_ENTRY_ID\"]",
      "label": "官网客服 / 默认入口"
    },
    "undoOf": ""
  }
}
```

- 需要账号同时具备 customers 与 service 权限：会话可见性来自客服工作台。
- 调用前先读取 customers.bindPreview?conversationId=会话编号&customerId=客户编号：返回 catalogRevision（即 revision）、conversationVersion、linkRevision、customerRevision，以及两份档案的字段差异 conflicts，供人工确认是否为同一人。
- 本操作特有的错误：409「资料已变化，请刷新后重试」（revision 过期）；409「会话不存在、不可见或已变化」（会话不可见，或 conversationVersion 过期）；409「用户不存在或资料已更新」（客户不存在、已归档，或 customerRevision 过期）；409「关联关系已变化」（linkRevision 过期）；400「关联对象未变化」（目标客户就是当前关联的客户，或会话本来就没有关联却要解除）；400「关联原因格式无效」（reason 为空或超过 300 字符）；400「用户编号格式无效」（customerId 超过 100 字符或不是字符串）。
- 成功后该会话的客户服务记录改挂到新客户（解除关联时移除）；两份客户档案的资料都不会被修改或合并。

### 读取客户跟进

`GET /v1/operations/customer-crm.read`

权限：customers
费用：按业务权限与套餐执行。

```sh
# cURL 7.76+；请先在服务端设置环境变量。
: "${YUNFU_BASE_URL:?请设置服务端 HTTPS 地址}"
: "${YUNFU_API_KEY:?请设置已获授权的 API 密钥}"
curl --fail-with-body --show-error "$YUNFU_BASE_URL/v1/operations/customer-crm.read?id=%3Cid%3E" \
  -H "Authorization: Bearer $YUNFU_API_KEY"
```

| 字段 | 类型 | 要求 | 说明 |
| --- | --- | --- | --- |
| id (query) | string | 必填 | 客户编号，必填。 |
| cursor (query) | string | 可选 | 服务端返回的不透明分页游标。 |

响应示例：
```json
{
  "followups": [],
  "owners": [],
  "canManage": false,
  "canFollowup": false,
  "nextCursor": null
}
```

- 响应示例仅展示其中一个分支的部分字段；其他字段依查询与 action 返回，不能据此生成严格 DTO。
- 仅 GET，读取 CRM、跟进记录和可见资源。修改通过 customers.crmSave / customers.crmFollowup，不能用详情页 revision 代替 customerRevision/crmRevision。
- 应用接口沿用原业务去重规则；Bearer 网关增加操作级幂等，不取代 revision 校验。

### 读取邮件与AI接待

`GET /v1/operations/email.read`

权限：service
费用：按业务权限与套餐执行。

```sh
# cURL 7.76+；请先在服务端设置环境变量。
: "${YUNFU_BASE_URL:?请设置服务端 HTTPS 地址}"
: "${YUNFU_API_KEY:?请设置已获授权的 API 密钥}"
curl --fail-with-body --show-error "$YUNFU_BASE_URL/v1/operations/email.read?view=mailbox&folder=inbox&page=1" \
  -H "Authorization: Bearer $YUNFU_API_KEY"
```

| 字段 | 类型 | 要求 | 说明 |
| --- | --- | --- | --- |
| view (query) | string | 必填 | 固定mailbox，不能切换到客户上下文 |
| messageId (query) | string | 可选 | 可选真实邮件ID；读取单封可使用folder=all |
| folder (query) | string | 可选 | 邮件文件夹 |
| q (query) | string | 可选 | 搜索当前范围正文/主题/联系人 |
| page (query) | integer | 可选 | 从1开始，单页最多30条 |

响应示例：
```json
{
  "folder": "inbox",
  "page": 1,
  "total": 0,
  "rows": [],
  "connections": []
}
```

- 只读取当前账号授权邮箱；邮箱匹配不是身份认证。
- 示例未实际执行；AI可能计费，发送需用户明确授权。

### 邮件与AI接待 · 标记单封邮件

`POST /v1/operations/email.mark`

权限：service
费用：按业务权限与套餐执行。

```sh
# cURL 7.76+；请先在服务端设置环境变量。
: "${YUNFU_BASE_URL:?请设置服务端 HTTPS 地址}"
: "${YUNFU_API_KEY:?请设置已获授权的 API 密钥}"
: "${YUNFU_IDEMPOTENCY_KEY:?请设置本次写入的唯一编号，重试沿用原编号}"
curl --fail-with-body --show-error "$YUNFU_BASE_URL/v1/operations/email.mark" \
  -H "Authorization: Bearer $YUNFU_API_KEY" \
  -H "Idempotency-Key: $YUNFU_IDEMPOTENCY_KEY" \
  -H 'Content-Type: application/json' \
  --data-binary '{
  "action": "mark",
  "messageId": "YOUR_MESSAGE_ID",
  "field": "review",
  "value": "done"
}'
```

| 字段 | 类型 | 要求 | 说明 |
| --- | --- | --- | --- |
| messageId | string | 必填 | 邮件编号，最多 100 个字符。取 email.read（如 ?view=mailbox&folder=inbox）返回的 rows[].id；只能是收到的邮件，已发送邮件和草稿不可标记。 |
| field | string | 必填 | 要修改的状态：read（已读）、star（星标）、archive（归档）、review（处理状态）、category（分类）、label（标签）、aiTask（AI 待办状态）。 |
| value | string | 必填 | 新值，类型随 field 而定。read、star、archive：JSON 布尔值 true 或 false；review：open（待处理）或 done（已处理）；category：primary、updates、promotions、social 或 spam；aiTask：open、done 或 dismissed；label：标签名称，1–32 个字符，不能含 <、> 或控制字符。 |
| applied | boolean | 条件必填：field 为 label | true 给邮件加上该标签，false 移除该标签；必须是 JSON 布尔值。 |

响应示例：
```json
{
  "messageId": "YOUR_MESSAGE_ID",
  "field": "review",
  "value": "done"
}
```

- 前置条件：企业需已开通邮件应用；先调用 email.read 取得 rows[].id。本操作不需要版本号。
- 没有批量接口：一次只处理一封邮件的一个字段，批量整理需逐封调用，并受密钥每分钟限额约束。
- 标签：每封邮件最多 20 个标签。内置标签为 orders、refunds、shipping、billing、support、complaints、campaigns；添加其他名称时会自动在密钥所属账号的标签列表中创建该标签。
- AI 待办：只有邮件已有 AI 待办（email.read 返回的 rows[].ai_action_text 非空）时才能修改 aiTask，否则返回 409。
- 错误：400 messageId 为空或过长、邮件不是收到的邮件、field 不在允许值内、value 类型或取值不符、标签名称无效、标签超过 20 个；403 企业未开通邮件应用；404 邮件不存在或对密钥所属账号不可见；409 标签被并发修改（“标签已变化，请刷新后重试”）或邮件、权限已变化。
- 重复调用：read、star、archive、review、category 是覆盖写入，重复调用结果一致；其中 read=true 每次都会把已读时间更新为当前时间。
- API Key 调用的限制：密钥以所属管理员账号的身份执行，只能标记企业共享邮箱和该账号本人邮箱中的邮件；归属于其他成员的邮箱中的邮件返回 404。自定义标签也记在该账号名下。

### 邮件与AI接待 · 保存草稿

`POST /v1/operations/email.saveDraft`

权限：service
费用：按业务权限与套餐执行。

```sh
# cURL 7.76+；请先在服务端设置环境变量。
: "${YUNFU_BASE_URL:?请设置服务端 HTTPS 地址}"
: "${YUNFU_API_KEY:?请设置已获授权的 API 密钥}"
: "${YUNFU_IDEMPOTENCY_KEY:?请设置本次写入的唯一编号，重试沿用原编号}"
curl --fail-with-body --show-error "$YUNFU_BASE_URL/v1/operations/email.saveDraft" \
  -H "Authorization: Bearer $YUNFU_API_KEY" \
  -H "Idempotency-Key: $YUNFU_IDEMPOTENCY_KEY" \
  -H 'Content-Type: application/json' \
  --data-binary '{
  "action": "saveDraft",
  "id": "stable-draft-id",
  "bindingId": "binding-id",
  "replyToId": "message-id",
  "recipient": "customer@example.test",
  "subject": "Re: 咨询",
  "body": "已核对的回复"
}'
```

| 字段 | 类型 | 要求 | 说明 |
| --- | --- | --- | --- |
| action | string | 可选 | 可省略，系统固定为 saveDraft；传入其他值返回 400。 |
| id | string | 见说明 | 稳定草稿ID；MCP新草稿同样必填 |
| revision | integer | 可选 | 修改已有草稿时必须提供当前修订号 |
| bindingId | string | 可选 | 可选当前账号可见邮箱连接ID；空值只保存草稿，不能发送。 |
| replyToId | string | 可选 | 回复时传原邮件ID |
| recipient | string | 可选 | 收件人邮箱，未发送草稿可留空 |
| subject | string | 可选 | 主题 |
| body | string | 可选 | 纯文本正文 |
| agentId | string | 可选 | 可选已发布智能体ID；空值表示默认邮件助手，随草稿保存并恢复。 |

响应示例：
```json
{
  "draft": {
    "id": "stable-draft-id",
    "revision": 1
  }
}
```

- 只读取当前账号授权邮箱；邮箱匹配不是身份认证。
- 示例未实际执行；AI可能计费，发送需用户明确授权。
- 提供稳定 Idempotency-Key；生成保持 requestId，修改/发送携带当前草稿revision；未知结果沿用原ID核查。

### 邮件与AI接待 · 发送草稿

`POST /v1/operations/email.sendDraft`

权限：service
费用：可能产生模型、工具或通话费用。

```sh
# cURL 7.76+；请先在服务端设置环境变量。
: "${YUNFU_BASE_URL:?请设置服务端 HTTPS 地址}"
: "${YUNFU_API_KEY:?请设置已获授权的 API 密钥}"
: "${YUNFU_IDEMPOTENCY_KEY:?请设置本次写入的唯一编号，重试沿用原编号}"
curl --fail-with-body --show-error "$YUNFU_BASE_URL/v1/operations/email.sendDraft" \
  -H "Authorization: Bearer $YUNFU_API_KEY" \
  -H "Idempotency-Key: $YUNFU_IDEMPOTENCY_KEY" \
  -H 'Content-Type: application/json' \
  --data-binary '{
  "action": "sendDraft",
  "id": "stable-draft-id",
  "revision": 1,
  "confirmed": true
}'
```

| 字段 | 类型 | 要求 | 说明 |
| --- | --- | --- | --- |
| action | string | 可选 | 可省略，系统固定为 sendDraft；传入其他值返回 400。 |
| id | string | 必填 | 已核对的草稿ID |
| revision | integer | 必填 | 当前草稿修订号 |
| confirmed | boolean | 必填 | 发送必须true；仍需用户对收件人和内容的明确授权 |

响应示例：
```json
{
  "draft": {
    "id": "stable-draft-id",
    "status": "sent"
  },
  "message": {
    "status": "accepted"
  }
}
```

- 只读取当前账号授权邮箱；邮箱匹配不是身份认证。
- 示例未实际执行；AI可能计费，发送需用户明确授权。
- 提供稳定 Idempotency-Key；生成保持 requestId，修改/发送携带当前草稿revision；未知结果沿用原ID核查。

### 读取黑名单

`GET /v1/operations/blacklist.read`

权限：service
费用：按业务权限与套餐执行。

```sh
# cURL 7.76+；请先在服务端设置环境变量。
: "${YUNFU_BASE_URL:?请设置服务端 HTTPS 地址}"
: "${YUNFU_API_KEY:?请设置已获授权的 API 密钥}"
curl --fail-with-body --show-error "$YUNFU_BASE_URL/v1/operations/blacklist.read" \
  -H "Authorization: Bearer $YUNFU_API_KEY"
```

响应示例：
```json
{
  "groups": [],
  "entries": [],
  "stats": {
    "total": 0,
    "active": 0,
    "phone": 0,
    "address": 0,
    "customer": 0
  },
  "canManage": false
}
```

- 读取须单独授权 blacklist.read；不因具有导入权限而自动获得。

### 导入黑名单

`POST /v1/operations/blacklist.import`

权限：service, agent
费用：按业务权限与套餐执行。

```sh
# cURL 7.76+；请先在服务端设置环境变量。
: "${YUNFU_BASE_URL:?请设置服务端 HTTPS 地址}"
: "${YUNFU_API_KEY:?请设置已获授权的 API 密钥}"
: "${YUNFU_IDEMPOTENCY_KEY:?请设置本次写入的唯一编号，重试沿用原编号}"
curl --fail-with-body --show-error "$YUNFU_BASE_URL/v1/operations/blacklist.import" \
  -H "Authorization: Bearer $YUNFU_API_KEY" \
  -H "Idempotency-Key: $YUNFU_IDEMPOTENCY_KEY" \
  -H 'Content-Type: application/json' \
  --data-binary '{
  "entries": [
    {
      "kind": "phone",
      "value": "13800138000",
      "label": "拒绝营销",
      "reason": "客户要求",
      "expiresAt": 0
    }
  ]
}'
```

| 字段 | 类型 | 要求 | 说明 |
| --- | --- | --- | --- |
| entries | array | 必填 | 每批 1–1000 条；建议每批 500 条。 |
| kind | string | 必填 | phone 手机号、address 设备地址 / IP、customer 客户标识。 |
| value | string | 必填 | 必须为字符串；手机号最多 40 字符，其他值最多 200 字符。 |
| groupId | string | 未注明 | 本企业已有分组 ID，省略或空字符串为未分组。 |
| label | string | 未注明 | 备注标签，最多 80 字符。 |
| reason | string | 未注明 | 加入原因，最多 240 字符。 |
| expiresAt | integer | 未注明 | Unix 毫秒时间戳；省略或 0 为永久，最远不超过当前时间后 10 年。 |

响应示例：
```json
{
  "import": {
    "inserted": 1,
    "duplicates": 0
  }
}
```

- 服务端集成使用 /v1/operations/blacklist.import 和 Bearer 密钥；/v1/operations/blacklist.import 仍要求同源登录 Cookie。
- API 只返回本批计数；Cookie 管理页另返回最新名单。导入权限不包含读取、删除、启停或修改策略。
- 最多 1000 条且 JSON 正文不超过 150,000 个 UTF-16 码元（UTF-8 最多 450,000 字节），超限请拆批。
- 任何无效行或跨企业分组使整批失败。手机号按现有规则归一化，设备地址及客户标识忽略大小写。
- 不覆盖重复条目的启停状态、标签、原因、分组或有效期；导入不自动启用黑名单策略。
- 超时用相同编号重试；409 时先核对调用记录，429 按 Retry-After 等待。不要更换编号盲目重复提交。
- Bearer 网关必须携带 Idempotency-Key；同一批重试保持请求编号和正文不变，新批次使用新编号。

### 读取工作台与工单

`GET /v1/operations/desk.read`

权限：service
费用：按业务权限与套餐执行。

```sh
# cURL 7.76+；请先在服务端设置环境变量。
: "${YUNFU_BASE_URL:?请设置服务端 HTTPS 地址}"
: "${YUNFU_API_KEY:?请设置已获授权的 API 密钥}"
curl --fail-with-body --show-error "$YUNFU_BASE_URL/v1/operations/desk.read" \
  -H "Authorization: Bearer $YUNFU_API_KEY"
```

响应示例：
```json
{
  "state": {
    "conversations": []
  }
}
```

- 响应示例仅展示其中一个分支的部分字段；其他字段依查询与 action 返回，不能据此生成严格 DTO。
- GET 返回按角色和成员范围投影的 state；summary=1 返回接待摘要。send/note 发送消息或备注，claim 接管，close/endConversation 结束，reopen 重新接待，handoff/acceptHandoff/cancelHandoff 邀请、接收或撤回转接，createTask 创建待办，createTicket/transferTicket/workStatus 管理工单。API Key 写入仅在本地工作台存储模式支持；Go 远程模式尚未接入提交时撤权校验，拒绝网关写入。
- createTask 可使用已授权的 desk.createTask 公开操作。先读取最新 revision 与本企业已启用成员，填写 data.title/content/owner/ownerId/due/kind；content 必填，最多 3000 个 UTF-16 单位，创建时保存 createdAt/updatedAt。企业管理员有 service 权限时读取本企业全部待办；客服仍按本人、主管组与有效转接授权范围读取。
- createTicket 使用相同的创建示例字段并将 action 改为 createTicket，kind 必须为有效工单模板；data.content 必填，最多 3000 个 UTF-16 单位，独立保存并记录 createdAt/updatedAt。工单状态流转和重开保留正文；旧记录和系统生成工单可缺少正文。
- cancelHandoff 仅当前负责人或正常企业管理员有 service 权限时可用，支持访问不可用；需最新 revision/version 及 data.offerId。有效邀请存在时不能重复 handoff；已接收或失效邀请不能撤回。撤回保留原负责人，不发送客户消息。
- releaseToAI 仅当前接待负责人可调用，使用最新 revision/version，可带不超过 1000 字的 data.handoffSummary。会话有未知结果、待审批动作，或接待组为影子/建议模式时拒绝交回；成功后由 AI 接待下一条访客消息，不等于已对客户发送回复。
- 应用接口沿用原业务去重规则；Bearer 网关增加操作级幂等，不取代 revision 校验。

### 工作台与工单 · 发送消息

`POST /v1/operations/desk.send`

权限：service
费用：按业务权限与套餐执行。

```sh
# cURL 7.76+；请先在服务端设置环境变量。
: "${YUNFU_BASE_URL:?请设置服务端 HTTPS 地址}"
: "${YUNFU_API_KEY:?请设置已获授权的 API 密钥}"
: "${YUNFU_IDEMPOTENCY_KEY:?请设置本次写入的唯一编号，重试沿用原编号}"
curl --fail-with-body --show-error "$YUNFU_BASE_URL/v1/operations/desk.send" \
  -H "Authorization: Bearer $YUNFU_API_KEY" \
  -H "Idempotency-Key: $YUNFU_IDEMPOTENCY_KEY" \
  -H 'Content-Type: application/json' \
  --data-binary '{
  "action": "send",
  "requestId": "YOUR_STABLE_REQUEST_ID",
  "revision": 1,
  "id": "YOUR_CONVERSATION_ID",
  "version": 1,
  "data": {
    "text": "您好，已收到您的问题。"
  }
}'
```

| 字段 | 类型 | 要求 | 说明 |
| --- | --- | --- | --- |
| requestId | string | 必填 | 稳定业务操作编号，8–70 位字母、数字、下划线或连字符；重试保持不变，同时仍须 Idempotency-Key。 |
| revision | integer | 必填 | 先读取 desk.read 返回的 state.revision。 |
| id | string | 必填 | 已授权的会话编号。 |
| version | integer | 必填 | 该会话当前 version；变更后须重新读取。 |
| data | object | 必填 | 业务字段见请求示例；文本位于 data.text。 |

响应示例：
```json
{
  "state": {
    "revision": 2,
    "conversations": []
  },
  "result": "操作结果"
}
```

- 示例中的 revision、version 和资源编号必须替换为当前读取值；未收到最终回执时，先读取原业务结果。
- 发送前须接管且拥有会话；通道发送结果按业务回执核对。

### 工作台与工单 · 添加会话内部备注

`POST /v1/operations/desk.note`

权限：service
费用：按业务权限与套餐执行。

```sh
# cURL 7.76+；请先在服务端设置环境变量。
: "${YUNFU_BASE_URL:?请设置服务端 HTTPS 地址}"
: "${YUNFU_API_KEY:?请设置已获授权的 API 密钥}"
: "${YUNFU_IDEMPOTENCY_KEY:?请设置本次写入的唯一编号，重试沿用原编号}"
curl --fail-with-body --show-error "$YUNFU_BASE_URL/v1/operations/desk.note" \
  -H "Authorization: Bearer $YUNFU_API_KEY" \
  -H "Idempotency-Key: $YUNFU_IDEMPOTENCY_KEY" \
  -H 'Content-Type: application/json' \
  --data-binary '{
  "action": "note",
  "requestId": "YOUR_STABLE_REQUEST_ID",
  "revision": 12,
  "id": "YOUR_CONVERSATION_ID",
  "version": 3,
  "data": {
    "text": "客户已提供订单号，等待仓库核实。"
  }
}'
```

| 字段 | 类型 | 要求 | 说明 |
| --- | --- | --- | --- |
| requestId | string | 必填 | 业务操作编号，8–70 位字母、数字、下划线或连字符，由调用方生成。重试同一次操作时保持不变且正文完全一致，服务端回放原结果而不重复执行；它与请求头 Idempotency-Key 相互独立，两者都必须提供。 |
| revision | integer | 必填 | 工作台版本：先调用 desk.read，取返回的 state.revision。必须与服务端当前值完全相等，否则返回 409；工作台的每次写入都会使它递增。 |
| id | string | 必填 | 会话编号：取 desk.read 返回的 state.conversations[].id。 |
| version | integer | 必填 | 该会话的 version：取同一次 desk.read 返回的 state.conversations[].version。不是非负整数返回 400，与当前值不相等返回 409。 |
| data | object | 必填 | 备注内容。 |
| data.text | string | 必填 | 备注正文，去除首尾空白后不能为空，最多 4000 个字符（含首尾空白）。 |
| data.mentions | object[] | 可选 | 要提及（@）的同事，最多 20 项；省略表示不提及。每项只允许 accountId、start、end 三个键，被提及成员会收到备注提及通知。 |
| data.mentions[].accountId | string | 条件必填：提供 data.mentions 时 | 被提及成员的账号编号：取 desk.read 返回的 state.members[].id；成员须为状态“已启用”、角色为企业管理员或人工客服。 |
| data.mentions[].start | integer | 条件必填：提供 data.mentions 时 | data.text 中“@成员姓名”片段的起始下标，从 0 开始，按提交的原始 data.text 计算。 |
| data.mentions[].end | integer | 条件必填：提供 data.mentions 时 | 片段的结束下标（不含）。data.text 从 start 到 end 的内容必须恰好等于“@”加该成员在 state.members[] 中的 name，各片段不得重叠。 |

响应示例：
```json
{
  "state": {
    "revision": 13,
    "conversations": [
      {
        "id": "YOUR_CONVERSATION_ID",
        "version": 3,
        "lifecycle": "OPEN",
        "handling": "HUMAN",
        "owner": "示例管理员",
        "ownerId": "YOUR_ACCOUNT_ID",
        "messages": [
          {
            "id": "MSG-1a2b3c4d",
            "role": "note",
            "text": "客户已提供订单号，等待仓库核实。",
            "author": "示例管理员",
            "authorId": "YOUR_ACCOUNT_ID",
            "time": "10:30",
            "timestamp": "2026-11-16T02:30:00.000Z"
          }
        ]
      }
    ]
  },
  "result": "内部备注已保存",
  "executionReceipt": null
}
```

- 调用前先用 desk.read 读取最新 state，取 state.revision 和目标会话的 version；任一与服务端不符返回 409，须重新读取后改用新的 Idempotency-Key 提交（旧 Idempotency-Key 已绑定原正文，不能复用；requestId 可以沿用）。
- 状态前置：进行中的会话必须先由调用账号接管（handling 为 HUMAN 且 ownerId 为调用账号，可先调用 desk.claim），否则返回 403；已关闭的会话可直接添加备注。
- 400：data.text 为空或超过 4000 个字符；出现 data.media；出现 data.replyToMessageId；data.mentions 不是数组、超过 20 项或某项格式不符。409：被提及成员已停用、角色不符，或 start/end 与“@姓名”不吻合。413：整个请求正文超过 20000 个字符。
- API Key 以创建该密钥的企业管理员账号身份执行，本契约中的“调用账号”均指该管理员账号。工作台以远程存储模式部署时，API Key 的工作台写操作一律返回 503。
- API Key 调用不支持备注图片：只要正文出现 data.mediaIds（包括空数组）就返回 403。
- 结果未知时（超时或断连）先用 desk.read 核对目标状态。需要重发时保持原 requestId 和完全相同的正文（含原 revision、version）：服务端按 requestId 去重，已执行则回放原 result 而不重复执行，更换 Idempotency-Key 后也是如此。同一 requestId 搭配不同正文返回 409。
- 错误响应正文为 {"error":"原因说明"}。requestId 不符合格式、revision 不是非负整数返回 400；会话编号不存在返回 404。

### 工作台与工单 · 关闭本人接待的会话

`POST /v1/operations/desk.close`

权限：service
费用：按业务权限与套餐执行。

```sh
# cURL 7.76+；请先在服务端设置环境变量。
: "${YUNFU_BASE_URL:?请设置服务端 HTTPS 地址}"
: "${YUNFU_API_KEY:?请设置已获授权的 API 密钥}"
: "${YUNFU_IDEMPOTENCY_KEY:?请设置本次写入的唯一编号，重试沿用原编号}"
curl --fail-with-body --show-error "$YUNFU_BASE_URL/v1/operations/desk.close" \
  -H "Authorization: Bearer $YUNFU_API_KEY" \
  -H "Idempotency-Key: $YUNFU_IDEMPOTENCY_KEY" \
  -H 'Content-Type: application/json' \
  --data-binary '{
  "action": "close",
  "requestId": "YOUR_STABLE_REQUEST_ID",
  "revision": 12,
  "id": "YOUR_CONVERSATION_ID",
  "version": 3
}'
```

| 字段 | 类型 | 要求 | 说明 |
| --- | --- | --- | --- |
| requestId | string | 必填 | 业务操作编号，8–70 位字母、数字、下划线或连字符，由调用方生成。重试同一次操作时保持不变且正文完全一致，服务端回放原结果而不重复执行；它与请求头 Idempotency-Key 相互独立，两者都必须提供。 |
| revision | integer | 必填 | 工作台版本：先调用 desk.read，取返回的 state.revision。必须与服务端当前值完全相等，否则返回 409；工作台的每次写入都会使它递增。 |
| id | string | 必填 | 会话编号：取 desk.read 返回的 state.conversations[].id。 |
| version | integer | 必填 | 该会话的 version：取同一次 desk.read 返回的 state.conversations[].version。不是非负整数返回 400，与当前值不相等返回 409。 |

响应示例：
```json
{
  "state": {
    "revision": 13,
    "conversations": [
      {
        "id": "YOUR_CONVERSATION_ID",
        "version": 4,
        "lifecycle": "CLOSED",
        "handling": "HUMAN",
        "owner": "示例管理员",
        "ownerId": "YOUR_ACCOUNT_ID",
        "closedAt": "2026-11-16T02:30:00.000Z"
      }
    ]
  },
  "result": "会话已关闭",
  "executionReceipt": null
}
```

- 调用前先用 desk.read 读取最新 state，取 state.revision 和目标会话的 version；任一与服务端不符返回 409，须重新读取后改用新的 Idempotency-Key 提交（旧 Idempotency-Key 已绑定原正文，不能复用；requestId 可以沿用）。
- 状态前置：会话必须进行中（lifecycle 为 OPEN）、handling 为 HUMAN 且 ownerId 为调用账号；不满足时返回 403，已关闭的会话再次关闭同样返回 403。会话由 AI 接待或在排队时，先调用 desk.claim 接管，或改用 desk.endConversation。
- 与 desk.endConversation 的区别：两者都只把会话置为 CLOSED，都不处理工单。close 仅限调用账号本人人工接待中的会话，不需要 seq；endConversation 可结束任意进行中的会话，但必须提供 seq，并额外记录 terminatedAt。
- 原生消息渠道（机器人连接）的会话：渠道回复仍在发送或结果待核对、渠道绑定已变化、或该渠道当前仅可查看时返回 409。
- API Key 以创建该密钥的企业管理员账号身份执行，本契约中的“调用账号”均指该管理员账号。工作台以远程存储模式部署时，API Key 的工作台写操作一律返回 503。
- 结果未知时（超时或断连）先用 desk.read 核对目标状态。需要重发时保持原 requestId 和完全相同的正文（含原 revision、version）：服务端按 requestId 去重，已执行则回放原 result 而不重复执行，更换 Idempotency-Key 后也是如此。同一 requestId 搭配不同正文返回 409。
- 错误响应正文为 {"error":"原因说明"}。requestId 不符合格式、revision 不是非负整数返回 400；会话编号不存在返回 404。

### 工作台与工单 · 结束进行中的会话

`POST /v1/operations/desk.endConversation`

权限：service
费用：按业务权限与套餐执行。

```sh
# cURL 7.76+；请先在服务端设置环境变量。
: "${YUNFU_BASE_URL:?请设置服务端 HTTPS 地址}"
: "${YUNFU_API_KEY:?请设置已获授权的 API 密钥}"
: "${YUNFU_IDEMPOTENCY_KEY:?请设置本次写入的唯一编号，重试沿用原编号}"
curl --fail-with-body --show-error "$YUNFU_BASE_URL/v1/operations/desk.endConversation" \
  -H "Authorization: Bearer $YUNFU_API_KEY" \
  -H "Idempotency-Key: $YUNFU_IDEMPOTENCY_KEY" \
  -H 'Content-Type: application/json' \
  --data-binary '{
  "action": "endConversation",
  "requestId": "YOUR_STABLE_REQUEST_ID",
  "revision": 12,
  "id": "YOUR_CONVERSATION_ID",
  "version": 3,
  "seq": 6
}'
```

| 字段 | 类型 | 要求 | 说明 |
| --- | --- | --- | --- |
| requestId | string | 必填 | 业务操作编号，8–70 位字母、数字、下划线或连字符，由调用方生成。重试同一次操作时保持不变且正文完全一致，服务端回放原结果而不重复执行；它与请求头 Idempotency-Key 相互独立，两者都必须提供。 |
| revision | integer | 必填 | 工作台版本：先调用 desk.read，取返回的 state.revision。必须与服务端当前值完全相等，否则返回 409；工作台的每次写入都会使它递增。 |
| id | string | 必填 | 会话编号：取 desk.read 返回的 state.conversations[].id。 |
| version | integer | 必填 | 该会话的 version：取同一次 desk.read 返回的 state.conversations[].version。不是非负整数返回 400，与当前值不相等返回 409。 |
| seq | integer | 必填 | 该会话当前的消息总数：取同一次 desk.read 返回的目标会话 messages 数组长度（系统消息和内部备注也计入）。缺失或与服务端不一致返回 409，用于避免在出现新消息后误结束。 |

响应示例：
```json
{
  "state": {
    "revision": 13,
    "conversations": [
      {
        "id": "YOUR_CONVERSATION_ID",
        "version": 4,
        "lifecycle": "CLOSED",
        "handling": "AI",
        "owner": "AI 助手",
        "ownerId": "",
        "closedAt": "2026-11-16T02:30:00.000Z",
        "terminatedAt": "2026-11-16T02:30:00.000Z"
      }
    ]
  },
  "result": "会话已结束",
  "executionReceipt": null
}
```

- 调用前先用 desk.read 读取最新 state，取 state.revision 和目标会话的 version；任一与服务端不符返回 409，须重新读取后改用新的 Idempotency-Key 提交（旧 Idempotency-Key 已绑定原正文，不能复用；requestId 可以沿用）。
- 状态前置：会话必须进行中（lifecycle 为 OPEN），已结束的会话返回 409；seq 必须等于当前消息总数，否则返回 409，需重新读取后再确认结束。seq 不是非负整数返回 400。
- 与 desk.close 的区别：两者都只把会话置为 CLOSED，都不处理工单。close 仅限调用账号本人人工接待中的会话，不需要 seq；endConversation 可结束任意进行中的会话，但必须提供 seq，并额外记录 terminatedAt。
- 原生消息渠道（机器人连接）的会话：渠道回复仍在发送或结果待核对、渠道绑定已变化、或该渠道当前仅可查看时返回 409。
- API Key 以创建该密钥的企业管理员账号身份执行，本契约中的“调用账号”均指该管理员账号。工作台以远程存储模式部署时，API Key 的工作台写操作一律返回 503。
- 结果未知时（超时或断连）先用 desk.read 核对目标状态。需要重发时保持原 requestId 和完全相同的正文（含原 revision、version）：服务端按 requestId 去重，已执行则回放原 result 而不重复执行，更换 Idempotency-Key 后也是如此。同一 requestId 搭配不同正文返回 409。
- 错误响应正文为 {"error":"原因说明"}。requestId 不符合格式、revision 不是非负整数返回 400；会话编号不存在返回 404。

### 工作台与工单 · 重新打开会话

`POST /v1/operations/desk.reopen`

权限：service
费用：按业务权限与套餐执行。

```sh
# cURL 7.76+；请先在服务端设置环境变量。
: "${YUNFU_BASE_URL:?请设置服务端 HTTPS 地址}"
: "${YUNFU_API_KEY:?请设置已获授权的 API 密钥}"
: "${YUNFU_IDEMPOTENCY_KEY:?请设置本次写入的唯一编号，重试沿用原编号}"
curl --fail-with-body --show-error "$YUNFU_BASE_URL/v1/operations/desk.reopen" \
  -H "Authorization: Bearer $YUNFU_API_KEY" \
  -H "Idempotency-Key: $YUNFU_IDEMPOTENCY_KEY" \
  -H 'Content-Type: application/json' \
  --data-binary '{
  "action": "reopen",
  "requestId": "YOUR_STABLE_REQUEST_ID",
  "revision": 12,
  "id": "YOUR_CONVERSATION_ID",
  "version": 4
}'
```

| 字段 | 类型 | 要求 | 说明 |
| --- | --- | --- | --- |
| requestId | string | 必填 | 业务操作编号，8–70 位字母、数字、下划线或连字符，由调用方生成。重试同一次操作时保持不变且正文完全一致，服务端回放原结果而不重复执行；它与请求头 Idempotency-Key 相互独立，两者都必须提供。 |
| revision | integer | 必填 | 工作台版本：先调用 desk.read，取返回的 state.revision。必须与服务端当前值完全相等，否则返回 409；工作台的每次写入都会使它递增。 |
| id | string | 必填 | 会话编号：取 desk.read 返回的 state.conversations[].id。 |
| version | integer | 必填 | 该会话的 version：取同一次 desk.read 返回的 state.conversations[].version。不是非负整数返回 400，与当前值不相等返回 409。 |

响应示例：
```json
{
  "state": {
    "revision": 13,
    "conversations": [
      {
        "id": "YOUR_CONVERSATION_ID",
        "version": 5,
        "lifecycle": "OPEN",
        "handling": "HANDOFF",
        "owner": "售后客服组",
        "ownerId": ""
      }
    ]
  },
  "result": "已重开会话",
  "executionReceipt": null
}
```

- 调用前先用 desk.read 读取最新 state，取 state.revision 和目标会话的 version；任一与服务端不符返回 409，须重新读取后改用新的 Idempotency-Key 提交（旧 Idempotency-Key 已绑定原正文，不能复用；requestId 可以沿用）。
- 状态前置：会话必须已关闭（lifecycle 为 CLOSED）；仍在进行中返回 409。
- 409：原生消息渠道（机器人连接）的会话不能重开；会话原属客服组已停用或不存在。422：企业没有任何已启用的客服组。
- API Key 以创建该密钥的企业管理员账号身份执行，本契约中的“调用账号”均指该管理员账号。工作台以远程存储模式部署时，API Key 的工作台写操作一律返回 503。
- 结果未知时（超时或断连）先用 desk.read 核对目标状态。需要重发时保持原 requestId 和完全相同的正文（含原 revision、version）：服务端按 requestId 去重，已执行则回放原 result 而不重复执行，更换 Idempotency-Key 后也是如此。同一 requestId 搭配不同正文返回 409。
- 错误响应正文为 {"error":"原因说明"}。requestId 不符合格式、revision 不是非负整数返回 400；会话编号不存在返回 404。

### 工作台与工单 · 领取

`POST /v1/operations/desk.claim`

权限：service
费用：按业务权限与套餐执行。

```sh
# cURL 7.76+；请先在服务端设置环境变量。
: "${YUNFU_BASE_URL:?请设置服务端 HTTPS 地址}"
: "${YUNFU_API_KEY:?请设置已获授权的 API 密钥}"
: "${YUNFU_IDEMPOTENCY_KEY:?请设置本次写入的唯一编号，重试沿用原编号}"
curl --fail-with-body --show-error "$YUNFU_BASE_URL/v1/operations/desk.claim" \
  -H "Authorization: Bearer $YUNFU_API_KEY" \
  -H "Idempotency-Key: $YUNFU_IDEMPOTENCY_KEY" \
  -H 'Content-Type: application/json' \
  --data-binary '{
  "action": "claim",
  "requestId": "YOUR_STABLE_REQUEST_ID",
  "revision": 1,
  "id": "YOUR_CONVERSATION_ID",
  "version": 1,
  "data": {}
}'
```

| 字段 | 类型 | 要求 | 说明 |
| --- | --- | --- | --- |
| requestId | string | 必填 | 稳定业务操作编号，8–70 位字母、数字、下划线或连字符；重试保持不变，同时仍须 Idempotency-Key。 |
| revision | integer | 必填 | 先读取 desk.read 返回的 state.revision。 |
| id | string | 必填 | 已授权的会话编号。 |
| version | integer | 必填 | 该会话当前 version；变更后须重新读取。 |
| data | object | 必填 | 业务字段见请求示例；文本位于 data.text。 |

响应示例：
```json
{
  "state": {
    "revision": 2,
    "conversations": []
  },
  "result": "操作结果"
}
```

- 示例中的 revision、version 和资源编号必须替换为当前读取值；未收到最终回执时，先读取原业务结果。

### 工作台与工单 · 创建任务

`POST /v1/operations/desk.createTask`

权限：service
费用：按业务权限与套餐执行。

```sh
# cURL 7.76+；请先在服务端设置环境变量。
: "${YUNFU_BASE_URL:?请设置服务端 HTTPS 地址}"
: "${YUNFU_API_KEY:?请设置已获授权的 API 密钥}"
: "${YUNFU_IDEMPOTENCY_KEY:?请设置本次写入的唯一编号，重试沿用原编号}"
curl --fail-with-body --show-error "$YUNFU_BASE_URL/v1/operations/desk.createTask" \
  -H "Authorization: Bearer $YUNFU_API_KEY" \
  -H "Idempotency-Key: $YUNFU_IDEMPOTENCY_KEY" \
  -H 'Content-Type: application/json' \
  --data-binary '{
  "action": "createTask",
  "requestId": "desk_example_1",
  "revision": 1,
  "data": {
    "title": "退款回查",
    "content": "核对退款回执后于下午联系客户",
    "owner": "嘉宁",
    "ownerId": "owner-a",
    "due": "2026-10-13T09:00:00+08:00",
    "kind": "回访"
  }
}'
```

| 字段 | 类型 | 要求 | 说明 |
| --- | --- | --- | --- |
| requestId | string | 可选 | 业务请求编号；它与网关 Idempotency-Key 均需保持稳定。 |
| revision | integer | 可选 | 先读取当前资源修订号；共享配置与单资源修订号不可混用。 |
| id | string | 可选 | 操作目标的真实资源 ID；不能使用其他企业 ID。 |
| version | integer | 可选 | 目标会话版本（适用时），与工作台 revision 不同。 |
| seq | integer | 可选 | send 所依赖的消息数量，保护并发回复。 |
| data.text | string | 可选 | send/note 的正文，最多 4000 字。 |
| data.content | string | 见说明 | createTask/createTicket 必填的独立待办/工单内容，不能为空，最多 3000 个 UTF-16 单位；与标题分开保存。 |
| data.ticketId | string | 可选 | 仅 createTask 可选：关联当前可见的未完成工单，并自动继承其 conversationId；同时提交的 conversationId 必须一致。待办和工单状态独立，createTicket 不接受此字段。 |
| data.offerId | string | 见说明 | cancelHandoff 必填，当前会话有效待接收邀请的 ID；撤回同一归属版本的全部待接收邀请。 |
| data | object | 可选 | 操作数据：createTask/createTicket 的标题/内容/类型/负责人/截止时间，transferTicket 的目标，workStatus 的集合与状态等，以当前工作台协议为准。 |

响应示例：
```json
{
  "state": {
    "conversations": []
  }
}
```

- 响应示例仅展示其中一个分支的部分字段；其他字段依查询与 action 返回，不能据此生成严格 DTO。
- GET 返回按角色和成员范围投影的 state；summary=1 返回接待摘要。send/note 发送消息或备注，claim 接管，close/endConversation 结束，reopen 重新接待，handoff/acceptHandoff/cancelHandoff 邀请、接收或撤回转接，createTask 创建待办，createTicket/transferTicket/workStatus 管理工单。API Key 写入仅在本地工作台存储模式支持；Go 远程模式尚未接入提交时撤权校验，拒绝网关写入。
- createTask 可使用已授权的 desk.createTask 公开操作。先读取最新 revision 与本企业已启用成员，填写 data.title/content/owner/ownerId/due/kind；content 必填，最多 3000 个 UTF-16 单位，创建时保存 createdAt/updatedAt。企业管理员有 service 权限时读取本企业全部待办；客服仍按本人、主管组与有效转接授权范围读取。
- createTicket 使用相同的创建示例字段并将 action 改为 createTicket，kind 必须为有效工单模板；data.content 必填，最多 3000 个 UTF-16 单位，独立保存并记录 createdAt/updatedAt。工单状态流转和重开保留正文；旧记录和系统生成工单可缺少正文。
- cancelHandoff 仅当前负责人或正常企业管理员有 service 权限时可用，支持访问不可用；需最新 revision/version 及 data.offerId。有效邀请存在时不能重复 handoff；已接收或失效邀请不能撤回。撤回保留原负责人，不发送客户消息。
- releaseToAI 仅当前接待负责人可调用，使用最新 revision/version，可带不超过 1000 字的 data.handoffSummary。会话有未知结果、待审批动作，或接待组为影子/建议模式时拒绝交回；成功后由 AI 接待下一条访客消息，不等于已对客户发送回复。
- 应用接口沿用原业务去重规则；Bearer 网关增加操作级幂等，不取代 revision 校验。

### 工作台与工单 · 创建工单

`POST /v1/operations/desk.createTicket`

权限：service
费用：按业务权限与套餐执行。

```sh
# cURL 7.76+；请先在服务端设置环境变量。
: "${YUNFU_BASE_URL:?请设置服务端 HTTPS 地址}"
: "${YUNFU_API_KEY:?请设置已获授权的 API 密钥}"
: "${YUNFU_IDEMPOTENCY_KEY:?请设置本次写入的唯一编号，重试沿用原编号}"
curl --fail-with-body --show-error "$YUNFU_BASE_URL/v1/operations/desk.createTicket" \
  -H "Authorization: Bearer $YUNFU_API_KEY" \
  -H "Idempotency-Key: $YUNFU_IDEMPOTENCY_KEY" \
  -H 'Content-Type: application/json' \
  --data-binary '{
  "action": "createTicket",
  "requestId": "YOUR_STABLE_REQUEST_ID",
  "revision": 1,
  "id": "YOUR_CONVERSATION_ID",
  "version": 1,
  "data": {
    "title": "订单售后",
    "owner": "接待客服",
    "ownerId": "YOUR_MEMBER_ID",
    "due": "2026-12-01T09:00:00+08:00",
    "kind": "退款",
    "content": "请核对订单并联系客户",
    "conversationId": "YOUR_CONVERSATION_ID"
  }
}'
```

| 字段 | 类型 | 要求 | 说明 |
| --- | --- | --- | --- |
| requestId | string | 必填 | 稳定业务操作编号，8–70 位字母、数字、下划线或连字符；重试保持不变，同时仍须 Idempotency-Key。 |
| revision | integer | 必填 | 先读取 desk.read 返回的 state.revision。 |
| id | string | 必填 | 已授权的会话编号。 |
| version | integer | 必填 | 该会话当前 version；变更后须重新读取。 |
| data | object | 必填 | 业务字段见请求示例；文本位于 data.text。 |

响应示例：
```json
{
  "state": {
    "revision": 2,
    "conversations": []
  },
  "result": "操作结果"
}
```

- 示例中的 revision、version 和资源编号必须替换为当前读取值；未收到最终回执时，先读取原业务结果。
- kind 使用当前工单模板；due 为有效截止时间；data.conversationId 与顶层 id 一致。管理员须先开启自动创建工单。

### 工作台与工单 · 转派工单

`POST /v1/operations/desk.transferTicket`

权限：service
费用：按业务权限与套餐执行。

```sh
# cURL 7.76+；请先在服务端设置环境变量。
: "${YUNFU_BASE_URL:?请设置服务端 HTTPS 地址}"
: "${YUNFU_API_KEY:?请设置已获授权的 API 密钥}"
: "${YUNFU_IDEMPOTENCY_KEY:?请设置本次写入的唯一编号，重试沿用原编号}"
curl --fail-with-body --show-error "$YUNFU_BASE_URL/v1/operations/desk.transferTicket" \
  -H "Authorization: Bearer $YUNFU_API_KEY" \
  -H "Idempotency-Key: $YUNFU_IDEMPOTENCY_KEY" \
  -H 'Content-Type: application/json' \
  --data-binary '{
  "action": "transferTicket",
  "requestId": "YOUR_STABLE_REQUEST_ID",
  "revision": 12,
  "id": "YOUR_TICKET_ID",
  "version": 3,
  "data": {
    "fromOwnerId": "YOUR_CURRENT_OWNER_ID",
    "ownerId": "YOUR_MEMBER_ID",
    "reason": "需要售后专员跟进退款"
  }
}'
```

| 字段 | 类型 | 要求 | 说明 |
| --- | --- | --- | --- |
| requestId | string | 必填 | 业务操作编号，8–70 位字母、数字、下划线或连字符，由调用方生成。重试同一次操作时保持不变且正文完全一致，服务端回放原结果而不重复执行；它与请求头 Idempotency-Key 相互独立，两者都必须提供。 |
| revision | integer | 必填 | 工作台版本：先调用 desk.read，取返回的 state.revision。必须与服务端当前值完全相等，否则返回 409；工作台的每次写入都会使它递增。 |
| id | string | 必填 | 工单编号：取 desk.read 返回的 state.tickets[].id（不是会话编号）。 |
| version | integer | 条件必填：工单关联了会话（state.tickets[].conversationId 非空） | 关联会话的 version：在 state.conversations[] 中找到 id 等于该工单 conversationId 的会话，取其 version；缺失或与当前值不相等返回 409。工单未关联会话时不使用此字段。 |
| data | object | 必填 | 转派参数。 |
| data.fromOwnerId | string | 必填 | 工单当前负责人的账号编号：取 state.tickets[].ownerId；工单尚未分配负责人时传空字符串。与服务端当前值不一致返回 409。 |
| data.ownerId | string | 必填 | 接收人的账号编号：取 desk.read 返回的 state.members[].id。接收人须状态为“已启用”，角色为人工客服、客服主管或企业管理员，且不能是当前负责人。 |
| data.reason | string | 必填 | 转派原因，去除首尾空白后不能为空，最多 500 个字符；写入工单历史和关联会话的转派备注。 |
| data.ticketVersion | integer | 可选 | 工单自身的 version：取 state.tickets[].version，工单没有该字段时传 0。提供时与当前值不一致返回 409；省略则不做此项校验。 |
| data.departmentId | string | 可选 | 接收人所属部门编号：取 state.members[].departmentId，无部门时为空字符串。提供时与接收人当前部门不一致返回 409；省略则不做此项校验。 |

响应示例：
```json
{
  "state": {
    "revision": 13,
    "tickets": [
      {
        "id": "YOUR_TICKET_ID",
        "version": 2,
        "status": "处理中",
        "owner": "售后专员",
        "ownerId": "YOUR_MEMBER_ID",
        "conversationId": "YOUR_CONVERSATION_ID"
      }
    ],
    "conversations": [
      {
        "id": "YOUR_CONVERSATION_ID",
        "version": 4,
        "lifecycle": "OPEN",
        "handling": "HUMAN",
        "owner": "售后专员",
        "ownerId": "YOUR_MEMBER_ID"
      }
    ]
  },
  "result": "工单与关联会话已同步转派，聊天记录完整保留",
  "executionReceipt": null
}
```

- 调用前先用 desk.read 读取最新 state：取 state.revision；在 state.tickets 中取目标工单的 id、ownerId、version 和 conversationId；在 state.members 中选定接收人；工单关联了会话时再取该会话的 version。任一版本不符返回 409，须重新读取后改用新的 Idempotency-Key 提交（旧 Idempotency-Key 已绑定原正文，不能复用；requestId 可以沿用）。
- 状态前置：已完成的工单不能转派（409），需先用 desk.workStatus 改回“待处理”。
- 409：data.fromOwnerId 与工单当前负责人不一致；关联会话的 version 已变化或关联会话不可用；关联会话进行中且接收人已达同时接待上限；关联会话进行中、接收人不是会话现负责人且当前不在坐席排班时间内。400：接收人不存在、未启用或角色不符；接收人就是当前负责人；data.reason 为空或超过 500 个字符。404：工单不存在。
- 注意副作用：关联会话无论原先由 AI 接待、在排队还是已关闭，转派后 handling 都会变为 HUMAN 并归接收人负责。
- API Key 以创建该密钥的企业管理员账号身份执行，本契约中的“调用账号”均指该管理员账号。工作台以远程存储模式部署时，API Key 的工作台写操作一律返回 503。
- 以 API Key 调用时可转派本企业任意工单，不受“只能流转本人负责的工单”限制。
- 结果未知时（超时或断连）先用 desk.read 核对目标状态。需要重发时保持原 requestId 和完全相同的正文（含原 revision、version）：服务端按 requestId 去重，已执行则回放原 result 而不重复执行，更换 Idempotency-Key 后也是如此。同一 requestId 搭配不同正文返回 409。
- 错误响应正文为 {"error":"原因说明"}。requestId 不符合格式、revision 不是非负整数返回 400。

### 工作台与工单 · 更新工单或待办状态

`POST /v1/operations/desk.workStatus`

权限：service
费用：按业务权限与套餐执行。

```sh
# cURL 7.76+；请先在服务端设置环境变量。
: "${YUNFU_BASE_URL:?请设置服务端 HTTPS 地址}"
: "${YUNFU_API_KEY:?请设置已获授权的 API 密钥}"
: "${YUNFU_IDEMPOTENCY_KEY:?请设置本次写入的唯一编号，重试沿用原编号}"
curl --fail-with-body --show-error "$YUNFU_BASE_URL/v1/operations/desk.workStatus" \
  -H "Authorization: Bearer $YUNFU_API_KEY" \
  -H "Idempotency-Key: $YUNFU_IDEMPOTENCY_KEY" \
  -H 'Content-Type: application/json' \
  --data-binary '{
  "action": "workStatus",
  "requestId": "YOUR_STABLE_REQUEST_ID",
  "revision": 12,
  "id": "YOUR_TICKET_ID",
  "data": {
    "collection": "tickets",
    "status": "处理中"
  }
}'
```

| 字段 | 类型 | 要求 | 说明 |
| --- | --- | --- | --- |
| requestId | string | 必填 | 业务操作编号，8–70 位字母、数字、下划线或连字符，由调用方生成。重试同一次操作时保持不变且正文完全一致，服务端回放原结果而不重复执行；它与请求头 Idempotency-Key 相互独立，两者都必须提供。 |
| revision | integer | 必填 | 工作台版本：先调用 desk.read，取返回的 state.revision。必须与服务端当前值完全相等，否则返回 409；工作台的每次写入都会使它递增。 |
| id | string | 必填 | 工单或待办的编号：工单取 desk.read 返回的 state.tickets[].id，待办取 state.tasks[].id（不是会话编号）。 |
| data | object | 必填 | 状态参数。 |
| data.collection | string | 可选 | 传 "tickets" 表示更新工单；省略或传其他任何值都按待办（state.tasks）处理。 |
| data.status | string | 必填 | 目标状态。工单允许的流转：待处理→处理中或已完成；处理中→待客户反馈或已完成；待客户反馈→处理中或已完成；已完成→待处理（重开）。待办只接受“处理中”（当前须为待处理）或“已完成”。 |
| data.evidence | string | 条件必填：data.status 为“已完成” | 完成证据，去除首尾空白后不能为空，最多 2000 个字符。 |
| data.reason | string | 条件必填：把已完成的工单改回“待处理”（重开） | 重开原因，去除首尾空白后不能为空，最多 500 个字符。工单的其他状态流转可选填，只保留前 500 个字符；待办不使用此字段。 |
| data.ticketVersion | integer | 可选 | 仅用于工单：取 state.tickets[].version，工单没有该字段时传 0。提供时与当前值不一致返回 409；省略则不做此项校验。 |

响应示例：
```json
{
  "state": {
    "revision": 13,
    "tickets": [
      {
        "id": "YOUR_TICKET_ID",
        "version": 2,
        "status": "处理中",
        "owner": "示例管理员",
        "ownerId": "YOUR_ACCOUNT_ID",
        "conversationId": "YOUR_CONVERSATION_ID"
      }
    ],
    "tasks": []
  },
  "result": "工单状态已更新",
  "executionReceipt": null
}
```

- 调用前先用 desk.read 读取最新 state：取 state.revision，并在 state.tickets 或 state.tasks 中取目标记录的 id 和当前 status。revision 不符返回 409，须重新读取后改用新的 Idempotency-Key 提交（旧 Idempotency-Key 已绑定原正文，不能复用；requestId 可以沿用）。本操作不使用顶层 version。
- 工单（data.collection 为 "tickets"）：404 工单不存在；409 目标状态不在允许的流转内（包括传入未知状态值），或 data.ticketVersion 已变化；400 data.status 不是 1–30 个字符的非空字符串，或缺少必填的 data.evidence / data.reason。
- 待办（省略 data.collection）：404 记录不存在；400 该待办是转接邀请（应改用 desk.acceptHandoff），或 data.status 不是“处理中”“已完成”；409 待办已完成或已取消，或要求改为“处理中”时当前状态不是“待处理”；400 完成时缺少 data.evidence。
- data.collection 拼写错误不会报参数错误，而是按待办查找，通常表现为 404 记录不存在。
- API Key 以创建该密钥的企业管理员账号身份执行，本契约中的“调用账号”均指该管理员账号。工作台以远程存储模式部署时，API Key 的工作台写操作一律返回 503。
- 以 API Key 调用时可更新本企业任意工单与待办；唯一例外是私域“交接”类待办，只有接收人本人可处理，否则返回 403。
- 结果未知时（超时或断连）先用 desk.read 核对目标状态。需要重发时保持原 requestId 和完全相同的正文（含原 revision、version）：服务端按 requestId 去重，已执行则回放原 result 而不重复执行，更换 Idempotency-Key 后也是如此。同一 requestId 搭配不同正文返回 409。
- 错误响应正文为 {"error":"原因说明"}。requestId 不符合格式、revision 不是非负整数返回 400。

### 工作台与工单 · 发起转接邀请

`POST /v1/operations/desk.handoff`

权限：service
费用：按业务权限与套餐执行。

```sh
# cURL 7.76+；请先在服务端设置环境变量。
: "${YUNFU_BASE_URL:?请设置服务端 HTTPS 地址}"
: "${YUNFU_API_KEY:?请设置已获授权的 API 密钥}"
: "${YUNFU_IDEMPOTENCY_KEY:?请设置本次写入的唯一编号，重试沿用原编号}"
curl --fail-with-body --show-error "$YUNFU_BASE_URL/v1/operations/desk.handoff" \
  -H "Authorization: Bearer $YUNFU_API_KEY" \
  -H "Idempotency-Key: $YUNFU_IDEMPOTENCY_KEY" \
  -H 'Content-Type: application/json' \
  --data-binary '{
  "action": "handoff",
  "requestId": "YOUR_STABLE_REQUEST_ID",
  "revision": 1,
  "id": "YOUR_CONVERSATION_ID",
  "version": 1,
  "data": {
    "owner": "接待客服",
    "ownerId": "YOUR_MEMBER_ID",
    "reason": "需要售后处理"
  }
}'
```

| 字段 | 类型 | 要求 | 说明 |
| --- | --- | --- | --- |
| requestId | string | 必填 | 稳定业务操作编号，8–70 位字母、数字、下划线或连字符；重试保持不变，同时仍须 Idempotency-Key。 |
| revision | integer | 必填 | 先读取 desk.read 返回的 state.revision。 |
| id | string | 必填 | 已授权的会话编号。 |
| version | integer | 必填 | 该会话当前 version；变更后须重新读取。 |
| data | object | 必填 | 业务字段见请求示例；文本位于 data.text。 |

响应示例：
```json
{
  "state": {
    "revision": 2,
    "conversations": []
  },
  "result": "操作结果"
}
```

- 示例中的 revision、version 和资源编号必须替换为当前读取值；未收到最终回执时，先读取原业务结果。
- owner 与 reason 必填；同名成员须使用 ownerId。此操作只创建邀请，对方接受前由原客服继续接待。

### 工作台与工单 · 接受转接邀请

`POST /v1/operations/desk.acceptHandoff`

权限：service
费用：按业务权限与套餐执行。

```sh
# cURL 7.76+；请先在服务端设置环境变量。
: "${YUNFU_BASE_URL:?请设置服务端 HTTPS 地址}"
: "${YUNFU_API_KEY:?请设置已获授权的 API 密钥}"
: "${YUNFU_IDEMPOTENCY_KEY:?请设置本次写入的唯一编号，重试沿用原编号}"
curl --fail-with-body --show-error "$YUNFU_BASE_URL/v1/operations/desk.acceptHandoff" \
  -H "Authorization: Bearer $YUNFU_API_KEY" \
  -H "Idempotency-Key: $YUNFU_IDEMPOTENCY_KEY" \
  -H 'Content-Type: application/json' \
  --data-binary '{
  "action": "acceptHandoff",
  "requestId": "YOUR_STABLE_REQUEST_ID",
  "revision": 12,
  "id": "YOUR_CONVERSATION_ID",
  "version": 3
}'
```

| 字段 | 类型 | 要求 | 说明 |
| --- | --- | --- | --- |
| requestId | string | 必填 | 业务操作编号，8–70 位字母、数字、下划线或连字符，由调用方生成。重试同一次操作时保持不变且正文完全一致，服务端回放原结果而不重复执行；它与请求头 Idempotency-Key 相互独立，两者都必须提供。 |
| revision | integer | 必填 | 工作台版本：先调用 desk.read，取返回的 state.revision。必须与服务端当前值完全相等，否则返回 409；工作台的每次写入都会使它递增。 |
| id | string | 必填 | 会话编号：取 desk.read 返回的 state.conversations[].id。 |
| version | integer | 必填 | 该会话的 version：取同一次 desk.read 返回的 state.conversations[].version。不是非负整数返回 400，与当前值不相等返回 409。 |

响应示例：
```json
{
  "state": {
    "revision": 13,
    "conversations": [
      {
        "id": "YOUR_CONVERSATION_ID",
        "version": 4,
        "lifecycle": "OPEN",
        "handling": "HUMAN",
        "owner": "示例管理员",
        "ownerId": "YOUR_ACCOUNT_ID"
      }
    ],
    "tasks": [
      {
        "id": "TD-1a2b3c4d",
        "kind": "转接邀请",
        "status": "已完成",
        "conversationId": "YOUR_CONVERSATION_ID",
        "owner": "示例管理员",
        "ownerId": "YOUR_ACCOUNT_ID",
        "handoffVersion": 3
      }
    ]
  },
  "result": "已确认接收转接",
  "executionReceipt": null
}
```

- 调用前先用 desk.read 读取最新 state，取 state.revision 和目标会话的 version；任一与服务端不符返回 409，须重新读取后改用新的 Idempotency-Key 提交（旧 Idempotency-Key 已绑定原正文，不能复用；requestId 可以沿用）。
- 状态前置：desk.read 的 state.tasks 中必须有一条 kind 为“转接邀请”、conversationId 为该会话、ownerId 为调用账号、status 为“待处理”的待办，且未过期（邀请发出后 15 分钟内有效）、其 handoffVersion 等于会话当前 version；否则返回 409。
- 409：没有有效的转接邀请；会话已不是进行中的人工接待；当前不在坐席排班时间内；调用账号已达同时接待上限。
- 原生消息渠道（机器人连接）的会话：渠道回复仍在发送或结果待核对、渠道绑定已变化、或该渠道当前仅可查看时返回 409。
- API Key 以创建该密钥的企业管理员账号身份执行，本契约中的“调用账号”均指该管理员账号。工作台以远程存储模式部署时，API Key 的工作台写操作一律返回 503。
- 以 API Key 调用时只能接受发给该管理员账号的邀请。接受成功还会把该账号的坐席状态置为在线（约 120 秒内有效），其间系统可能向它分配新的会话。
- 结果未知时（超时或断连）先用 desk.read 核对目标状态。需要重发时保持原 requestId 和完全相同的正文（含原 revision、version）：服务端按 requestId 去重，已执行则回放原 result 而不重复执行，更换 Idempotency-Key 后也是如此。同一 requestId 搭配不同正文返回 409。
- 错误响应正文为 {"error":"原因说明"}。requestId 不符合格式、revision 不是非负整数返回 400；会话编号不存在返回 404。

### 工作台与工单 · 撤回转接邀请

`POST /v1/operations/desk.cancelHandoff`

权限：service
费用：按业务权限与套餐执行。

```sh
# cURL 7.76+；请先在服务端设置环境变量。
: "${YUNFU_BASE_URL:?请设置服务端 HTTPS 地址}"
: "${YUNFU_API_KEY:?请设置已获授权的 API 密钥}"
: "${YUNFU_IDEMPOTENCY_KEY:?请设置本次写入的唯一编号，重试沿用原编号}"
curl --fail-with-body --show-error "$YUNFU_BASE_URL/v1/operations/desk.cancelHandoff" \
  -H "Authorization: Bearer $YUNFU_API_KEY" \
  -H "Idempotency-Key: $YUNFU_IDEMPOTENCY_KEY" \
  -H 'Content-Type: application/json' \
  --data-binary '{
  "action": "cancelHandoff",
  "requestId": "YOUR_STABLE_REQUEST_ID",
  "revision": 12,
  "id": "YOUR_CONVERSATION_ID",
  "version": 3,
  "data": {
    "offerId": "YOUR_HANDOFF_OFFER_ID"
  }
}'
```

| 字段 | 类型 | 要求 | 说明 |
| --- | --- | --- | --- |
| requestId | string | 必填 | 业务操作编号，8–70 位字母、数字、下划线或连字符，由调用方生成。重试同一次操作时保持不变且正文完全一致，服务端回放原结果而不重复执行；它与请求头 Idempotency-Key 相互独立，两者都必须提供。 |
| revision | integer | 必填 | 工作台版本：先调用 desk.read，取返回的 state.revision。必须与服务端当前值完全相等，否则返回 409；工作台的每次写入都会使它递增。 |
| id | string | 必填 | 会话编号：取 desk.read 返回的 state.conversations[].id。 |
| version | integer | 必填 | 该会话的 version：取同一次 desk.read 返回的 state.conversations[].version。不是非负整数返回 400，与当前值不相等返回 409。 |
| data | object | 必填 | 撤回参数。 |
| data.offerId | string | 必填 | 要撤回的转接邀请编号，最多 100 个字符：取 desk.read 返回的 state.tasks[] 中 kind 为“转接邀请”、conversationId 等于该会话、status 为“待处理”的待办的 id。 |

响应示例：
```json
{
  "state": {
    "revision": 13,
    "conversations": [
      {
        "id": "YOUR_CONVERSATION_ID",
        "version": 3,
        "lifecycle": "OPEN",
        "handling": "HUMAN",
        "owner": "原接待客服",
        "ownerId": "YOUR_CURRENT_OWNER_ID"
      }
    ],
    "tasks": [
      {
        "id": "YOUR_HANDOFF_OFFER_ID",
        "kind": "转接邀请",
        "status": "已取消",
        "conversationId": "YOUR_CONVERSATION_ID",
        "owner": "受邀客服",
        "ownerId": "YOUR_MEMBER_ID",
        "handoffVersion": 3
      }
    ]
  },
  "result": "转接邀请已撤回，原负责人继续接待",
  "executionReceipt": null
}
```

- 调用前先用 desk.read 读取最新 state，取 state.revision 和目标会话的 version；任一与服务端不符返回 409，须重新读取后改用新的 Idempotency-Key 提交（旧 Idempotency-Key 已绑定原正文，不能复用；requestId 可以沿用）。
- 状态前置：邀请必须仍然有效——status 为“待处理”、未过期（发出后 15 分钟内）、会话仍是进行中的人工接待、邀请的 handoffVersion 等于会话当前 version；否则返回 409（邀请已被接受、已过期或已失效）。
- 400：data.offerId 缺失、为空或超过 100 个字符。desk.handoff 的响应不单独返回邀请编号，需在其返回的 state.tasks 或之后的 desk.read 中查找。
- API Key 以创建该密钥的企业管理员账号身份执行，本契约中的“调用账号”均指该管理员账号。工作台以远程存储模式部署时，API Key 的工作台写操作一律返回 503。
- 以 API Key 调用时可撤回本企业任意会话的有效邀请，不要求调用账号是该会话负责人。
- 结果未知时（超时或断连）先用 desk.read 核对目标状态。需要重发时保持原 requestId 和完全相同的正文（含原 revision、version）：服务端按 requestId 去重，已执行则回放原 result 而不重复执行，更换 Idempotency-Key 后也是如此。同一 requestId 搭配不同正文返回 409。
- 错误响应正文为 {"error":"原因说明"}。requestId 不符合格式、revision 不是非负整数返回 400；会话编号不存在返回 404。

### 工作台与工单 · 交回 AI 接待

`POST /v1/operations/desk.releaseToAI`

权限：service
费用：按业务权限与套餐执行。

```sh
# cURL 7.76+；请先在服务端设置环境变量。
: "${YUNFU_BASE_URL:?请设置服务端 HTTPS 地址}"
: "${YUNFU_API_KEY:?请设置已获授权的 API 密钥}"
: "${YUNFU_IDEMPOTENCY_KEY:?请设置本次写入的唯一编号，重试沿用原编号}"
curl --fail-with-body --show-error "$YUNFU_BASE_URL/v1/operations/desk.releaseToAI" \
  -H "Authorization: Bearer $YUNFU_API_KEY" \
  -H "Idempotency-Key: $YUNFU_IDEMPOTENCY_KEY" \
  -H 'Content-Type: application/json' \
  --data-binary '{
  "action": "releaseToAI",
  "requestId": "YOUR_STABLE_REQUEST_ID",
  "revision": 12,
  "id": "YOUR_CONVERSATION_ID",
  "version": 3,
  "data": {
    "handoffSummary": "已核实订单信息，客户等待物流更新。"
  }
}'
```

| 字段 | 类型 | 要求 | 说明 |
| --- | --- | --- | --- |
| requestId | string | 必填 | 业务操作编号，8–70 位字母、数字、下划线或连字符，由调用方生成。重试同一次操作时保持不变且正文完全一致，服务端回放原结果而不重复执行；它与请求头 Idempotency-Key 相互独立，两者都必须提供。 |
| revision | integer | 必填 | 工作台版本：先调用 desk.read，取返回的 state.revision。必须与服务端当前值完全相等，否则返回 409；工作台的每次写入都会使它递增。 |
| id | string | 必填 | 会话编号：取 desk.read 返回的 state.conversations[].id。 |
| version | integer | 必填 | 该会话的 version：取同一次 desk.read 返回的 state.conversations[].version；缺失或与当前值不相等都返回 409。 |
| data | object | 可选 | 可选参数；不留交接备注时可省略。 |
| data.handoffSummary | string | 可选 | 交接备注，最多 1000 个字符；去除首尾空白后非空时，作为一条内部备注写入会话。省略或只有空白则不写备注。 |

响应示例：
```json
{
  "state": {
    "revision": 13,
    "conversations": [
      {
        "id": "YOUR_CONVERSATION_ID",
        "version": 4,
        "lifecycle": "OPEN",
        "handling": "AI",
        "owner": "AI 助手",
        "ownerId": ""
      }
    ]
  },
  "result": "已交由 AI 继续接待",
  "executionReceipt": null
}
```

- 调用前先用 desk.read 读取最新 state，取 state.revision 和目标会话的 version；任一与服务端不符返回 409，须重新读取后改用新的 Idempotency-Key 提交（旧 Idempotency-Key 已绑定原正文，不能复用；requestId 可以沿用）。
- 状态前置：会话必须进行中（lifecycle 为 OPEN，已关闭返回 409）、handling 为 HUMAN 且 ownerId 为调用账号，否则返回 403；调用账号需先通过 desk.claim 或 desk.acceptHandoff 成为负责人。
- 409：会话的 unknown 为 true，或该会话存在未完成的“审批”“未知结果”类待办；会话所属客服组为影子运行或仅建议模式。400：data.handoffSummary 不是字符串或超过 1000 个字符；桌面连接器渠道的会话不支持交回 AI。
- 原生消息渠道（机器人连接）的会话：渠道回复仍在发送或结果待核对、渠道绑定已变化、或该渠道当前仅可查看时返回 409。
- API Key 以创建该密钥的企业管理员账号身份执行，本契约中的“调用账号”均指该管理员账号。工作台以远程存储模式部署时，API Key 的工作台写操作一律返回 503。
- 结果未知时（超时或断连）先用 desk.read 核对目标状态。需要重发时保持原 requestId 和完全相同的正文（含原 revision、version）：服务端按 requestId 去重，已执行则回放原 result 而不重复执行，更换 Idempotency-Key 后也是如此。同一 requestId 搭配不同正文返回 409。
- 错误响应正文为 {"error":"原因说明"}。requestId 不符合格式、revision 不是非负整数返回 400；会话编号不存在返回 404。

### 读取知识库

`GET /v1/operations/knowledge.read`

权限：knowledge
费用：按业务权限与套餐执行。

```sh
# cURL 7.76+；请先在服务端设置环境变量。
: "${YUNFU_BASE_URL:?请设置服务端 HTTPS 地址}"
: "${YUNFU_API_KEY:?请设置已获授权的 API 密钥}"
curl --fail-with-body --show-error "$YUNFU_BASE_URL/v1/operations/knowledge.read" \
  -H "Authorization: Bearer $YUNFU_API_KEY"
```

| 字段 | 类型 | 要求 | 说明 |
| --- | --- | --- | --- |
| agentId (query) | string | 可选 | 智能体配置类接口通过查询参数指定；默认 default。 |
| query | string | 可选 | retrieve 的检索问题，最多 2000 字。 |

响应示例：
```json
{
  "documents": []
}
```

- 响应示例仅展示其中一个分支的部分字段；其他字段依查询与 action 返回，不能据此生成严格 DTO。
- GET 不传 id 列出文档；传 id 返回文档和切片。save 保存草稿，preview 仅切片，index 真实调用向量模型，retrieve 按智能体知识配置检索，publish 只发布已完成且匹配当前配置的索引，unpublish/delete 受版本与引用约束。
- 应用接口沿用原业务去重规则；Bearer 网关增加操作级幂等，不取代 revision 校验。

### 知识库 · 保存

`POST /v1/operations/knowledge.save`

权限：knowledge
费用：按业务权限与套餐执行。

```sh
# cURL 7.76+；请先在服务端设置环境变量。
: "${YUNFU_BASE_URL:?请设置服务端 HTTPS 地址}"
: "${YUNFU_API_KEY:?请设置已获授权的 API 密钥}"
: "${YUNFU_IDEMPOTENCY_KEY:?请设置本次写入的唯一编号，重试沿用原编号}"
curl --fail-with-body --show-error "$YUNFU_BASE_URL/v1/operations/knowledge.save" \
  -H "Authorization: Bearer $YUNFU_API_KEY" \
  -H "Idempotency-Key: $YUNFU_IDEMPOTENCY_KEY" \
  -H 'Content-Type: application/json' \
  --data-binary '{
  "action": "save",
  "title": "退款说明",
  "content": "退款申请需提供订单号。",
  "chunkSize": 600,
  "overlap": 80
}'
```

| 字段 | 类型 | 要求 | 说明 |
| --- | --- | --- | --- |
| title | string | 必填 | 文档名称，最多 150 字。 |
| content | string | 必填 | 已获授权的知识正文。 |
| chunkSize | integer | 必填 | 分段长度，200–2000。 |
| overlap | integer | 必填 | 重叠字符，0–500 且小于 chunkSize / 2。 |
| id | string | 条件必填：更新已有文档 | 更新现有文档时使用其编号。 |
| revision | integer | 条件必填：更新已有文档 | 更新现有文档时使用当前版本。 |

响应示例：
```json
{
  "ok": true,
  "chunks": 1
}
```

- 先读取文档或智能体的当前版本，不照抄示例中的版本号。
- 保存只返回 ok 与 chunks；新文档编号请从知识目录读取，不能从该响应推断。

### 知识库 · 预览

`POST /v1/operations/knowledge.preview`

权限：knowledge
费用：按业务权限与套餐执行。

```sh
# cURL 7.76+；请先在服务端设置环境变量。
: "${YUNFU_BASE_URL:?请设置服务端 HTTPS 地址}"
: "${YUNFU_API_KEY:?请设置已获授权的 API 密钥}"
: "${YUNFU_IDEMPOTENCY_KEY:?请设置本次写入的唯一编号，重试沿用原编号}"
curl --fail-with-body --show-error "$YUNFU_BASE_URL/v1/operations/knowledge.preview" \
  -H "Authorization: Bearer $YUNFU_API_KEY" \
  -H "Idempotency-Key: $YUNFU_IDEMPOTENCY_KEY" \
  -H 'Content-Type: application/json' \
  --data-binary '{
  "action": "preview",
  "content": "待检索的客服知识正文",
  "chunkSize": 500,
  "overlap": 50
}'
```

| 字段 | 类型 | 要求 | 说明 |
| --- | --- | --- | --- |
| id | string | 可选 | 操作目标的真实资源 ID；不能使用其他企业 ID。 |
| revision | integer | 可选 | 先读取当前资源修订号；共享配置与单资源修订号不可混用。 |
| agentId (query) | string | 可选 | 智能体配置类接口通过查询参数指定；默认 default。 |
| title | string | 可选 | save 文档标题，最多 150 字。 |
| content | string | 可选 | save/preview 正文，最多 50000 字。 |
| chunkSize | integer | 可选 | 切片长度 200–2000。 |
| overlap | integer | 可选 | 重叠 0–500 且小于切片长度一半。 |
| query | string | 可选 | retrieve 的检索问题，最多 2000 字。 |
| mode | string | 可选 | index 可指定 keyword 使用关键词索引；否则使用智能体当前配置的向量模型。 |

响应示例：
```json
{
  "chunks": []
}
```

- 响应示例仅展示其中一个分支的部分字段；其他字段依查询与 action 返回，不能据此生成严格 DTO。
- GET 不传 id 列出文档；传 id 返回文档和切片。save 保存草稿，preview 仅切片，index 真实调用向量模型，retrieve 按智能体知识配置检索，publish 只发布已完成且匹配当前配置的索引，unpublish/delete 受版本与引用约束。
- 应用接口沿用原业务去重规则；Bearer 网关增加操作级幂等，不取代 revision 校验。

### 知识库 · 检索

`POST /v1/operations/knowledge.retrieve`

权限：knowledge
费用：可能产生模型、工具或通话费用。

```sh
# cURL 7.76+；请先在服务端设置环境变量。
: "${YUNFU_BASE_URL:?请设置服务端 HTTPS 地址}"
: "${YUNFU_API_KEY:?请设置已获授权的 API 密钥}"
: "${YUNFU_IDEMPOTENCY_KEY:?请设置本次写入的唯一编号，重试沿用原编号}"
curl --fail-with-body --show-error "$YUNFU_BASE_URL/v1/operations/knowledge.retrieve?agentId=YOUR_AGENT_ID" \
  -H "Authorization: Bearer $YUNFU_API_KEY" \
  -H "Idempotency-Key: $YUNFU_IDEMPOTENCY_KEY" \
  -H 'Content-Type: application/json' \
  --data-binary '{
  "action": "retrieve",
  "query": "退款需要哪些材料？",
  "scope": "published",
  "expectedVersion": 1
}'
```

| 字段 | 类型 | 要求 | 说明 |
| --- | --- | --- | --- |
| agentId (query) | string | 可选 | 已配置知识绑定的智能体编号。 |
| query | string | 必填 | 检索问题，最多 2000 字。 |
| scope | string | 可选 | draft 或 published；默认 draft。 |
| expectedVersion | integer | 可选 | 对应草稿 revision 或已发布 publishedVersion；用于核对目标版本。 |

响应示例：
```json
{
  "scope": "published",
  "version": 1,
  "hits": []
}
```

- 先读取文档或智能体的当前版本，不照抄示例中的版本号。
- 检索按所选智能体的知识绑定与版本执行；published 需已有发布版本。

### 知识库 · 建立索引

`POST /v1/operations/knowledge.index`

权限：knowledge
费用：可能产生模型、工具或通话费用。

```sh
# cURL 7.76+；请先在服务端设置环境变量。
: "${YUNFU_BASE_URL:?请设置服务端 HTTPS 地址}"
: "${YUNFU_API_KEY:?请设置已获授权的 API 密钥}"
: "${YUNFU_IDEMPOTENCY_KEY:?请设置本次写入的唯一编号，重试沿用原编号}"
curl --fail-with-body --show-error "$YUNFU_BASE_URL/v1/operations/knowledge.index" \
  -H "Authorization: Bearer $YUNFU_API_KEY" \
  -H "Idempotency-Key: $YUNFU_IDEMPOTENCY_KEY" \
  -H 'Content-Type: application/json' \
  --data-binary '{
  "action": "index",
  "id": "YOUR_DOCUMENT_ID",
  "revision": 1
}'
```

| 字段 | 类型 | 要求 | 说明 |
| --- | --- | --- | --- |
| id | string | 必填 | 已存在的知识文档编号。 |
| revision | integer | 必填 | 知识目录读取的当前文档版本。 |

响应示例：
```json
{
  "ok": true
}
```

- 先读取文档或智能体的当前版本，不照抄示例中的版本号。

### 知识库 · 发布

`POST /v1/operations/knowledge.publish`

权限：knowledge
费用：按业务权限与套餐执行。

```sh
# cURL 7.76+；请先在服务端设置环境变量。
: "${YUNFU_BASE_URL:?请设置服务端 HTTPS 地址}"
: "${YUNFU_API_KEY:?请设置已获授权的 API 密钥}"
: "${YUNFU_IDEMPOTENCY_KEY:?请设置本次写入的唯一编号，重试沿用原编号}"
curl --fail-with-body --show-error "$YUNFU_BASE_URL/v1/operations/knowledge.publish" \
  -H "Authorization: Bearer $YUNFU_API_KEY" \
  -H "Idempotency-Key: $YUNFU_IDEMPOTENCY_KEY" \
  -H 'Content-Type: application/json' \
  --data-binary '{
  "action": "publish",
  "id": "YOUR_DOCUMENT_ID",
  "revision": 2
}'
```

| 字段 | 类型 | 要求 | 说明 |
| --- | --- | --- | --- |
| id | string | 必填 | 已存在的知识文档编号。 |
| revision | integer | 必填 | 知识目录读取的当前文档版本。 |

响应示例：
```json
{
  "ok": true
}
```

- 先读取文档或智能体的当前版本，不照抄示例中的版本号。
- 须先完成当前草稿索引（ready），并满足已绑定智能体的向量配置。

### 知识库 · 撤回文档发布

`POST /v1/operations/knowledge.unpublish`

权限：knowledge
费用：按业务权限与套餐执行。

```sh
# cURL 7.76+；请先在服务端设置环境变量。
: "${YUNFU_BASE_URL:?请设置服务端 HTTPS 地址}"
: "${YUNFU_API_KEY:?请设置已获授权的 API 密钥}"
: "${YUNFU_IDEMPOTENCY_KEY:?请设置本次写入的唯一编号，重试沿用原编号}"
curl --fail-with-body --show-error "$YUNFU_BASE_URL/v1/operations/knowledge.unpublish" \
  -H "Authorization: Bearer $YUNFU_API_KEY" \
  -H "Idempotency-Key: $YUNFU_IDEMPOTENCY_KEY" \
  -H 'Content-Type: application/json' \
  --data-binary '{
  "action": "unpublish",
  "id": "YOUR_DOCUMENT_ID",
  "revision": 3
}'
```

| 字段 | 类型 | 要求 | 说明 |
| --- | --- | --- | --- |
| id | string | 必填 | 知识文档编号。先调用 knowledge.read，取 documents[].id。 |
| revision | integer | 必填 | 该文档的当前版本号，取 knowledge.read 返回的 documents[].revision。必须是 JSON 数字并与服务端完全一致，否则返回 409。 |

响应示例：
```json
{
  "ok": true
}
```

- 前置条件：先调用 knowledge.read 取得 id 与 revision。本操作不读取 agentId 查询参数，也不要求文档处于某个状态；对一篇尚未发布的文档调用同样返回成功，并使 revision 加 1。
- 对智能体的影响：接口不检查文档是否被智能体使用。已发布智能体如果绑定了这篇文档，会立即检索不到它，但绑定关系不会被移除；之后再发布这些智能体时，发布检查会因“知识尚未发布”而不通过，直到重新发布该文档或在智能体配置中解除绑定。
- 可逆：文档 status 为 ready 且 draft_gen 非空时，用新的 revision 调用 knowledge.publish 即可重新上线，无需重建索引；重新上线的是当前草稿索引，不一定是撤回前的线上版本。若文档在此之前被改过（status 为 draft 或 error），需先调用 knowledge.index（会计费）。
- 错误：404 文档不存在或未传 id；409 revision 与当前版本不一致（“文档版本已变化，请重新加载”）；409 文档正在索引且最近 180 秒内有更新（“文档正在索引，请等待完成后再操作”）；409 写入时文档版本或密钥授权已变化（“文档已更新”）。遇到 409 先重新读取再决定是否重试。

### 知识库 · 永久删除文档

`POST /v1/operations/knowledge.delete`

权限：knowledge
费用：按业务权限与套餐执行。

```sh
# cURL 7.76+；请先在服务端设置环境变量。
: "${YUNFU_BASE_URL:?请设置服务端 HTTPS 地址}"
: "${YUNFU_API_KEY:?请设置已获授权的 API 密钥}"
: "${YUNFU_IDEMPOTENCY_KEY:?请设置本次写入的唯一编号，重试沿用原编号}"
curl --fail-with-body --show-error "$YUNFU_BASE_URL/v1/operations/knowledge.delete" \
  -H "Authorization: Bearer $YUNFU_API_KEY" \
  -H "Idempotency-Key: $YUNFU_IDEMPOTENCY_KEY" \
  -H 'Content-Type: application/json' \
  --data-binary '{
  "action": "delete",
  "id": "YOUR_DOCUMENT_ID",
  "revision": 3
}'
```

| 字段 | 类型 | 要求 | 说明 |
| --- | --- | --- | --- |
| id | string | 必填 | 知识文档编号。先调用 knowledge.read，取 documents[].id。 |
| revision | integer | 必填 | 该文档的当前版本号，取 knowledge.read 返回的 documents[].revision。必须是 JSON 数字并与服务端完全一致，否则返回 409。 |

响应示例：
```json
{
  "ok": true
}
```

- 前置条件：先调用 knowledge.read 取得 id 与 revision。草稿、已索引和已发布的文档都可以直接删除，不需要先调用 knowledge.unpublish；本操作不读取 agentId 查询参数。
- 不可逆：接口直接删除文档和切片，没有回收站。需要保留内容时，请先用 knowledge.read?id=文档编号 读取正文自行备份。
- 对智能体的影响：接口不检查文档是否被智能体使用。已发布智能体立即检索不到这篇文档，但智能体配置中仍保留该文档编号；之后再发布这些智能体时，发布检查会因“知识尚未发布”而不通过，需先在智能体配置中移除绑定。
- 来自知识源同步的文档（source_id 非空）：如果知识源的 refs 仍包含对应引用，下一次同步会用相同的文档编号把它重新创建为草稿。要彻底移除，请先用 knowledge-sources.save 从 refs 中去掉该引用。
- 错误：404 文档不存在或未传 id；409 revision 与当前版本不一致；409 文档正在索引且最近 180 秒内有更新；409 写入时文档版本或密钥授权已变化（“文档已更新，未执行删除”）。响应不确定时用同一个 Idempotency-Key 重试；换新键重试一篇已删除的文档会得到 404。

### 读取知识源

`GET /v1/operations/knowledge-sources.read`

权限：knowledge
费用：按业务权限与套餐执行。

```sh
# cURL 7.76+；请先在服务端设置环境变量。
: "${YUNFU_BASE_URL:?请设置服务端 HTTPS 地址}"
: "${YUNFU_API_KEY:?请设置已获授权的 API 密钥}"
curl --fail-with-body --show-error "$YUNFU_BASE_URL/v1/operations/knowledge-sources.read" \
  -H "Authorization: Bearer $YUNFU_API_KEY"
```

响应示例：
```json
{
  "sources": [],
  "logs": []
}
```

- 响应示例仅展示其中一个分支的部分字段；其他字段依查询与 action 返回，不能据此生成严格 DTO。
- GET 返回 sources/logs/scheduler。sync 执行已保存来源同步，save 保存连接，pause 启停；定时同步必须有原生 scheduled 调度。同步内容作为不可信知识，不具备修改系统指令或授权的能力。
- 应用接口沿用原业务去重规则；Bearer 网关增加操作级幂等，不取代 revision 校验。

### 知识源 · 新建或更新连接

`POST /v1/operations/knowledge-sources.save`

权限：knowledge
费用：按业务权限与套餐执行。

```sh
# cURL 7.76+；请先在服务端设置环境变量。
: "${YUNFU_BASE_URL:?请设置服务端 HTTPS 地址}"
: "${YUNFU_API_KEY:?请设置已获授权的 API 密钥}"
: "${YUNFU_IDEMPOTENCY_KEY:?请设置本次写入的唯一编号，重试沿用原编号}"
curl --fail-with-body --show-error "$YUNFU_BASE_URL/v1/operations/knowledge-sources.save" \
  -H "Authorization: Bearer $YUNFU_API_KEY" \
  -H "Idempotency-Key: $YUNFU_IDEMPOTENCY_KEY" \
  -H 'Content-Type: application/json' \
  --data-binary '{
  "action": "save",
  "provider": "website",
  "name": "官网帮助文档",
  "appId": {
    "schemaVersion": 1,
    "startUrl": "https://docs.your-company.com/",
    "maxPages": 100,
    "maxDepth": 2,
    "followSitemap": false
  },
  "refs": [
    "https://docs.your-company.com/"
  ],
  "intervalHours": 24
}'
```

| 字段 | 类型 | 要求 | 说明 |
| --- | --- | --- | --- |
| id | string | 条件必填：更新已有知识源 | 知识源编号，取 knowledge-sources.read 返回的 sources[].id。省略表示新建。 |
| revision | integer | 条件必填：更新已有知识源 | 该知识源的当前版本号，取 sources[].revision；必须是 JSON 数字并与服务端一致。 |
| provider | string | 必填 | 来源平台：website（网站/Sitemap）、http_api（通用 API）、notion、google_drive、slack、confluence、sharepoint、feishu、wecom、dingtalk。更新时不能更换平台。 |
| name | string | 必填 | 连接名称，1–80 个字符。 |
| refs | string[] | 条件必填：除钉钉统一应用方式（provider=dingtalk 且 authMode=platform）外的所有来源 | 要同步的文档引用，1–8 项，每项最多 500 个字符，重复项会合并。website：填与 appId.startUrl 相同的公网 HTTPS 起始页地址（实际抓取范围由 appId 决定）；http_api：读取接口的 HTTPS 地址，必须与 appId.origin 同域名；notion：页面链接或 32 位页面 ID；google_drive：文件链接或文件 ID；slack：频道 ID、“频道 ID:线程时间戳”或官方频道/线程链接；confluence：页面链接或数字页面 ID；sharepoint：页面 UUID；feishu：docs/docx/wiki 文档链接；wecom：文档链接或 docid；dingtalk 自建应用：文档链接或文档 ID。 |
| appId | object | 条件必填：provider 为 website、http_api、confluence、sharepoint，或 feishu、wecom、dingtalk 使用自建应用（authMode 不是 platform） | 来源的非密钥配置。website、http_api、dingtalk 传对象（字段见下方 appId.*）；confluence 传站点地址字符串（如 https://your-team.atlassian.net）；sharepoint 传 Microsoft Graph 站点 ID 字符串；feishu、wecom 自建应用传应用 ID 字符串（1–120 位字母、数字、下划线或连字符）。notion、google_drive、slack 不使用此字段。该值会在 knowledge-sources.read 中以 app_id 原样返回，不要放入密钥。 |
| appId.schemaVersion | integer | 条件必填：provider 为 website 或 http_api | 配置版本，固定为 1。 |
| appId.startUrl | string | 条件必填：provider 为 website | 抓取起始页的公网 HTTPS 地址，最多 500 个字符，不能包含账号密码或 # 片段。 |
| appId.maxPages | integer | 可选 | 仅 website：最多抓取的页面数，1–500，省略为 100。 |
| appId.maxDepth | integer | 可选 | 仅 website：从起始页跟随同源链接的最大深度，0–5，省略为 2。 |
| appId.followSitemap | boolean | 可选 | 仅 website：true 时同时抓取站点 sitemap 中的页面，省略为 false。 |
| appId.origin | string | 条件必填：provider 为 http_api | 业务接口的服务域名，只写协议和域名（如 https://api.your-company.com），必须是公网 HTTPS，不能带路径、查询、端口或凭据。 |
| appId.auth | string | 条件必填：provider 为 http_api | 鉴权方式：bearer（secret 作为 Authorization: Bearer 发送）、header（secret 放入 appId.headerName 指定的请求头）或 none（不需要 secret）。 |
| appId.headerName | string | 条件必填：appId.auth 为 header | 携带 secret 的请求头名称，如 X-API-Key；字母开头，只含字母、数字和连字符，最多 64 位，不能是 Authorization、Cookie、Host、Content-Length、Content-Type、Connection 或 Accept。 |
| appId.recordsPath | string | 条件必填：provider 为 http_api | 响应 JSON 中资料列表的点分路径（如 data.items），最多 160 个字符；列表就在响应根部时传空字符串。 |
| appId.idPath | string | 条件必填：provider 为 http_api | 每条资料中稳定标识字段的点分路径，不能为空。 |
| appId.titlePath | string | 条件必填：provider 为 http_api | 每条资料中标题字段的点分路径，不能为空。 |
| appId.contentPath | string | 条件必填：provider 为 http_api | 每条资料中正文字段的点分路径，不能为空。 |
| appId.urlPath | string | 条件必填：provider 为 http_api | 每条资料中来源链接字段的点分路径；没有时传空字符串（不能省略该键）。 |
| appId.updatedPath | string | 条件必填：provider 为 http_api | 每条资料中更新时间字段的点分路径；没有时传空字符串（不能省略该键）。 |
| appId.nextCursorPath | string | 条件必填：provider 为 http_api | 响应 JSON 中下一页游标的点分路径；接口不分页时传空字符串（不能省略该键）。单次同步最多读取 5 页、200 条资料。 |
| appId.cursorParameter | string | 条件必填：appId.nextCursorPath 非空 | 翻页时携带游标的查询参数名，字母开头，只含字母、数字和下划线，最多 64 位，名称中不能含 token、secret、password 或 key。 |
| appId.appKey | string | 条件必填：provider 为 dingtalk 且使用自建应用 | 钉钉自建应用的 AppKey，最多 120 个字符。 |
| appId.operatorId | string | 条件必填：provider 为 dingtalk 且使用自建应用 | 有权读取目标文档的钉钉操作人 Union ID，最多 200 个字符。 |
| secret | string | 条件必填：新建需要凭据的来源；或更新时更换了 appId（http_api 为 origin、auth、headerName 任一变化） | 访问凭据，最多 8192 个字符，不能含换行。notion：内部连接 Token；google_drive：有 drive.readonly 权限的 OAuth 访问令牌；slack：xoxb-/xoxp- OAuth Token；confluence：“邮箱:API 令牌”；sharepoint：Microsoft Graph 访问令牌；http_api：接口凭据；feishu、wecom、dingtalk 自建应用：应用密钥。website、http_api 的 auth=none 以及统一应用方式不需要。更新时省略则沿用已保存的凭据。凭据只加密保存，任何读取接口都不返回明文，只返回 secretSet。 |
| authMode | string | 可选 | 连接方式：platform（复用平台统一应用，仅 feishu、wecom、dingtalk 可用）或 custom（自建应用或自备凭据）。新建时省略按 custom 处理；更新时省略沿用原方式。 |
| connectionId | string | 条件必填：authMode 为 platform 的新建 | 企业已授权的统一应用连接编号，取 knowledge-sources.read 返回的 feishuConnections、wecomConnections 或 dingtalkConnections 中 available 为 true 的 id。 |
| intervalHours | integer | 必填 | 定时同步间隔（小时），只能是 0、1、6、24 或 168；0 表示只手动同步。钉钉统一应用方式必须为 0。大于 0 时，保存后该来源立即到期，等待调度拉取。 |
| enabled | boolean | 可选 | 是否启用同步。只有显式传 false 才停用；省略按 true 处理，因此更新一个已暂停的来源时省略此字段会把它重新启用。 |
| targetLibraryId | string | 可选 | 同步内容同时写入的帮助中心资料库编号，取 knowledge-sources.read 返回的 libraries 中 enabled 为 true 的 id，最多 100 个字符。传空字符串清除；更新时省略沿用原值。 |
| exportDocument | object | 条件必填：provider=dingtalk 且 authMode=platform 的首次保存 | 从钉钉导出的文档内容；钉钉统一应用方式不读取云端文档，只同步这里提交的正文。更新时省略沿用上次提交的内容。 |
| exportDocument.title | string | 条件必填：提供 exportDocument | 文档标题，1–200 个字符。 |
| exportDocument.content | string | 条件必填：提供 exportDocument | 文档正文，最多 50,000 个字符；更长的文档请拆成多个知识源。 |
| exportDocument.fileName | string | 条件必填：提供 exportDocument | 导出文件名，最多 255 个字符，可为空字符串。 |
| exportDocument.warnings | string[] | 条件必填：提供 exportDocument | 导入时需要提示的缺失内容说明，最多 50 条、每条最多 1000 个字符；没有时传空数组。 |

响应示例：
```json
{
  "ok": true,
  "id": "YOUR_SOURCE_ID"
}
```

- 前置条件：更新前先调用 knowledge-sources.read 取得 sources[].id 与 revision；新建不传 id。每个企业最多 20 个知识源，超出返回 409。
- 凭据提交与回显：secret 只写不读，读取时只有 secretSet 表示是否已配置；appId 和 refs 会原样返回，不要在其中放密钥（http_api 的地址若带 token、secret、password、authorization、api_key 这类查询参数会被拒绝）。
- 更新的副作用：保存会把来源状态重置为 ready 并清空上次错误；正在排队或执行的同步会因版本变化而中止，尚未写入的文档不再写入，也不生成同步记录；省略 enabled 会重新启用来源。
- 错误：400 字段校验失败（未知 provider、refs 不是 1–8 项或格式不符、intervalHours 不在允许值内、缺少凭据、更换 appId 后未重新提供 secret、更新时更换 provider、authMode 无效等）；403 所选平台不适用于当前站点，或统一应用授权不属于当前企业、尚未完成授权；404 知识源不存在，或 targetLibraryId 不存在、已停用；409 revision 不一致（“来源已修改，请刷新后重试”）；409 “连接已达 20 个，或账户权限已变化”。
- 归属与大小：知识源归属于保存它的企业管理员账号（API Key 调用时为密钥所属账号）；该账号停用或失去知识权限后，同步会被取消，来源可能被置为停用并标记为需要重新授权（status 为 reauthorize），需重新保存连接。请求正文最多 150,000 个字符。
- API Key 调用的限制：平台可用范围固定按中国站规则判定，provider 为 confluence 或 sharepoint 时固定返回 403“该知识平台仅适用于国际站”。
- 重试：新建不按名称去重。响应不确定时用同一个 Idempotency-Key 重试会重放原结果；不要换新键重试，应先调用 knowledge-sources.read 确认是否已创建。

### 知识源 · 立即同步

`POST /v1/operations/knowledge-sources.sync`

权限：knowledge
费用：按业务权限与套餐执行。

```sh
# cURL 7.76+；请先在服务端设置环境变量。
: "${YUNFU_BASE_URL:?请设置服务端 HTTPS 地址}"
: "${YUNFU_API_KEY:?请设置已获授权的 API 密钥}"
: "${YUNFU_IDEMPOTENCY_KEY:?请设置本次写入的唯一编号，重试沿用原编号}"
curl --fail-with-body --show-error "$YUNFU_BASE_URL/v1/operations/knowledge-sources.sync" \
  -H "Authorization: Bearer $YUNFU_API_KEY" \
  -H "Idempotency-Key: $YUNFU_IDEMPOTENCY_KEY" \
  -H 'Content-Type: application/json' \
  --data-binary '{
  "action": "sync",
  "id": "YOUR_SOURCE_ID",
  "revision": 1
}'
```

| 字段 | 类型 | 要求 | 说明 |
| --- | --- | --- | --- |
| id | string | 必填 | 知识源编号，取 knowledge-sources.read 返回的 sources[].id。 |
| revision | integer | 必填 | 该知识源的当前版本号，取 sources[].revision；必须是 JSON 数字并与服务端一致。 |

响应示例：
```json
{
  "accepted": true,
  "taskId": "YOUR_TASK_ID",
  "sourceId": "YOUR_SOURCE_ID",
  "status": "queued",
  "reused": false
}
```

- 前置条件：先调用 knowledge-sources.read 取得 sources[].id 与 revision，并确认来源 enabled 为 1。成功的状态码是 202 而不是 200。
- 查询进度：轮询 knowledge-sources.read?mode=progress，返回 sources[]（id、revision、status、error、last_at、next_at、lease_until、task_id、task_status、task_updated）；task_status 为 pending 或 leased 表示仍在排队或执行；长时间停在 pending 时，查看 knowledge-sources.read 返回的 scheduler.mode 与 scheduler.message 确认后台执行进程是否在线。结束后调用 knowledge-sources.read?selected=知识源编号（不带 mode），在 logs[] 中查看该来源最新一条记录（logs 只含全企业最近 100 条，selected 保证包含该来源最近一次的记录）：status 为 success、partial 或 error，detail 含 added、changed、unchanged、failures 以及每个引用的 results（outcome、documentId、error）。
- 同步之后：新增或有变化的文档是草稿（status 为 draft），需要对每篇文档依次调用 knowledge.index 和 knowledge.publish 才会被线上检索命中；已在本地补齐并脱离同步的文档不会被覆盖。
- 费用：同步只读取来源并写入草稿，不调用模型，不产生费用；向量化费用在后续的 knowledge.index 产生。
- 错误：404 未传 id 或知识源不存在；409 revision 不一致；429“拉取暂未受理”——来源已停用、正在同步、距上次同步结束不足 15 秒、仍在来源平台限流冷却期，或排队中的同步任务已达上限（响应带 Retry-After，但来源停用时重试无效，需先调用 knowledge-sources.pause 并传 enabled=true）；409“旧配置的任务正在结束，请稍后重新拉取”；403 飞书、企业微信或钉钉统一应用的企业授权已失效。
- 重复调用：同一知识源同一时间只有一个同步任务，重复调用返回同一个 taskId 且 reused 为 true。单次同步最长执行约 330 秒，附件下载合计不超过 64 MiB；超时后未处理的引用在同步记录中标为 not_processed，留待下次同步。
- 已知限制：provider 为 dingtalk 且使用自建应用（authMode 为 custom）的知识源不能用本操作手动同步，固定返回 400“请选择当前企业的钉钉统一应用”，只能等待定时同步（intervalHours 大于 0）。
- API Key 调用：后台任务以密钥所属账号的身份执行；任务开始前该账号被停用或失去知识权限时，任务会被取消且不生成同步记录。

### 知识源 · 启用或暂停同步

`POST /v1/operations/knowledge-sources.pause`

权限：knowledge
费用：按业务权限与套餐执行。

```sh
# cURL 7.76+；请先在服务端设置环境变量。
: "${YUNFU_BASE_URL:?请设置服务端 HTTPS 地址}"
: "${YUNFU_API_KEY:?请设置已获授权的 API 密钥}"
: "${YUNFU_IDEMPOTENCY_KEY:?请设置本次写入的唯一编号，重试沿用原编号}"
curl --fail-with-body --show-error "$YUNFU_BASE_URL/v1/operations/knowledge-sources.pause" \
  -H "Authorization: Bearer $YUNFU_API_KEY" \
  -H "Idempotency-Key: $YUNFU_IDEMPOTENCY_KEY" \
  -H 'Content-Type: application/json' \
  --data-binary '{
  "action": "pause",
  "id": "source_example",
  "revision": 1,
  "enabled": false
}'
```

| 字段 | 类型 | 要求 | 说明 |
| --- | --- | --- | --- |
| id | string | 可选 | 操作目标的真实资源 ID；不能使用其他企业 ID。 |
| revision | integer | 可选 | 先读取当前资源修订号；共享配置与单资源修订号不可混用。 |
| provider / name / appId | string | 可选 | 来源平台、连接名称、应用编号；Notion 不需要 appId。 |
| secret | string | 见说明 | 首次保存或更换应用时必填连接凭据；只加密存储。 |
| refs | array | 可选 | 来源平台的文档引用列表。 |
| intervalHours | integer | 可选 | 0/1/6/24/168。 |
| enabled | boolean | 可选 | save/pause 的启用状态。 |

响应示例：
```json
{
  "ok": true
}
```

- 响应示例仅展示其中一个分支的部分字段；其他字段依查询与 action 返回，不能据此生成严格 DTO。
- GET 返回 sources/logs/scheduler。sync 执行已保存来源同步，save 保存连接，pause 启停；定时同步必须有原生 scheduled 调度。同步内容作为不可信知识，不具备修改系统指令或授权的能力。
- 应用接口沿用原业务去重规则；Bearer 网关增加操作级幂等，不取代 revision 校验。

### 读取客服知识检索

`GET /v1/operations/desk-knowledge.read`

权限：service
费用：按业务权限与套餐执行。

```sh
# cURL 7.76+；请先在服务端设置环境变量。
: "${YUNFU_BASE_URL:?请设置服务端 HTTPS 地址}"
: "${YUNFU_API_KEY:?请设置已获授权的 API 密钥}"
curl --fail-with-body --show-error "$YUNFU_BASE_URL/v1/operations/desk-knowledge.read?q=%E9%80%80%E6%AC%BE&page=1" \
  -H "Authorization: Bearer $YUNFU_API_KEY"
```

| 字段 | 类型 | 要求 | 说明 |
| --- | --- | --- | --- |
| q | string | 可选 | 关键词，最多 80 字符。 |
| libraryId | string | 可选 | 帮助中心 ID，最多 100 字符。 |
| visibility | internal \| public | 可选 | 限定内外部可见性；省略表示全部授权知识。 |
| favorites | 0 \| 1 | 可选 | 本人收藏筛选。 |
| scope | all \| enterprise \| personal | 可选 | 全部、企业或本人资料，仍受当前登录主体权限限制。 |
| content | all \| documents | 可选 | 默认全部；documents 仅保留正文中实际引用可访问文件附件的资料，筛选在分页前完成。 |
| category | string | 可选 | 精确分类，最多 40 字符；省略表示全部，空值表示未分类；个人资料暂未分类。 |
| sort | updated \| title | 可选 | 默认按最近更新，或按标题排序；并列值按更新时间和条目 ID 稳定排序。 |
| page | integer | 可选 | 1 至 10000。 |

响应示例：
```json
{
  "articles": [],
  "total": 0
}
```

- 人工客服可检索对内和公开知识；不放宽外部客户的公开内容边界。

### 读取电话呼入呼出

`GET /v1/operations/phone-calls.read`

权限：service
费用：按业务权限与套餐执行。

```sh
# cURL 7.76+；请先在服务端设置环境变量。
: "${YUNFU_BASE_URL:?请设置服务端 HTTPS 地址}"
: "${YUNFU_API_KEY:?请设置已获授权的 API 密钥}"
curl --fail-with-body --show-error "$YUNFU_BASE_URL/v1/operations/phone-calls.read?view=calls&page=1&pageSize=100&compact=1&qMode=metadata" \
  -H "Authorization: Bearer $YUNFU_API_KEY"
```

| 字段 | 类型 | 要求 | 说明 |
| --- | --- | --- | --- |
| view | calls | 必填 | 电话列表模式；开放操作 phone-calls.read 固定此值。 |
| page / pageSize | integer / 20\|50\|100 | 可选 | page 为 1–10000，默认 1；pageSize 默认 20，实际返回 page 可能钳制到最后一页。 |
| compact | 1 | 可选 | 移除列表转写正文，messages 返回空数组；完整转写用详情或批量导出。 |
| direction | inbound \| outbound | 可选 | 省略表示两个方向。 |
| status | queued \| ringing \| active \| completed \| failed \| no_answer \| canceled \| unknown \| live \| finished | 可选 | live 包含 queued/ringing/active，finished 包含四个终态；unknown 不属于失败或终态。 |
| scope | all \| service \| test | 可选 | 默认 all；此电话记录接口不返回语音演练记录，test 当前为空。 |
| lineId / batchId / planId | string | 可选 | 按真实资源编号筛选，各最多 100 字符。 |
| q / qMode | string / metadata\|all | 可选 | q 最多 100 字符；qMode 默认 all，包含转写正文；建议列表显式 metadata。 |
| start / end | Unix 毫秒 | 可选 | 按创建时间筛选，start 包含、end 不包含；两者均传时 end 必须大于 start。 |

响应示例：
```json
{
  "calls": [],
  "total": 0,
  "page": 1,
  "pageSize": 100,
  "metrics": {
    "total": 0,
    "answered": 0,
    "active": 0,
    "unknown": 0,
    "failed": 0,
    "averageDuration": 0,
    "answerRate": null
  },
  "canCall": true,
  "canOutbound": true,
  "canInbound": false,
  "canTelephone": true
}
```

- 返回当前企业电话记录；不能将分页列表、unknown 结果或空转写当作呼叫完成凭据。

### 电话呼入呼出 · 拨号

`POST /v1/operations/phone-calls.dial`

权限：service
费用：可能产生模型、工具或通话费用。

```sh
# cURL 7.76+；请先在服务端设置环境变量。
: "${YUNFU_BASE_URL:?请设置服务端 HTTPS 地址}"
: "${YUNFU_API_KEY:?请设置已获授权的 API 密钥}"
: "${YUNFU_IDEMPOTENCY_KEY:?请设置本次写入的唯一编号，重试沿用原编号}"
curl --fail-with-body --show-error "$YUNFU_BASE_URL/v1/operations/phone-calls.dial" \
  -H "Authorization: Bearer $YUNFU_API_KEY" \
  -H "Idempotency-Key: $YUNFU_IDEMPOTENCY_KEY" \
  -H 'Content-Type: application/json' \
  --data-binary '{
  "action": "dial",
  "requestId": "44444444-4444-4444-8444-444444444444",
  "channelId": "22222222-2222-4222-8222-222222222222",
  "to": "+8613800138000",
  "confirmed": true
}'
```

| 字段 | 类型 | 要求 | 说明 |
| --- | --- | --- | --- |
| action | dial | 可选 | 可省略，系统固定为 dial；传入其他值返回 400。 |
| requestId | UUID 字符串 | 必填 | 本次业务请求 ID，36 位；重试必须保留同一 ID、渠道和号码，与开放网关 Idempotency-Key 独立。 |
| channelId | string | 必填 | 真实、已启用电话渠道 ID；其线路须可呼出、已同步注册或免注册就绪。不是 lineId。 |
| to | E.164 string | 必填 | 已确认的真实被叫号码，含 + 国家区号；号码不能作为数值。 |
| confirmed | true | 必填 | 用户已授权本次号码与线路的真实呼叫。 |

响应示例：
```json
{
  "call": {
    "id": "33333333-3333-4333-8333-333333333333",
    "status": "queued"
  },
  "notice": ""
}
```

- 号码必须在用户授权范围内，线路及启用渠道需可外呼并通过并发、黑名单、服务权益和媒体就绪检查；调用会产生真实电话并可能计费。
- 结果为 unknown 或网络超时时停止新拨号，先用原 call.id 查询详情；重放保留 requestId、正文和开放网关幂等键，不能用新 ID 将未知请求当作失败重拨。
- 本接口依赖已绑定渠道的发布方案；小电话的 lineId/agentId 快速测试属于另一协议，不能混用。

### 电话呼入呼出 · 挂断

`POST /v1/operations/phone-calls.hangup`

权限：service
费用：按业务权限与套餐执行。

```sh
# cURL 7.76+；请先在服务端设置环境变量。
: "${YUNFU_BASE_URL:?请设置服务端 HTTPS 地址}"
: "${YUNFU_API_KEY:?请设置已获授权的 API 密钥}"
: "${YUNFU_IDEMPOTENCY_KEY:?请设置本次写入的唯一编号，重试沿用原编号}"
curl --fail-with-body --show-error "$YUNFU_BASE_URL/v1/operations/phone-calls.hangup" \
  -H "Authorization: Bearer $YUNFU_API_KEY" \
  -H "Idempotency-Key: $YUNFU_IDEMPOTENCY_KEY" \
  -H 'Content-Type: application/json' \
  --data-binary '{
  "action": "hangup",
  "id": "33333333-3333-4333-8333-333333333333"
}'
```

| 字段 | 类型 | 要求 | 说明 |
| --- | --- | --- | --- |
| action | hangup | 可选 | 可省略，系统固定为 hangup；传入其他值返回 400。 |
| id | string | 必填 | 同企业真实电话 call.id，最多 100 字符；不是线路、渠道或语音演练 ID。 |

响应示例：
```json
{
  "requested": true
}
```

- 网关未明确接受时返回 503；读取原通话状态核实，不将请求已接受视为最终挂断、时长或并发已释放。

### 读取电话详情

`GET /v1/operations/phone-detail.read`

权限：service
费用：按业务权限与套餐执行。

```sh
# cURL 7.76+；请先在服务端设置环境变量。
: "${YUNFU_BASE_URL:?请设置服务端 HTTPS 地址}"
: "${YUNFU_API_KEY:?请设置已获授权的 API 密钥}"
curl --fail-with-body --show-error "$YUNFU_BASE_URL/v1/operations/phone-detail.read?view=call&id=33333333-3333-4333-8333-333333333333" \
  -H "Authorization: Bearer $YUNFU_API_KEY"
```

| 字段 | 类型 | 要求 | 说明 |
| --- | --- | --- | --- |
| view | call | 必填 | 详情模式；开放操作 phone-detail.read 固定此值。 |
| id | string | 必填 | 真实电话记录 ID，非 voiceSessionId，最多 100 字符。 |
| direction / status / scope / lineId / batchId / planId / q / qMode / start / end | 同电话列表筛选 | 可选 | 可选，仅决定 previous/next；按 id 读取的详情独立于列表页和筛选范围。 |

响应示例：
```json
{
  "call": {
    "id": "33333333-3333-4333-8333-333333333333",
    "status": "completed",
    "summary": "",
    "messages": []
  },
  "previous": null,
  "next": null,
  "canCall": true,
  "canOutbound": true,
  "canInbound": false,
  "canTelephone": true
}
```

- call.summary 可能尚未上报或为空；缺失转写或总结时明确报告缺失，不能猜测通话结论。

### 读取批量外呼

`GET /v1/operations/outbound-batches.read`

权限：service, agent
费用：按业务权限与套餐执行。

```sh
# cURL 7.76+；请先在服务端设置环境变量。
: "${YUNFU_BASE_URL:?请设置服务端 HTTPS 地址}"
: "${YUNFU_API_KEY:?请设置已获授权的 API 密钥}"
curl --fail-with-body --show-error "$YUNFU_BASE_URL/v1/operations/outbound-batches.read?page=1" \
  -H "Authorization: Bearer $YUNFU_API_KEY"
```

| 字段 | 类型 | 要求 | 说明 |
| --- | --- | --- | --- |
| id | string | 可选 | 批次详情编号；省略读取列表。 |
| page | integer | 可选 | 从 1 开始；列表每页 20，号码每页 50。 |
| status | string | 可选 | 草稿、预约、运行、暂停、完成、取消对应的英文状态。 |
| view | string | 可选 | import 查询号码导入进度；resources 查询线路和发布计划；templates 查询配置模板。 |

响应示例：
```json
{
  "batches": [],
  "total": 0,
  "page": 1,
  "pageSize": 20
}
```

- 已实现：查询批次与号码进度，GET 不执行拨号。电话对话记录通过 /v1/operations/phone-calls.read?direction=outbound&batchId=... 筛选。

### 批量外呼 · 保存

`POST /v1/operations/outbound-batches.save`

权限：service, agent
费用：按业务权限与套餐执行。

```sh
# cURL 7.76+；请先在服务端设置环境变量。
: "${YUNFU_BASE_URL:?请设置服务端 HTTPS 地址}"
: "${YUNFU_API_KEY:?请设置已获授权的 API 密钥}"
: "${YUNFU_IDEMPOTENCY_KEY:?请设置本次写入的唯一编号，重试沿用原编号}"
curl --fail-with-body --show-error "$YUNFU_BASE_URL/v1/operations/outbound-batches.save" \
  -H "Authorization: Bearer $YUNFU_API_KEY" \
  -H "Idempotency-Key: $YUNFU_IDEMPOTENCY_KEY" \
  -H 'Content-Type: application/json' \
  --data-binary '{
  "action": "save",
  "requestId": "batch_example_request_1",
  "name": "预约提醒",
  "lineId": "line_uuid",
  "agentId": "default",
  "version": 1,
  "concurrency": 1,
  "reserved": 1,
  "recipients": [
    {
      "phone": "+8613800138000",
      "name": "示例"
    }
  ]
}'
```

| 字段 | 类型 | 要求 | 说明 |
| --- | --- | --- | --- |
| action | string | 可选 | 可省略，系统固定为 save；传入其他值返回 400。 |
| id / revision | string / integer | 可选 | 控制已存批次需最新编号和修订号。 |
| requestId | string | 可选 | save/retry 的稳定去重标识，16–100 位字母数字横线下划线。 |
| lineId / agentId / version | string / integer | 见说明 | save 必填；固定已发布智能体版本，不修改线路原呼入绑定。 |
| recipients | array | 可选 | 最多 200000 条 {phone,name}，同时受 900000 码元正文限制；大名单使用 importId。号码归一化去重，错误拒绝整批保存。 |
| importId | string | 可选 | 完成校验且 status=ready 的本人导入任务 ID；提供时替代 recipients，完成保存后不可重复绑定批次。 |
| concurrency / reserved | integer | 可选 | 批次并发和为其他通话预留的线路并发，两者之和不超过线路上限。 |
| scheduledAt / windowStart / windowEnd | integer | 可选 | 预约 Unix 毫秒；每日北京时间分钟数，默认 09:00–18:00。 |
| confirmed | boolean | 可选 | start/resume 必须 true，确认名单授权和真实费用。 |

响应示例：
```json
{
  "batch": {
    "id": "batch_uuid",
    "status": "draft",
    "revision": 1
  }
}
```

- 已实现：原子队列占位和线路并发保护。离页执行依赖 Worker scheduled 及已部署电话媒体网关，初次启动和终态事件也会推进。未知回执不自动重拨。暂停/取消不挂断已发起电话。API 密钥撤销会阻止后续调度。

### 批量外呼 · 启动批次

`POST /v1/operations/outbound-batches.start`

权限：service, agent
费用：可能产生模型、工具或通话费用。

```sh
# cURL 7.76+；请先在服务端设置环境变量。
: "${YUNFU_BASE_URL:?请设置服务端 HTTPS 地址}"
: "${YUNFU_API_KEY:?请设置已获授权的 API 密钥}"
: "${YUNFU_IDEMPOTENCY_KEY:?请设置本次写入的唯一编号，重试沿用原编号}"
curl --fail-with-body --show-error "$YUNFU_BASE_URL/v1/operations/outbound-batches.start" \
  -H "Authorization: Bearer $YUNFU_API_KEY" \
  -H "Idempotency-Key: $YUNFU_IDEMPOTENCY_KEY" \
  -H 'Content-Type: application/json' \
  --data-binary '{
  "action": "start",
  "id": "YOUR_BATCH_ID",
  "revision": 1,
  "confirmed": true
}'
```

| 字段 | 类型 | 要求 | 说明 |
| --- | --- | --- | --- |
| id | string | 必填 | 批次 ID，最长 100 字符。取自 outbound-batches.save 响应的 batch.id，或 outbound-batches.read 列表的 batches[].id。 |
| revision | integer | 必填 | 批次当前 revision，必须是 JSON 整数且与服务端当前值完全相等。调用前用 outbound-batches.read 读取（列表 batches[].revision，或 ?id=批次ID 详情的 batch.revision）；后台调度自动暂停或完成批次时也会使它递增。 |
| confirmed | boolean | 必填 | 必须为 true，表示调用方确认名单已获得呼叫授权并接受真实通话费用；省略或为其他值返回 400。 |

响应示例：
```json
{
  "batch": {
    "id": "YOUR_BATCH_ID",
    "revision": 2,
    "name": "预约提醒",
    "status": "running",
    "lineId": "YOUR_LINE_ID",
    "orderMode": "sequential",
    "lineRevision": 1,
    "plan": {
      "type": "agent",
      "id": "YOUR_AGENT_ID",
      "version": 1,
      "name": "预约提醒智能体"
    },
    "concurrency": 1,
    "reserved": 0,
    "scheduledAt": 0,
    "schedule": {
      "enabled": true,
      "timezone": "Asia/Shanghai",
      "validFrom": "",
      "validUntil": "",
      "slots": [
        {
          "day": 1,
          "start": "09:00",
          "end": "18:00"
        }
      ]
    },
    "windowStart": 540,
    "windowEnd": 1080,
    "total": 1,
    "notice": "",
    "created": 1767225600000
  }
}
```

- 前置条件：批次状态必须是 draft 或 paused；scheduled、running、completed、canceled 返回 409“当前批次不能启动”。先用 outbound-batches.read 读取最新 revision，不一致返回 409“批次已变化，请刷新”；批次不存在返回 404。
- 仅批次原提交账号可启动：API Key 所属企业管理员必须就是创建该批次的账号，且账号授权版本未变化，否则返回 403“仅原提交人且授权未变化时可以启动，请重新创建批次”。
- 准入检查任一不满足即拒绝且不会拨号：企业未开通外呼或语音应用、或企业登录策略强制要求近期 MFA 时返回 403；拨号时段配置无效或已过截止时间返回 409；线路不存在或已删除返回 404；线路 revision 已变化、已停用、未允许呼出、未注册就绪，或“并发 + 预留”超过线路并发上限返回 422；智能体发布版本不可用或未开启语音返回 422 或 409；电话网关未部署、不可达或未就绪返回 503；企业数据任务并发已满返回 429。
- 当前不在允许拨号的时段（时段未开放或未到生效时间）不会被拒绝：批次照常进入 running 或 scheduled，由后台调度在时段开放后拨号。
- 启动与恢复不校验语音分钟或账户余额；计费准入在每通电话接入语音媒体时进行，启动成功不代表额度充足。
- 异步生效：响应只表示批次已进入拨号队列，不代表号码已拨出或接通。请求返回后服务端尽力立即触发一轮调度，其余由后台定时调度按批次并发分页拨号；用 outbound-batches.read?id=批次ID 查看 metrics 与各号码状态。
- 后台调度遇到线路掉线、执行时间截止、线路或授权变化时，会自动把批次改为 paused、写入 batch.notice 并递增 revision；排除原因后调用 outbound-batches.resume 继续。
- API Key 调用会把该密钥记为批次的拨号授权：密钥被撤销、轮换、到期或不再包含本操作后，后台调度停止拨号并自动暂停批次，需用有效密钥重新启动。
- start 与 resume 的服务端校验完全相同，二者都接受 draft 与 paused 状态的批次。
- 成功后产生 outbound.batch.changed 回调事件（data.sourceId 为批次 ID，data.revision 为新 revision）。
- 会产生真实通话费用。网关按 Idempotency-Key 缓存并重放原响应（包括 4xx）；结果未知时先读取批次状态，不要更换 Key 重复启动；修正条件后重新调用需使用新的 Idempotency-Key。

### 批量外呼 · 暂停批次

`POST /v1/operations/outbound-batches.pause`

权限：service, agent
费用：按业务权限与套餐执行。

```sh
# cURL 7.76+；请先在服务端设置环境变量。
: "${YUNFU_BASE_URL:?请设置服务端 HTTPS 地址}"
: "${YUNFU_API_KEY:?请设置已获授权的 API 密钥}"
: "${YUNFU_IDEMPOTENCY_KEY:?请设置本次写入的唯一编号，重试沿用原编号}"
curl --fail-with-body --show-error "$YUNFU_BASE_URL/v1/operations/outbound-batches.pause" \
  -H "Authorization: Bearer $YUNFU_API_KEY" \
  -H "Idempotency-Key: $YUNFU_IDEMPOTENCY_KEY" \
  -H 'Content-Type: application/json' \
  --data-binary '{
  "action": "pause",
  "id": "YOUR_BATCH_ID",
  "revision": 2
}'
```

| 字段 | 类型 | 要求 | 说明 |
| --- | --- | --- | --- |
| id | string | 必填 | 批次 ID，最长 100 字符。取自 outbound-batches.save 响应的 batch.id，或 outbound-batches.read 列表的 batches[].id。 |
| revision | integer | 必填 | 批次当前 revision，必须是 JSON 整数且与服务端当前值完全相等。调用前用 outbound-batches.read 读取（列表 batches[].revision，或 ?id=批次ID 详情的 batch.revision）；后台调度自动暂停或完成批次时也会使它递增。 |

响应示例：
```json
{
  "batch": {
    "id": "YOUR_BATCH_ID",
    "revision": 3,
    "name": "预约提醒",
    "status": "paused",
    "lineId": "YOUR_LINE_ID",
    "orderMode": "sequential",
    "lineRevision": 1,
    "plan": {
      "type": "agent",
      "id": "YOUR_AGENT_ID",
      "version": 1,
      "name": "预约提醒智能体"
    },
    "concurrency": 1,
    "reserved": 0,
    "scheduledAt": 0,
    "schedule": {
      "enabled": true,
      "timezone": "Asia/Shanghai",
      "validFrom": "",
      "validUntil": "",
      "slots": [
        {
          "day": 1,
          "start": "09:00",
          "end": "18:00"
        }
      ]
    },
    "windowStart": 540,
    "windowEnd": 1080,
    "total": 1,
    "notice": "",
    "created": 1767225600000
  }
}
```

- 前置条件：批次状态必须是 scheduled 或 running；draft、paused、completed、canceled 返回 409“当前批次不能执行此操作”。先用 outbound-batches.read 读取最新 revision，不一致返回 409“批次已变化，请刷新”；批次不存在返回 404。
- 立即生效：暂停后不再发起新呼叫；暂停瞬间已提交给电话网关的呼叫仍会继续，其结果照常记录。
- 继续拨号调用 outbound-batches.resume，需重新传 confirmed: true 并再次通过全部准入检查。
- 不要求外呼服务处于开通状态，也不占用企业数据任务并发额度：外呼被关闭或导入拥塞时仍可执行。不限原提交人，具备权限的本企业管理员 API Key 均可调用。
- 成功后产生 outbound.batch.changed 回调事件（data.sourceId 为批次 ID，data.revision 为新 revision）。
- 并发修改导致提交失败时返回 409“批次或权限已变化”；重新读取 revision 后使用新的 Idempotency-Key 再调用。

### 批量外呼 · 继续批次

`POST /v1/operations/outbound-batches.resume`

权限：service, agent
费用：可能产生模型、工具或通话费用。

```sh
# cURL 7.76+；请先在服务端设置环境变量。
: "${YUNFU_BASE_URL:?请设置服务端 HTTPS 地址}"
: "${YUNFU_API_KEY:?请设置已获授权的 API 密钥}"
: "${YUNFU_IDEMPOTENCY_KEY:?请设置本次写入的唯一编号，重试沿用原编号}"
curl --fail-with-body --show-error "$YUNFU_BASE_URL/v1/operations/outbound-batches.resume" \
  -H "Authorization: Bearer $YUNFU_API_KEY" \
  -H "Idempotency-Key: $YUNFU_IDEMPOTENCY_KEY" \
  -H 'Content-Type: application/json' \
  --data-binary '{
  "action": "resume",
  "id": "YOUR_BATCH_ID",
  "revision": 3,
  "confirmed": true
}'
```

| 字段 | 类型 | 要求 | 说明 |
| --- | --- | --- | --- |
| id | string | 必填 | 批次 ID，最长 100 字符。取自 outbound-batches.save 响应的 batch.id，或 outbound-batches.read 列表的 batches[].id。 |
| revision | integer | 必填 | 批次当前 revision，必须是 JSON 整数且与服务端当前值完全相等。调用前用 outbound-batches.read 读取（列表 batches[].revision，或 ?id=批次ID 详情的 batch.revision）；后台调度自动暂停或完成批次时也会使它递增。 |
| confirmed | boolean | 必填 | 必须为 true，表示调用方确认名单已获得呼叫授权并接受真实通话费用；省略或为其他值返回 400。 |

响应示例：
```json
{
  "batch": {
    "id": "YOUR_BATCH_ID",
    "revision": 4,
    "name": "预约提醒",
    "status": "running",
    "lineId": "YOUR_LINE_ID",
    "orderMode": "sequential",
    "lineRevision": 1,
    "plan": {
      "type": "agent",
      "id": "YOUR_AGENT_ID",
      "version": 1,
      "name": "预约提醒智能体"
    },
    "concurrency": 1,
    "reserved": 0,
    "scheduledAt": 0,
    "schedule": {
      "enabled": true,
      "timezone": "Asia/Shanghai",
      "validFrom": "",
      "validUntil": "",
      "slots": [
        {
          "day": 1,
          "start": "09:00",
          "end": "18:00"
        }
      ]
    },
    "windowStart": 540,
    "windowEnd": 1080,
    "total": 1,
    "notice": "",
    "created": 1767225600000
  }
}
```

- 前置条件：批次状态必须是 paused（draft 也被接受）；scheduled、running、completed、canceled 返回 409“当前批次不能启动”。批次被后台自动暂停后 revision 已递增，先用 outbound-batches.read 读取最新 revision 与 batch.notice，revision 不一致返回 409“批次已变化，请刷新”。
- 只继续状态仍为待拨的号码；已提交、已完成、失败、未接听或结果未知的号码不会重拨。重拨失败与未接听号码请用 outbound-batches.retry。
- 因拨号时段已过截止时间而自动暂停的批次无法恢复（返回 409“时间配置无效或已截止，请重新创建批次”）；线路配置在批次创建后被修改（线路 revision 变化）的批次同样无法恢复（返回 422）；这两种情况需用 outbound-batches.save 新建批次。线路仅掉线后重新注册就绪的，可以恢复。
- 仅批次原提交账号可启动：API Key 所属企业管理员必须就是创建该批次的账号，且账号授权版本未变化，否则返回 403“仅原提交人且授权未变化时可以启动，请重新创建批次”。
- 准入检查任一不满足即拒绝且不会拨号：企业未开通外呼或语音应用、或企业登录策略强制要求近期 MFA 时返回 403；拨号时段配置无效或已过截止时间返回 409；线路不存在或已删除返回 404；线路 revision 已变化、已停用、未允许呼出、未注册就绪，或“并发 + 预留”超过线路并发上限返回 422；智能体发布版本不可用或未开启语音返回 422 或 409；电话网关未部署、不可达或未就绪返回 503；企业数据任务并发已满返回 429。
- 当前不在允许拨号的时段（时段未开放或未到生效时间）不会被拒绝：批次照常进入 running 或 scheduled，由后台调度在时段开放后拨号。
- 启动与恢复不校验语音分钟或账户余额；计费准入在每通电话接入语音媒体时进行，启动成功不代表额度充足。
- 异步生效：响应只表示批次已进入拨号队列，不代表号码已拨出或接通。请求返回后服务端尽力立即触发一轮调度，其余由后台定时调度按批次并发分页拨号；用 outbound-batches.read?id=批次ID 查看 metrics 与各号码状态。
- 后台调度遇到线路掉线、执行时间截止、线路或授权变化时，会自动把批次改为 paused、写入 batch.notice 并递增 revision；排除原因后调用 outbound-batches.resume 继续。
- API Key 调用会把该密钥记为批次的拨号授权：密钥被撤销、轮换、到期或不再包含本操作后，后台调度停止拨号并自动暂停批次，需用有效密钥重新启动。
- start 与 resume 的服务端校验完全相同，二者都接受 draft 与 paused 状态的批次。
- 成功后产生 outbound.batch.changed 回调事件（data.sourceId 为批次 ID，data.revision 为新 revision）。
- 会产生真实通话费用。网关按 Idempotency-Key 缓存并重放原响应（包括 4xx）；结果未知时先读取批次状态，不要更换 Key 重复启动；修正条件后重新调用需使用新的 Idempotency-Key。

### 批量外呼 · 取消批次

`POST /v1/operations/outbound-batches.cancel`

权限：service, agent
费用：按业务权限与套餐执行。

```sh
# cURL 7.76+；请先在服务端设置环境变量。
: "${YUNFU_BASE_URL:?请设置服务端 HTTPS 地址}"
: "${YUNFU_API_KEY:?请设置已获授权的 API 密钥}"
: "${YUNFU_IDEMPOTENCY_KEY:?请设置本次写入的唯一编号，重试沿用原编号}"
curl --fail-with-body --show-error "$YUNFU_BASE_URL/v1/operations/outbound-batches.cancel" \
  -H "Authorization: Bearer $YUNFU_API_KEY" \
  -H "Idempotency-Key: $YUNFU_IDEMPOTENCY_KEY" \
  -H 'Content-Type: application/json' \
  --data-binary '{
  "action": "cancel",
  "id": "YOUR_BATCH_ID",
  "revision": 2
}'
```

| 字段 | 类型 | 要求 | 说明 |
| --- | --- | --- | --- |
| id | string | 必填 | 批次 ID，最长 100 字符。取自 outbound-batches.save 响应的 batch.id，或 outbound-batches.read 列表的 batches[].id。 |
| revision | integer | 必填 | 批次当前 revision，必须是 JSON 整数且与服务端当前值完全相等。调用前用 outbound-batches.read 读取（列表 batches[].revision，或 ?id=批次ID 详情的 batch.revision）；后台调度自动暂停或完成批次时也会使它递增。 |

响应示例：
```json
{
  "batch": {
    "id": "YOUR_BATCH_ID",
    "revision": 3,
    "name": "预约提醒",
    "status": "canceled",
    "lineId": "YOUR_LINE_ID",
    "orderMode": "sequential",
    "lineRevision": 1,
    "plan": {
      "type": "agent",
      "id": "YOUR_AGENT_ID",
      "version": 1,
      "name": "预约提醒智能体"
    },
    "concurrency": 1,
    "reserved": 0,
    "scheduledAt": 0,
    "schedule": {
      "enabled": true,
      "timezone": "Asia/Shanghai",
      "validFrom": "",
      "validUntil": "",
      "slots": [
        {
          "day": 1,
          "start": "09:00",
          "end": "18:00"
        }
      ]
    },
    "windowStart": 540,
    "windowEnd": 1080,
    "total": 1,
    "notice": "",
    "created": 1767225600000
  }
}
```

- 前置条件：批次状态为 draft、scheduled、running 或 paused；completed、canceled 返回 409“当前批次不能执行此操作”。先用 outbound-batches.read 读取最新 revision，不一致返回 409“批次已变化，请刷新”；批次不存在返回 404。
- 立即生效且不可恢复：已取消的批次调用 start 或 resume 返回 409。取消瞬间已提交给电话网关的呼叫仍会继续，其结果照常记录。
- 取消后可用 outbound-batches.retry 为已确认失败或未接听的号码创建新批次；因取消而未拨出的号码不在重试范围内，需用 outbound-batches.save 重新提交。
- 不要求外呼服务处于开通状态，也不占用企业数据任务并发额度：外呼被关闭或导入拥塞时仍可执行。不限原提交人，具备权限的本企业管理员 API Key 均可调用。
- 成功后产生 outbound.batch.changed 回调事件（data.sourceId 为批次 ID，data.revision 为新 revision）。
- 并发修改导致提交失败时返回 409“批次或权限已变化”；重新读取 revision 后使用新的 Idempotency-Key 再调用。

### 批量外呼 · 为失败号码新建重试批次

`POST /v1/operations/outbound-batches.retry`

权限：service, agent
费用：按业务权限与套餐执行。

```sh
# cURL 7.76+；请先在服务端设置环境变量。
: "${YUNFU_BASE_URL:?请设置服务端 HTTPS 地址}"
: "${YUNFU_API_KEY:?请设置已获授权的 API 密钥}"
: "${YUNFU_IDEMPOTENCY_KEY:?请设置本次写入的唯一编号，重试沿用原编号}"
curl --fail-with-body --show-error "$YUNFU_BASE_URL/v1/operations/outbound-batches.retry" \
  -H "Authorization: Bearer $YUNFU_API_KEY" \
  -H "Idempotency-Key: $YUNFU_IDEMPOTENCY_KEY" \
  -H 'Content-Type: application/json' \
  --data-binary '{
  "action": "retry",
  "id": "YOUR_BATCH_ID",
  "revision": 5,
  "requestId": "YOUR_STABLE_REQUEST_ID"
}'
```

| 字段 | 类型 | 要求 | 说明 |
| --- | --- | --- | --- |
| id | string | 必填 | 源批次 ID，最长 100 字符。取自 outbound-batches.read 列表的 batches[].id。 |
| revision | integer | 必填 | 源批次当前 revision，必须是 JSON 整数且与服务端当前值完全相等；用 outbound-batches.read 读取。 |
| requestId | string | 必填 | 新批次的稳定业务去重标识，16–100 位字母、数字、下划线或连字符。同一 requestId 且待重试号码与配置未变时返回已创建的批次（duplicate: true）；内容不同返回 409。 |

响应示例：
```json
{
  "batch": {
    "id": "YOUR_NEW_BATCH_ID",
    "revision": 1,
    "name": "预约提醒 · 重试",
    "status": "draft",
    "lineId": "YOUR_LINE_ID",
    "orderMode": "sequential",
    "lineRevision": 1,
    "plan": {
      "type": "agent",
      "id": "YOUR_AGENT_ID",
      "version": 1,
      "name": "预约提醒智能体"
    },
    "concurrency": 1,
    "reserved": 0,
    "scheduledAt": 0,
    "schedule": {
      "enabled": true,
      "timezone": "Asia/Shanghai",
      "validFrom": "",
      "validUntil": "",
      "slots": [
        {
          "day": 1,
          "start": "09:00",
          "end": "18:00"
        }
      ]
    },
    "windowStart": 540,
    "windowEnd": 1080,
    "total": 1,
    "notice": "",
    "created": 1767225600000
  },
  "duplicates": 0
}
```

- 前置条件：源批次状态必须是 paused、completed 或 canceled，且 revision 与当前值相等；运行中或已预约的批次需先调用 outbound-batches.pause。状态不符与 revision 不一致返回同一个 409“请先暂停或等待批次结束”，遇到时先重新读取批次。
- 重试范围：只复制最近一次呼叫结果为 failed 或 no_answer 的号码；结果未知（unknown）、已完成、未拨出、已取消或被黑名单拦截的号码不会进入新批次。没有符合条件的号码返回 400“没有已确认失败或未接听的号码；未知结果不能重拨”。
- 没有单独的重试号码数量上限，也不记录重试次数：每次使用新的 requestId 调用都会新建一个草稿批次，同一批失败号码可能因此进入多个批次，调用方需自行避免重复重试。企业未完成批次（draft、scheduled、running、paused）达到 100 个或线路已停用时返回 409。
- 新批次沿用源批次的线路、智能体及其发布版本、并发、预留、号码顺序与拨号时段，名称为源批次名称加“ · 重试”（截断到 80 字符）；不沿用预约时间，启动后立即进入拨号队列。
- 需要外呼服务处于开通状态（否则返回 403）。线路不存在或已删除返回 404；线路未允许呼出或“并发 + 预留”超过线路并发上限返回 422；智能体发布版本不可用返回 422；号码与线路拨号格式不匹配返回 422；requestId 格式不符返回 400。
- 若源批次的拨号时段已过截止时间（schedule.validUntil），重试批次会沿用该时段，启动时返回 409“时间配置无效或已截止”；此时改用 outbound-batches.save 新建批次。
- 成功新建后产生 outbound.batch.created 回调事件（data.sourceId 为新批次 ID）。
- 网关按 Idempotency-Key 缓存并重放原响应（包括 4xx）；修正条件后重新调用需使用新的 Idempotency-Key，requestId 可保持不变。

### 批量外呼 · 开始导入

`POST /v1/operations/outbound-batches.importStart`

权限：service, agent
费用：按业务权限与套餐执行。

```sh
# cURL 7.76+；请先在服务端设置环境变量。
: "${YUNFU_BASE_URL:?请设置服务端 HTTPS 地址}"
: "${YUNFU_API_KEY:?请设置已获授权的 API 密钥}"
: "${YUNFU_IDEMPOTENCY_KEY:?请设置本次写入的唯一编号，重试沿用原编号}"
curl --fail-with-body --show-error "$YUNFU_BASE_URL/v1/operations/outbound-batches.importStart" \
  -H "Authorization: Bearer $YUNFU_API_KEY" \
  -H "Idempotency-Key: $YUNFU_IDEMPOTENCY_KEY" \
  -H 'Content-Type: application/json' \
  --data-binary '{
  "action": "importStart",
  "requestId": "import_example_request_1",
  "source": "generic",
  "fileName": "contacts.csv"
}'
```

| 字段 | 类型 | 要求 | 说明 |
| --- | --- | --- | --- |
| action | importStart | 可选 | 可省略，系统固定为 importStart；传入其他值返回 400。 |
| requestId | string | 必填 | 稳定业务去重标识，16–100 位字母数字横线下划线；同一标识不能改变来源或文件名。 |
| source | string | 必填 | generic / qichacha / tianyancha / aiqicha。 |
| fileName | string | 可选 | 文件名，可选，最多 160 字符。 |

响应示例：
```json
{
  "importJob": {
    "id": "import_example",
    "status": "uploading",
    "processed": 1,
    "accepted": 1,
    "duplicates": 0,
    "errors": 0,
    "errorSample": []
  }
}
```

- 每企业最多 5 个正在上传的任务，每批最多处理 200000 行；调用者须具有已开通外呼服务及企业管理员本人的服务、智能体权限。
- 只接收 JSON 数据，不接收文件上传或远程 URL，不会发起呼叫。外部 Skill 应在本地解析文件，逐块提交，再完成校验和保存草稿批次。
- complete 无有效号码时返回 failed，否则 ready。已完成的本人任务可再次查询；上传结束后不能继续提交。所有写入在提交时重新校验密钥及账号权限。
- 分块请求结果未知时保持同一 Idempotency-Key 和正文重试；409 先核实任务状态，不换编号重复上传。

### 批量外呼 · 上传导入分块

`POST /v1/operations/outbound-batches.importChunk`

权限：service, agent
费用：按业务权限与套餐执行。

```sh
# cURL 7.76+；请先在服务端设置环境变量。
: "${YUNFU_BASE_URL:?请设置服务端 HTTPS 地址}"
: "${YUNFU_API_KEY:?请设置已获授权的 API 密钥}"
: "${YUNFU_IDEMPOTENCY_KEY:?请设置本次写入的唯一编号，重试沿用原编号}"
curl --fail-with-body --show-error "$YUNFU_BASE_URL/v1/operations/outbound-batches.importChunk" \
  -H "Authorization: Bearer $YUNFU_API_KEY" \
  -H "Idempotency-Key: $YUNFU_IDEMPOTENCY_KEY" \
  -H 'Content-Type: application/json' \
  --data-binary '{
  "action": "importChunk",
  "importId": "import_example",
  "rows": [
    {
      "phone": "+8613800138000",
      "name": "示例客户"
    }
  ]
}'
```

| 字段 | 类型 | 要求 | 说明 |
| --- | --- | --- | --- |
| action | importChunk | 可选 | 可省略，系统固定为 importChunk；传入其他值返回 400。 |
| importId | string | 必填 | 本企业原提交人创建且账号 epoch 未变化的导入任务 ID，最多 100 字符。 |
| rows | array | 必填 | 1–2000 行 {phone,name}；手机号必须字符串，姓名可省略且最多 80 字。通过 Bearer 网关建议每块最多 500 行，受 150000 码元正文限制。 |

响应示例：
```json
{
  "importJob": {
    "id": "import_example",
    "status": "uploading",
    "processed": 1,
    "accepted": 1,
    "duplicates": 0,
    "errors": 0,
    "errorSample": []
  }
}
```

- 每企业最多 5 个正在上传的任务，每批最多处理 200000 行；调用者须具有已开通外呼服务及企业管理员本人的服务、智能体权限。
- 只接收 JSON 数据，不接收文件上传或远程 URL，不会发起呼叫。外部 Skill 应在本地解析文件，逐块提交，再完成校验和保存草稿批次。
- complete 无有效号码时返回 failed，否则 ready。已完成的本人任务可再次查询；上传结束后不能继续提交。所有写入在提交时重新校验密钥及账号权限。
- 分块请求结果未知时保持同一 Idempotency-Key 和正文重试；409 先核实任务状态，不换编号重复上传。

### 批量外呼 · 完成导入

`POST /v1/operations/outbound-batches.importComplete`

权限：service, agent
费用：按业务权限与套餐执行。

```sh
# cURL 7.76+；请先在服务端设置环境变量。
: "${YUNFU_BASE_URL:?请设置服务端 HTTPS 地址}"
: "${YUNFU_API_KEY:?请设置已获授权的 API 密钥}"
: "${YUNFU_IDEMPOTENCY_KEY:?请设置本次写入的唯一编号，重试沿用原编号}"
curl --fail-with-body --show-error "$YUNFU_BASE_URL/v1/operations/outbound-batches.importComplete" \
  -H "Authorization: Bearer $YUNFU_API_KEY" \
  -H "Idempotency-Key: $YUNFU_IDEMPOTENCY_KEY" \
  -H 'Content-Type: application/json' \
  --data-binary '{
  "action": "importComplete",
  "importId": "import_example"
}'
```

| 字段 | 类型 | 要求 | 说明 |
| --- | --- | --- | --- |
| action | importComplete | 可选 | 可省略，系统固定为 importComplete；传入其他值返回 400。 |
| importId | string | 必填 | 本企业原提交人创建且账号 epoch 未变化的导入任务 ID，最多 100 字符。 |

响应示例：
```json
{
  "importJob": {
    "id": "import_example",
    "status": "ready",
    "processed": 1,
    "accepted": 1,
    "duplicates": 0,
    "errors": 0,
    "errorSample": []
  }
}
```

- 每企业最多 5 个正在上传的任务，每批最多处理 200000 行；调用者须具有已开通外呼服务及企业管理员本人的服务、智能体权限。
- 只接收 JSON 数据，不接收文件上传或远程 URL，不会发起呼叫。外部 Skill 应在本地解析文件，逐块提交，再完成校验和保存草稿批次。
- complete 无有效号码时返回 failed，否则 ready。已完成的本人任务可再次查询；上传结束后不能继续提交。所有写入在提交时重新校验密钥及账号权限。
- 分块请求结果未知时保持同一 Idempotency-Key 和正文重试；409 先核实任务状态，不换编号重复上传。

### 批量外呼 · 取消导入

`POST /v1/operations/outbound-batches.importCancel`

权限：service, agent
费用：按业务权限与套餐执行。

```sh
# cURL 7.76+；请先在服务端设置环境变量。
: "${YUNFU_BASE_URL:?请设置服务端 HTTPS 地址}"
: "${YUNFU_API_KEY:?请设置已获授权的 API 密钥}"
: "${YUNFU_IDEMPOTENCY_KEY:?请设置本次写入的唯一编号，重试沿用原编号}"
curl --fail-with-body --show-error "$YUNFU_BASE_URL/v1/operations/outbound-batches.importCancel" \
  -H "Authorization: Bearer $YUNFU_API_KEY" \
  -H "Idempotency-Key: $YUNFU_IDEMPOTENCY_KEY" \
  -H 'Content-Type: application/json' \
  --data-binary '{
  "action": "importCancel",
  "importId": "import_example"
}'
```

| 字段 | 类型 | 要求 | 说明 |
| --- | --- | --- | --- |
| action | importCancel | 可选 | 可省略，系统固定为 importCancel；传入其他值返回 400。 |
| importId | string | 必填 | 本企业原提交人创建且账号 epoch 未变化的导入任务 ID，最多 100 字符。 |

响应示例：
```json
{
  "importJob": {
    "id": "import_example",
    "status": "canceled",
    "processed": 1,
    "accepted": 1,
    "duplicates": 0,
    "errors": 0,
    "errorSample": []
  }
}
```

- 每企业最多 5 个正在上传的任务，每批最多处理 200000 行；调用者须具有已开通外呼服务及企业管理员本人的服务、智能体权限。
- 只接收 JSON 数据，不接收文件上传或远程 URL，不会发起呼叫。外部 Skill 应在本地解析文件，逐块提交，再完成校验和保存草稿批次。
- complete 无有效号码时返回 failed，否则 ready。已完成的本人任务可再次查询；上传结束后不能继续提交。所有写入在提交时重新校验密钥及账号权限。
- 分块请求结果未知时保持同一 Idempotency-Key 和正文重试；409 先核实任务状态，不换编号重复上传。

### 读取账单与消耗

`GET /v1/operations/billing.read`

权限：billing
费用：按业务权限与套餐执行。

```sh
# cURL 7.76+；请先在服务端设置环境变量。
: "${YUNFU_BASE_URL:?请设置服务端 HTTPS 地址}"
: "${YUNFU_API_KEY:?请设置已获授权的 API 密钥}"
curl --fail-with-body --show-error "$YUNFU_BASE_URL/v1/operations/billing.read?start=2026-09-01&end=2026-09-18&page=1" \
  -H "Authorization: Bearer $YUNFU_API_KEY"
```

| 字段 | 类型 | 要求 | 说明 |
| --- | --- | --- | --- |
| start / end | YYYY-MM-DD | 可选 | 上海时区日期，最多 366 天；默认当月至今。 |
| orderId | string | 可选 | 订单筛选，最多 100 字符。 |
| page | integer | 可选 | 1 至 10000，固定每页 20。 |
| pagination / cursor | string | 可选 | 大账单可传 pagination=cursor；使用返回的 nextCursor 获取下一页。修改企业、日期或订单后从第一页重新读取。 |
| recordId / kind | string | 可选 | 指定原始记录与类型，返回单次会话费用。 |

响应示例：
```json
{
  "summary": {},
  "daily": [],
  "entries": [],
  "orders": [],
  "page": 1,
  "pageSize": 20,
  "timezone": "Asia/Shanghai"
}
```

- 三段式分钟套餐和端到端余额消耗分开记账；未结算不是最终费用。

### 读取服务运营分析

`GET /v1/operations/service-analytics.read`

权限：reports, service
费用：按业务权限与套餐执行。

```sh
# cURL 7.76+；请先在服务端设置环境变量。
: "${YUNFU_BASE_URL:?请设置服务端 HTTPS 地址}"
: "${YUNFU_API_KEY:?请设置已获授权的 API 密钥}"
curl --fail-with-body --show-error "$YUNFU_BASE_URL/v1/operations/service-analytics.read?reportVersion=2&filter=%7B%22timeMode%22%3A%22range%22%2C%22start%22%3A%222026-11-01%22%2C%22end%22%3A%222026-11-07%22%7D" \
  -H "Authorization: Bearer $YUNFU_API_KEY"
```

| 字段 | 类型 | 要求 | 说明 |
| --- | --- | --- | --- |
| reportVersion (query) | string | 可选 | 传 2 使用报表模式（推荐，支持日期范围）。省略时为快照模式，此时除 fresh 外的其余查询参数都不生效。 |
| filter (query) | string | 条件必填：reportVersion=2 | URL 编码后的 JSON 对象，编码前最多 8000 个字符，可只写需要的键。timeMode：all（默认，全部时间）、range（按 start、end），unknown 与 partial 只统计没有记录时间的数据；start、end：timeMode 为 range 时的起止时间，格式为 YYYY-MM-DD、YYYY-MM-DDTHH:mm[:ss] 或带 Z/±hh:mm 的 ISO 时间；dataset：service（默认）、simulation、test 或 all；recordScope：service（默认）、test 或 all；reception：all、human 或 ai；receptionMode：all、pure-ai、pure-human 或 mixed；channel、sourcePlatform、sourceChannel、sourceEntry、unit、owner、handling、lifecycle：默认 all；query：关键字，最多 200 个字符。其余值每个最多 120 个字符。 |
| reportView (query) | string | 可选 | 仅报表模式。要额外计算的视图：overview（默认，返回总览统计与筛选项）、source（来源统计，可用 sourceChannel 限定渠道）、work（工作量，增加 report.work）、diagnostics（接待诊断，增加 report.diagnostics）、custom（自定义图表，增加 report.custom）或 statistic（单项指标明细，增加 report.statistic）。 |
| agentId (query) | string | 可选 | 仅报表模式。只统计该智能体的会话，最多 120 个字符；省略或传 all 表示全部智能体。 |
| page (query) | integer | 可选 | 仅报表模式。明细分页的页码，1–1000000，默认 1；每页固定 100 行。 |
| cursor (query) | string | 可选 | 仅报表模式。上一页明细返回的 nextCursor，最多 2000 个字符。 |
| diagnostic (query) | string | 可选 | 仅 reportView=diagnostics。只保留某一类诊断：all（默认）、reply、handoff、delivery 或 business。 |
| detailKind (query) | string | 可选 | 仅 reportView=work。要展开明细的分组类型：daily、staff 或 tickets，与 detailKey 一起使用。 |
| detailKey (query) | string | 可选 | 仅 reportView=work。要展开的分组编号，取 report.work 中对应分组行的 id，最多 200 个字符。 |
| cards (query) | string | 可选 | 仅 reportView=custom。URL 编码后的 JSON 数组，最多 12 张图表卡片；每张卡片含 id（1–80 位字母、数字、下划线或连字符，不可重复）、chart（line、area、bar、donut、bubble、heatmap、table）、dimension（day、week、month、hour、platform、channel、entry、owner、unit、handling、lifecycle、content、sender）和 metric（如 conversations、closeRate、response、messages、aiShare）。缺少有效 id 的卡片会被忽略，不兼容的组合会被自动调整。 |
| statisticLabel (query) | string | 可选 | 仅 reportView=statistic。要查看明细的指标名称，最多 200 个字符。 |
| statisticScope (query) | string | 可选 | 仅 reportView=statistic。URL 编码后的 JSON 对象，编码前最多 2000 个字符，用于把明细限定到某一天（day，YYYY-MM-DD）、某个会话（conversationId）或某类角色（role：customer、ai 或 agent）。 |
| fresh (query) | string | 可选 | 两种模式均可传 1，跳过已保存的统计快照。 |

响应示例：
```json
{
  "state": {
    "revision": 12,
    "conversations": [],
    "issues": [],
    "tasks": [],
    "tickets": [],
    "members": [],
    "calls": []
  },
  "report": {
    "analytics": {
      "total": 128,
      "open": 9,
      "closed": 119,
      "closeRate": 0.93,
      "aiReplyShare": 0.71,
      "aiResolutionRate": 0.64,
      "resolveRate": 0.88,
      "issueCount": 40,
      "ticketCount": 6,
      "taskCount": 3
    },
    "filterOptions": {
      "platforms": [],
      "connections": [],
      "entries": [],
      "owners": [],
      "channels": [],
      "units": [],
      "agents": []
    }
  },
  "appliedFilter": {
    "query": "",
    "channel": "all",
    "sourcePlatform": "all",
    "sourceChannel": "all",
    "sourceEntry": "all",
    "dataset": "service",
    "recordScope": "service",
    "unit": "all",
    "owner": "all",
    "handling": "all",
    "reception": "all",
    "receptionMode": "all",
    "lifecycle": "all",
    "start": "2026-11-01",
    "end": "2026-11-07",
    "timeMode": "range"
  },
  "agentId": "",
  "statistics": {
    "mode": "paged-exact",
    "generatedAt": 1794787200000,
    "refreshSeconds": 3600,
    "channelCacheSeconds": 3600,
    "fresh": false
  }
}
```

- 前置条件：密钥需同时具备 reports 与 service 权限。时间范围只在报表模式下可用：传 reportVersion=2，并在 filter 中设置 timeMode 为 range 以及 start、end；起始晚于结束或日期无法解析返回 400“请选择有效日期”。快照模式没有时间筛选。
- 数据新鲜度按企业时区计算。当前汇总最多复用 10 分钟，已结束日期的汇总最多复用 1 小时。诊断、指标和工作明细按请求计算。旧版工作区快照最多复用 20 秒。按 statistics.refreshSeconds 轮询，需最新数据时传 fresh=1。
- 容量上限：报表模式单次最长计算 90 秒，report 序列化后不超过约 419 万个字符，超出返回 503（“统计范围过大”“统计结果过大”或“统计分组过多”），需缩小日期或筛选范围。快照模式上限为 2,000 个会话、20,000 条消息、序列化后约 419 万个字符和 2 秒处理时间，超出返回 503 且不返回不完整数据，此时请改用报表模式或 conversations.read 分页读取明细。
- 频率限制：服务端同时最多处理 4 个统计读取，超出返回 429，响应体含 retryAfter: 60 并带 Retry-After: 60；503 同样带 Retry-After: 60。此外仍受密钥每分钟限额约束。整个查询串不能超过 8000 个字符。
- 错误：400 报表模式缺少 filter（“请选择统计范围”）、参数重复出现或超长、JSON 无法解析（“统计参数无效”）、筛选值不在允许范围（“统计筛选无效”）、reportView 无效（“统计视图无效”）、diagnostic、detailKind 或 page 无效（“统计明细范围无效”）；403 密钥缺少接待权限，或计算期间权限发生变化（“统计权限已变化，请刷新重试”）。
- API Key 调用的限制：不带时区的 start、end 以及按天分组固定按 Asia/Shanghai 时区解释，需要其他时区时请传带 Z 或 ±hh:mm 的时间。企业开启手机号隐私保护后，API Key 读到的手机号始终是脱敏值。

### 读取质检复核记录

`GET /v1/operations/quality-reviews.read`

权限：reports, service
费用：按业务权限与套餐执行。

```sh
# cURL 7.76+；请先在服务端设置环境变量。
: "${YUNFU_BASE_URL:?请设置服务端 HTTPS 地址}"
: "${YUNFU_API_KEY:?请设置已获授权的 API 密钥}"
curl --fail-with-body --show-error "$YUNFU_BASE_URL/v1/operations/quality-reviews.read" \
  -H "Authorization: Bearer $YUNFU_API_KEY"
```

| 字段 | 类型 | 要求 | 说明 |
| --- | --- | --- | --- |
| trainingTask | string | 可选 | 可选：读取本企业训练任务详情，还需team权限；响应改为{task}。 |

响应示例：
```json
{
  "items": [],
  "conversations": [],
  "trainingTasks": [],
  "knowledgeDocuments": [],
  "canManage": true
}
```

- 同时需要service与reports权限，会话来源受当前可见范围约束。
- 关联训练资料还需要team，知识资料需要knowledge；GO_API_URL远程工作台尚未启用复核案例，返回503。

### 读取回调订阅

`GET /v1/operations/callbacks.read`

权限：applications, agent, service
费用：按业务权限与套餐执行。

```sh
# cURL 7.76+；请先在服务端设置环境变量。
: "${YUNFU_BASE_URL:?请设置服务端 HTTPS 地址}"
: "${YUNFU_API_KEY:?请设置已获授权的 API 密钥}"
curl --fail-with-body --show-error "$YUNFU_BASE_URL/v1/operations/callbacks.read" \
  -H "Authorization: Bearer $YUNFU_API_KEY"
```

响应示例：
```json
{
  "subscriptions": [],
  "deliveries": [],
  "events": {
    "outbound.batch.created": "外呼批次草稿已创建",
    "outbound.batch.changed": "外呼批次控制状态已变更",
    "outbound.batch.completed": "外呼批次全部号码已结束",
    "service.config.changed": "智能体或渠道配置已更新",
    "agent.published": "智能体已发布",
    "workflow.saved": "工作流草稿已保存",
    "workflow.published": "工作流已发布",
    "service.state.changed": "客服会话或工单已更新",
    "analysis.completed": "服务总结已完成",
    "analysis.failed": "服务总结失败",
    "api.request.completed": "API 请求已处理（不代表后台任务完成）",
    "api.request.failed": "API 请求被业务接口拒绝",
    "memory.linked": "记忆关联已登记",
    "memory.invalidated": "记忆关联已失效",
    "build.task.created": "构建任务已创建",
    "build.task.review": "构建计划待确认",
    "build.task.running": "构建开始执行",
    "build.task.approval": "构建等待单次授权",
    "build.task.step_completed": "构建步骤已完成",
    "build.task.paused": "构建已暂停",
    "build.task.failed": "构建执行受阻",
    "build.task.completed": "构建已完成",
    "build.task.cancelled": "构建已取消",
    "build.task.planning": "构建重新规划"
  }
}
```

- 仅订阅本人构建任务事件，不等于企业全部业务变更事件总线。

### 回调订阅 · 保存

`POST /v1/operations/callbacks.save`

权限：applications, agent, service
费用：按业务权限与套餐执行。

```sh
# cURL 7.76+；请先在服务端设置环境变量。
: "${YUNFU_BASE_URL:?请设置服务端 HTTPS 地址}"
: "${YUNFU_API_KEY:?请设置已获授权的 API 密钥}"
: "${YUNFU_IDEMPOTENCY_KEY:?请设置本次写入的唯一编号，重试沿用原编号}"
curl --fail-with-body --show-error "$YUNFU_BASE_URL/v1/operations/callbacks.save" \
  -H "Authorization: Bearer $YUNFU_API_KEY" \
  -H "Idempotency-Key: $YUNFU_IDEMPOTENCY_KEY" \
  -H 'Content-Type: application/json' \
  --data-binary '{
  "action": "save",
  "name": "构建进度",
  "endpoint": "https://receiver.example.com/events",
  "events": [
    "build.task.completed",
    "build.task.failed"
  ]
}'
```

| 字段 | 类型 | 要求 | 说明 |
| --- | --- | --- | --- |
| action | save | 可选 | 可省略，系统固定为 save；传入其他值返回 400。 |
| name | string | 必填 | 名称最多 80 字符。 |
| endpoint | https URL | 见说明 | 新建必填；更新留空保留原地址，替换地址会轮换签名密钥。 |
| events | string[] | 必填 | 非空且不重复，限注册表内事件。 |
| id / revision | string / integer | 见说明 | 更新时均必填；最多 5 个订阅。 |

响应示例：
```json
{
  "id": "subscription_example",
  "revision": 1,
  "enabled": false,
  "secret": "whsec_example_only"
}
```

- 仅公开 HTTPS 默认端口，拒绝私网、凭据 URL、片段及重定向；每次发送重新校验 DNS。
- sha256=hex(HMAC-SHA256(secret, timestamp + "." + raw_body))；timestamp 为 Unix 秒。接收方应以常量时间比较签名并限制 ±300 秒重放窗口。
- 同事务事件队列，默认本人范围，可显式选择本企业事件。涵盖构建、记忆、配置、发布、工作流、服务状态、总结和 API 结果；仅登记的事件有效。最多自动尝试 5 次，间隔 30 秒、2 分钟、10 分钟、1 小时，依赖原生 scheduled。人工最多 10 次；可能重复或乱序，按事件 ID 去重；停用或变更不补发历史。

### 回调订阅 · 启用或停用

`POST /v1/operations/callbacks.toggle`

权限：applications, agent, service
费用：按业务权限与套餐执行。

```sh
# cURL 7.76+；请先在服务端设置环境变量。
: "${YUNFU_BASE_URL:?请设置服务端 HTTPS 地址}"
: "${YUNFU_API_KEY:?请设置已获授权的 API 密钥}"
: "${YUNFU_IDEMPOTENCY_KEY:?请设置本次写入的唯一编号，重试沿用原编号}"
curl --fail-with-body --show-error "$YUNFU_BASE_URL/v1/operations/callbacks.toggle" \
  -H "Authorization: Bearer $YUNFU_API_KEY" \
  -H "Idempotency-Key: $YUNFU_IDEMPOTENCY_KEY" \
  -H 'Content-Type: application/json' \
  --data-binary '{
  "action": "toggle",
  "id": "YOUR_SUBSCRIPTION_ID",
  "revision": 1,
  "enabled": true
}'
```

| 字段 | 类型 | 要求 | 说明 |
| --- | --- | --- | --- |
| id | string | 必填 | 订阅 ID，最长 100 字符。取自 callbacks.save 响应的 id，或 callbacks.read 的 subscriptions[].id；只能操作 API Key 所属管理员账号名下的订阅。 |
| revision | integer | 必填 | 订阅当前 revision，必须是 JSON 整数且与服务端当前值完全相等。取自 callbacks.save 响应的 revision，或 callbacks.read 的 subscriptions[].revision。 |
| enabled | boolean | 必填 | true 启用，false 停用。必须是 JSON 布尔值，否则返回 400“启用状态无效”。 |

响应示例：
```json
{
  "ok": true,
  "revision": 2
}
```

- 前置条件：先用 callbacks.read 读取订阅的最新 revision。订阅不存在或不属于 API Key 所属管理员账号返回 404；revision 不一致返回 409“订阅版本已变化，请刷新”。
- 启用（enabled: true）要求订阅未被删除，且调用方与订阅所属管理员账号都具备订阅内每个事件所需的权限（api.* 事件需 applications；outbound.*、memory.*、analysis.* 与 service.state.changed 需 service；其余事件需 agent），否则返回 403“订阅已删除或事件权限不足”。
- 立即生效。只投递启用之后发生的事件；停用期间发生的事件不会入队，也不会在重新启用后补发。
- 每次启停都会使订阅 revision 加 1：此前尚未送达（pending、retry）的投递会在下一轮调度被取消（status=cancelled），此前 dead 的投递也不能再用 callbacks.retry 重试。
- 重复提交当前已有的状态（例如对已启用的订阅再次传 enabled: true）不会报错，但同样使 revision 加 1 并取消未送达的投递。
- callbacks.save 与 callbacks.rotate 成功后订阅都处于停用状态，需调用本操作重新启用。
- API Key 所属账号必须是企业管理员并具备 applications 与 agent 权限，否则返回 403。回调管理操作本身不产生 api.request.completed / api.request.failed 回调事件。

### 回调订阅 · 测试

`POST /v1/operations/callbacks.test`

权限：applications, agent, service
费用：可能产生模型、工具或通话费用。

```sh
# cURL 7.76+；请先在服务端设置环境变量。
: "${YUNFU_BASE_URL:?请设置服务端 HTTPS 地址}"
: "${YUNFU_API_KEY:?请设置已获授权的 API 密钥}"
: "${YUNFU_IDEMPOTENCY_KEY:?请设置本次写入的唯一编号，重试沿用原编号}"
curl --fail-with-body --show-error "$YUNFU_BASE_URL/v1/operations/callbacks.test" \
  -H "Authorization: Bearer $YUNFU_API_KEY" \
  -H "Idempotency-Key: $YUNFU_IDEMPOTENCY_KEY" \
  -H 'Content-Type: application/json' \
  --data-binary '{
  "action": "test",
  "id": "subscription_example",
  "revision": 2
}'
```

| 字段 | 类型 | 要求 | 说明 |
| --- | --- | --- | --- |
| action | toggle \| test \| retry \| dispatch | 可选 | 可省略，系统固定为 test；传入其他值返回 400。 |
| id / revision | string / integer | 可选 | 其余操作必须携带最新订阅版本。 |
| enabled | boolean | 见说明 | toggle 必填。 |
| deliveryId | string | 见说明 | retry 必填，只允许 dead 且尝试次数少于 10。 |

响应示例：
```json
{
  "eventId": "test:example"
}
```

- 调用 action=test 会向外部接收地址发送真实 webhook.test 验证事件，每人每分钟最多 10 次。
- 最多自动尝试 5 次，后续可人工重试至总计 10 次；同一事件 ID 去重，不保证顺序或恰好一次。
- 自动重试需要部署原生 scheduled 触发器；本地预览无常驻定时器，刷新不会投递。

### 回调订阅 · 重试失败投递

`POST /v1/operations/callbacks.retry`

权限：applications, agent, service
费用：按业务权限与套餐执行。

```sh
# cURL 7.76+；请先在服务端设置环境变量。
: "${YUNFU_BASE_URL:?请设置服务端 HTTPS 地址}"
: "${YUNFU_API_KEY:?请设置已获授权的 API 密钥}"
: "${YUNFU_IDEMPOTENCY_KEY:?请设置本次写入的唯一编号，重试沿用原编号}"
curl --fail-with-body --show-error "$YUNFU_BASE_URL/v1/operations/callbacks.retry" \
  -H "Authorization: Bearer $YUNFU_API_KEY" \
  -H "Idempotency-Key: $YUNFU_IDEMPOTENCY_KEY" \
  -H 'Content-Type: application/json' \
  --data-binary '{
  "action": "retry",
  "id": "YOUR_SUBSCRIPTION_ID",
  "revision": 2,
  "deliveryId": "YOUR_DELIVERY_ID"
}'
```

| 字段 | 类型 | 要求 | 说明 |
| --- | --- | --- | --- |
| id | string | 必填 | 订阅 ID，最长 100 字符。取自 callbacks.save 响应的 id，或 callbacks.read 的 subscriptions[].id；只能操作 API Key 所属管理员账号名下的订阅。 |
| revision | integer | 必填 | 订阅当前 revision，必须是 JSON 整数且与服务端当前值完全相等。取自 callbacks.save 响应的 revision，或 callbacks.read 的 subscriptions[].revision。 |
| deliveryId | string | 必填 | 要重试的投递记录 ID，最长 200 字符。取自 callbacks.read 的 deliveries[].id，且该记录的 subscriptionId 必须等于本请求的 id。 |

响应示例：
```json
{
  "ok": true
}
```

- 前置条件：先用 callbacks.read 读取订阅的最新 revision。订阅不存在或不属于 API Key 所属管理员账号返回 404；revision 不一致返回 409“订阅版本已变化，请刷新”。
- 订阅必须处于启用状态，且启用后所属账号的授权版本未变化，否则返回 409“请重新确认并启用订阅”。
- 只能重试 status=dead 的投递（自动尝试 5 次均未成功），并且该投递生成后订阅 revision 未变化（期间没有保存、启停或轮换）、累计尝试次数 attempts 小于 10；不满足任一条件返回 409“仅可重试配置未变化且少于 10 次的失败投递”。pending、retry、sending、delivered、cancelled 状态均不可重试。
- 每次调用只增加 1 次投递尝试：再次失败后投递回到 dead，可继续调用，直到累计 10 次（自动 5 次加人工最多 5 次）。
- 异步生效：投递被置为 pending 并立即到期，由后台回调队列发送。用 callbacks.read 的 deliveries[] 查看 status、attempts、httpStatus 与 message，用 callbacks.read?delivery=投递ID 查看每次尝试的记录。
- 重试沿用原事件 ID 与投递 ID（X-Yunfu-Event-Id、X-Yunfu-Delivery-Id 不变），时间戳与签名重新生成；接收方应按事件 ID 去重。
- callbacks.read 只返回最近 100 条投递记录；更早的投递需自行保存其 ID 才能重试。
- API Key 所属账号必须是企业管理员并具备 applications 与 agent 权限，否则返回 403。回调管理操作本身不产生 api.request.completed / api.request.failed 回调事件。

### 回调订阅 · 轮换签名密钥

`POST /v1/operations/callbacks.rotate`

权限：applications, agent, service
费用：按业务权限与套餐执行。

```sh
# cURL 7.76+；请先在服务端设置环境变量。
: "${YUNFU_BASE_URL:?请设置服务端 HTTPS 地址}"
: "${YUNFU_API_KEY:?请设置已获授权的 API 密钥}"
: "${YUNFU_IDEMPOTENCY_KEY:?请设置本次写入的唯一编号，重试沿用原编号}"
curl --fail-with-body --show-error "$YUNFU_BASE_URL/v1/operations/callbacks.rotate" \
  -H "Authorization: Bearer $YUNFU_API_KEY" \
  -H "Idempotency-Key: $YUNFU_IDEMPOTENCY_KEY" \
  -H 'Content-Type: application/json' \
  --data-binary '{
  "action": "rotate",
  "id": "YOUR_SUBSCRIPTION_ID",
  "revision": 2
}'
```

| 字段 | 类型 | 要求 | 说明 |
| --- | --- | --- | --- |
| id | string | 必填 | 订阅 ID，最长 100 字符。取自 callbacks.save 响应的 id，或 callbacks.read 的 subscriptions[].id；只能操作 API Key 所属管理员账号名下的订阅。 |
| revision | integer | 必填 | 订阅当前 revision，必须是 JSON 整数且与服务端当前值完全相等。取自 callbacks.save 响应的 revision，或 callbacks.read 的 subscriptions[].revision。 |

响应示例：
```json
{
  "secret": "whsec_EXAMPLE_ONLY",
  "enabled": false,
  "revision": 3
}
```

- 前置条件：先用 callbacks.read 读取订阅的最新 revision。订阅不存在或不属于 API Key 所属管理员账号返回 404；revision 不一致返回 409“订阅版本已变化，请刷新”。
- 启用或停用状态的订阅都可以轮换；已删除的订阅返回 409“订阅已删除”。
- 立即生效，没有新旧密钥并存的过渡期：旧密钥在响应返回时已作废。
- 轮换后订阅被自动停用：接收方换上新密钥后，用响应中的 revision 调用 callbacks.toggle（enabled: true）重新启用。停用期间发生的事件不会补发。
- 轮换时尚未送达的投递（pending、retry、sending）全部被取消（status=cancelled，message 为“订阅密钥已轮换或订阅已删除”），不会用新密钥补发；轮换前 dead 的投递也不能再用 callbacks.retry 重试。已送达的记录保留。
- 新密钥无法再次查询。唯一例外是使用相同 Idempotency-Key 与相同正文重放请求：网关在 24 小时内返回原响应（含同一 secret）。密钥丢失后只能再次轮换。
- API Key 所属账号必须是企业管理员并具备 applications 与 agent 权限，否则返回 403。回调管理操作本身不产生 api.request.completed / api.request.failed 回调事件。

### 回调订阅 · 删除订阅

`POST /v1/operations/callbacks.delete`

权限：applications, agent, service
费用：按业务权限与套餐执行。

```sh
# cURL 7.76+；请先在服务端设置环境变量。
: "${YUNFU_BASE_URL:?请设置服务端 HTTPS 地址}"
: "${YUNFU_API_KEY:?请设置已获授权的 API 密钥}"
: "${YUNFU_IDEMPOTENCY_KEY:?请设置本次写入的唯一编号，重试沿用原编号}"
curl --fail-with-body --show-error "$YUNFU_BASE_URL/v1/operations/callbacks.delete" \
  -H "Authorization: Bearer $YUNFU_API_KEY" \
  -H "Idempotency-Key: $YUNFU_IDEMPOTENCY_KEY" \
  -H 'Content-Type: application/json' \
  --data-binary '{
  "action": "delete",
  "id": "YOUR_SUBSCRIPTION_ID",
  "revision": 2
}'
```

| 字段 | 类型 | 要求 | 说明 |
| --- | --- | --- | --- |
| id | string | 必填 | 订阅 ID，最长 100 字符。取自 callbacks.save 响应的 id，或 callbacks.read 的 subscriptions[].id；只能操作 API Key 所属管理员账号名下的订阅。 |
| revision | integer | 必填 | 订阅当前 revision，必须是 JSON 整数且与服务端当前值完全相等。取自 callbacks.save 响应的 revision，或 callbacks.read 的 subscriptions[].revision。 |

响应示例：
```json
{
  "enabled": false,
  "revision": 3
}
```

- 前置条件：先用 callbacks.read 读取订阅的最新 revision。订阅不存在或不属于 API Key 所属管理员账号返回 404；revision 不一致返回 409“订阅版本已变化，请刷新”。
- 不可恢复：删除后回调地址与签名密钥被清除，再启用返回 403、再保存返回 409。如需恢复，用 callbacks.save 新建订阅（得到新的 ID 与密钥）。
- 删除保留记录而非物理删除：订阅仍出现在 callbacks.read 的 subscriptions[] 中，名称加“[已删除] ”前缀、events 为空数组、enabled 为 false；历史投递记录与每次尝试的记录保留，仍可通过 callbacks.read 查询。
- 删除时尚未送达的投递（pending、retry、sending）被取消（status=cancelled，message 为“订阅密钥已轮换或订阅已删除”）；已经发出的请求无法撤回。
- 已删除的订阅不再计入“每个账号最多 5 个订阅”的数量上限。
- 对已删除的订阅再次调用 delete 或 rotate 返回 409“订阅已删除”，不会改变记录。
- API Key 所属账号必须是企业管理员并具备 applications 与 agent 权限，否则返回 403。回调管理操作本身不产生 api.request.completed / api.request.failed 回调事件。

### 读取邮件关联客户与有效记忆

`GET /v1/operations/email-customer.read`

权限：service
费用：按业务权限与套餐执行。

```sh
# cURL 7.76+；请先在服务端设置环境变量。
: "${YUNFU_BASE_URL:?请设置服务端 HTTPS 地址}"
: "${YUNFU_API_KEY:?请设置已获授权的 API 密钥}"
curl --fail-with-body --show-error "$YUNFU_BASE_URL/v1/operations/email-customer.read?view=customerContext&messageId=message-id" \
  -H "Authorization: Bearer $YUNFU_API_KEY"
```

| 字段 | 类型 | 要求 | 说明 |
| --- | --- | --- | --- |
| view (query) | string | 必填 | 固定customerContext |
| messageId (query) | string | 必填 | 可读邮件的真实ID |

响应示例：
```json
{
  "messageId": "message-id",
  "association": {
    "status": "matched",
    "identityVerified": false
  },
  "customer": {
    "id": "customer-id"
  },
  "memory": {
    "status": "available",
    "entries": []
  },
  "history": []
}
```

- 只读取当前账号授权邮箱；邮箱匹配不是身份认证。
- 示例未实际执行；AI可能计费，发送需用户明确授权。

### 导出电话记录

`GET /v1/operations/phone-records.export`

权限：service
费用：按业务权限与套餐执行。

```sh
# cURL 7.76+；请先在服务端设置环境变量。
: "${YUNFU_BASE_URL:?请设置服务端 HTTPS 地址}"
: "${YUNFU_API_KEY:?请设置已获授权的 API 密钥}"
curl --fail-with-body --show-error "$YUNFU_BASE_URL/v1/operations/phone-records.export?view=export&ids=11111111-1111-4111-8111-111111111111" \
  -H "Authorization: Bearer $YUNFU_API_KEY"
```

| 字段 | 类型 | 要求 | 说明 |
| --- | --- | --- | --- |
| view | string | 必填 | 固定 export；操作网关 phone-records.export 会自动注入此查询参数。 |
| ids | string | 必填 | 逗号分隔的 1–100 个唯一电话 UUID；全部需属于当前企业。 |

响应示例：
```json
{
  "calls": []
}
```

- 电话呼叫 UUID 与 voice-records 的 sessionId 不同；不得把电话 ID 传入 analysis.read?kind=voice。
- 服务器返回 application/json，不是 CSV 文件。部分 ID 不存在或无权读取时整批返回 404，不静默导出部分数据。
- 先通过 phone-calls.read 分页筛选，按每批最多 100 个 ID 导出。记录可能包含客户正文，保存到用户指定的本地位置。
- 只读导出不会发起电话或生成收费分析。

### 读取客户订单与物流快照

`POST /v1/operations/business-data.snapshot`

权限：service
费用：按业务权限与套餐执行。

```sh
# cURL 7.76+；请先在服务端设置环境变量。
: "${YUNFU_BASE_URL:?请设置服务端 HTTPS 地址}"
: "${YUNFU_API_KEY:?请设置已获授权的 API 密钥}"
: "${YUNFU_IDEMPOTENCY_KEY:?请设置本次写入的唯一编号，重试沿用原编号}"
curl --fail-with-body --show-error "$YUNFU_BASE_URL/v1/operations/business-data.snapshot" \
  -H "Authorization: Bearer $YUNFU_API_KEY" \
  -H "Idempotency-Key: $YUNFU_IDEMPOTENCY_KEY" \
  -H 'Content-Type: application/json' \
  --data-binary '{
  "action": "customerSnapshot",
  "conversationId": "conv_example"
}'
```

| 字段 | 类型 | 要求 | 说明 |
| --- | --- | --- | --- |
| action | customerSnapshot | 可选 | 可省略，系统固定为 customerSnapshot；传入其他值返回 400。 |
| conversationId | string | 必填 | 正式会话编号；必须属于当前企业且已关联并核验客户档案。 |

响应示例：
```json
{
  "result": {
    "platformId": "taobao",
    "channelId": "channel_example",
    "customerId": "cus_example",
    "fetchedAt": 1789693200000,
    "customer": {
      "customerId": "cus_example",
      "displayName": "客户",
      "phoneMasked": "138****0000",
      "emailMasked": "c***@example.com",
      "locale": "zh-CN",
      "level": "普通",
      "tags": []
    },
    "orders": [
      {
        "orderId": "order_example",
        "status": "shipped",
        "amountPaid": 199,
        "refundableAmount": 0,
        "carrier": "示例物流",
        "trackingNumber": "masked_tracking",
        "logisticsStatus": "运输中",
        "timeline": [
          "2026-09-29 10:00 已揽收"
        ]
      }
    ]
  }
}
```

- 使用企业管理员创建的 Bearer API Key；网关会将操作绑定到密钥所属企业与账号，不能通过请求体切换租户或客户。
- POST 网关必须携带 8–100 位 Idempotency-Key；同一标识只能重放同一请求，结果未知时不要换标识重复执行。
- 只读能力仅对正式会话生效：会话必须来自已支持的原生渠道，并已关联和核验客户；请求体不能覆盖客户、企业、渠道或商家账号。
- 当前支持美团、京东、淘宝、五八、拼多多、抖音、小红书、Amazon 和 eBay 渠道；是否能返回字段仍由渠道的“接入智能体的信息”权限及订单/物流 scope 决定。
- 企业必须先在开放平台配置启用的客户订单只读连接器。连接器密钥只在服务端使用，绝不会通过 API 返回；目标地址必须为公开 HTTPS 且会重新校验 DNS。
- 快照经过字段白名单、归属校验和大小限制；外部商家返回的文本不会被当作智能体指令。连接器不可用、超时或返回未知数据时会返回明确错误，不伪造订单结论。
- 网关要求 Idempotency-Key；只读请求也使用同一请求语义以便安全重试，重复键返回缓存的同一快照结果。

### 查询订单或物流状态

`POST /v1/operations/business-data.lookup`

权限：service
费用：按业务权限与套餐执行。

```sh
# cURL 7.76+；请先在服务端设置环境变量。
: "${YUNFU_BASE_URL:?请设置服务端 HTTPS 地址}"
: "${YUNFU_API_KEY:?请设置已获授权的 API 密钥}"
: "${YUNFU_IDEMPOTENCY_KEY:?请设置本次写入的唯一编号，重试沿用原编号}"
curl --fail-with-body --show-error "$YUNFU_BASE_URL/v1/operations/business-data.lookup" \
  -H "Authorization: Bearer $YUNFU_API_KEY" \
  -H "Idempotency-Key: $YUNFU_IDEMPOTENCY_KEY" \
  -H 'Content-Type: application/json' \
  --data-binary '{
  "action": "lookup",
  "conversationId": "conv_example",
  "kind": "logistics_lookup",
  "input": {
    "orderId": "order_example",
    "customerId": "cus_example"
  }
}'
```

| 字段 | 类型 | 要求 | 说明 |
| --- | --- | --- | --- |
| action | lookup | 可选 | 可省略，系统固定为 lookup；传入其他值返回 400。 |
| conversationId | string | 必填 | 正式会话编号；必须属于当前企业并已关联客户。 |
| kind | order_lookup \| logistics_lookup | 必填 | 读取订单摘要或物流状态。 |
| input.orderId | string | 必填 | 商家订单编号。 |
| input.customerId | string | 必填 | 已核验客户编号，必须与会话关联客户一致。 |

响应示例：
```json
{
  "result": {
    "orderId": "order_example",
    "customerId": "cus_example",
    "status": "shipped",
    "amountPaid": 199,
    "refundableAmount": 0,
    "carrier": "示例物流",
    "trackingNumber": "masked_tracking",
    "timeline": [
      "2026-09-29 10:00 已揽收"
    ]
  }
}
```

- 使用企业管理员创建的 Bearer API Key；网关会将操作绑定到密钥所属企业与账号，不能通过请求体切换租户或客户。
- POST 网关必须携带 8–100 位 Idempotency-Key；同一标识只能重放同一请求，结果未知时不要换标识重复执行。
- 这是只读查询，不会发起退款、改价、改地址或其他订单写入；退款、订单更新和物流更新仍需后台客服提交并由人工审批。
- 服务端会将订单与当前会话关联客户做强一致校验，并只保留文档列出的字段；外部接口返回的任意说明不会作为提示词或系统指令执行。
- 外部连接器返回 429、超时、无效 JSON 或归属不一致时，接口会返回明确错误；不会无限重试、伪造办结或隐瞒待处理状态。
- 网关要求 Idempotency-Key；相同标识和请求可安全重放缓存结果，不能使用新标识绕过未知结果。

### 客户资料 · 预览会话与客户的关联

`GET /v1/operations/customers.bindPreview`

权限：customers, service
费用：按业务权限与套餐执行。

```sh
# cURL 7.76+；请先在服务端设置环境变量。
: "${YUNFU_BASE_URL:?请设置服务端 HTTPS 地址}"
: "${YUNFU_API_KEY:?请设置已获授权的 API 密钥}"
curl --fail-with-body --show-error "$YUNFU_BASE_URL/v1/operations/customers.bindPreview?bindPreview=1&conversationId=YOUR_CONVERSATION_ID&customerId=YOUR_CUSTOMER_ID" \
  -H "Authorization: Bearer $YUNFU_API_KEY"
```

| 字段 | 类型 | 要求 | 说明 |
| --- | --- | --- | --- |
| conversationId (query) | string | 必填 | 要关联的会话编号，必须是当前身份可见的会话。 |
| customerId (query) | string | 可选 | 目标客户编号，最多 100 字符；省略表示预览解除关联。 |

响应示例：
```json
{
  "catalogRevision": 12,
  "conversationVersion": 5,
  "linkRevision": 0,
  "customerRevision": 4,
  "from": null,
  "to": {
    "id": "YOUR_CUSTOMER_ID",
    "name": "示例客户",
    "revision": 4
  },
  "source": {
    "channelName": "官网客服",
    "label": "官网客服 / 默认入口"
  },
  "conflicts": [],
  "effect": "仅调整当前会话关联；两份客户档案保持独立，旧记忆授权将撤销。"
}
```

- 需要账号同时具备 customers 与 service 权限；会话不可见返回 404「对话不存在或无访问权限」，客户不存在返回 404「用户不存在」。
- 企业开启号码隐私后，返回的手机号为脱敏值。
