知办AI 开发者文档

Appearance

组织与人员 API 指南 ​

知办AI 的组织与人员服务端 API 面向外部 HR、IAM、OA、数据中台等系统开放，用于同步部门、成员、职位，并支持按 updated_since 做增量回查。

资源标识统一使用 id / *_id；开发期字段切换要求见 API 资源标识字段切换通知。

想直接试一下？

API 在线调试 (Scalar) 顶部填 Bearer ek_...，左侧选 org → Try it out。

能力总览 ​

┌─────────────────────────────────────────────────────────┐
│              组织与人员 (Org) 对外能力                  │
└─────────────────────────────────────────────────────────┘

  部门              ┌────────────────────────────────────┐
   ┌──────────────▶│  /org/departments                  │
   │               │  创建 / 列表 / 详情 / 更新 / 删除   │
 外部系统           └────────────────────────────────────┘
   │
   │ 成员             ┌────────────────────────────────────┐
   ├──────────────▶│  /org/members                      │
   │               │  添加 / 列表 / 详情 / 更新 / 移除    │
   │               └────────────────────────────────────┘
   │
   │ 职位             ┌────────────────────────────────────┐
   └──────────────▶│  /org/positions                    │
                   │  创建 / 列表 / 详情 / 更新 / 删除   │
                   └────────────────────────────────────┘

  增量同步：所有列表接口都支持 updated_since。

路径前缀都是 /api/external/v1/org。

鉴权与权限范围 ​

组织与人员 API 只接受 API Key (ek_)，不接受 Session Token (st_) 或管理员 JWT。

操作需要 scope
列表 / 详情 / 增量查询tenant.org.read
创建 / 更新 / 删除tenant.org.write

申请 API Key 时按最小权限勾选。组织同步回调配置在租户管理后台「组织与人员 → 组织同步」维护。

双向同步推荐流程 ​

外部系统写入知办AI：

外部 HR / IAM 系统
  → POST /org/departments
  → POST /org/members
  → POST /org/positions

知办AI 数据变化通知外部系统：

知办AI 组织数据变化
  → 组织同步 Webhook 薄通知
  → 外部系统校验签名、记录 event_id 后立即返回 2xx
  → 外部系统用自己保存的 last_success_updated_at 调用 updated_since 增量查询
  → 外部系统处理成功后推进 last_success_updated_at

不能接收 webhook 的私有化环境，可以定时增量拉取：

bash
curl -H "Authorization: Bearer ek_..." \
  "https://zhiban.creditease.corp/api/external/v1/org/members?updated_since=2026-06-23T10:00:00Z&limit=100"

SDK 方法映射 ​

Python SDK 的 client.org 模块覆盖组织与人员接口：

SDK 方法API用途
client.org.list_departments()GET /org/departments列部门 / 增量查询
client.org.create_department(...)POST /org/departments创建部门
client.org.update_department(department_id, ...)PATCH /org/departments/{department_id}更新部门
client.org.delete_department(department_id)DELETE /org/departments/{department_id}删除部门
client.org.list_members()GET /org/members列成员 / 增量查询
client.org.create_member(...)POST /org/members添加成员
client.org.update_member(account_id, ...)PATCH /org/members/{account_id}更新成员
client.org.delete_member(account_id)DELETE /org/members/{account_id}移除成员
client.org.list_positions()GET /org/positions列职位 / 增量查询
client.org.create_position(...)POST /org/positions创建职位
client.org.update_position(position_id, ...)PATCH /org/positions/{position_id}更新职位
client.org.delete_position(position_id)DELETE /org/positions/{position_id}删除职位

关键约束 ​

对象约束
部门根部门不可删除；有子部门或成员的部门不可删除
成员租户管理员不可通过 External API 移除；创建成员不允许授予 tenant.admin
对方系统 ID部门 third_department_id、成员 third_user_id、职位 third_position_id 在当前租户和接入来源内唯一
知办AI标识部门 / 职位使用 id；成员使用 account_id
删除删除为软删除；增量查询会返回 tombstone

通用约定 ​

所有接口路径前缀都是 /api/external/v1，示例里用 https://zhiban.creditease.corp 表示生产域名。

只接受并返回 third_department_id、third_position_id / third_user_id。已删除的 external_code / employee_id 请求字段会返回 HTTP 400，不会再做兼容解析。

通用请求头 ​

Header必填说明
Authorization是Bearer ek_...，只接受 API Key
Content-Type写接口必填application/json

通用列表入参 ​

参数位置类型必填说明
cursorquerystring否上一页返回的 next_cursor
limitqueryinteger否默认 50，最大 200
updated_sincequeryRFC3339 date-time否增量查询游标；传入后返回该时间之后变化的数据，包含软删除 tombstone

通用列表出参 ​

字段类型说明
itemsarray当前页数据
next_cursorstring下一页游标；没有下一页时为空或不存在
has_moreboolean是否还有下一页

通用错误出参 ​

json
{
  "success": false,
  "code": "scope_denied",
  "message": "missing required scope tenant.org.read",
  "request_id": "req_..."
}
HTTP常见原因
400参数缺失、字段格式不合法
401API Key 缺失、无效或已撤销
403scope 不足，或尝试移除租户管理员
404资源不存在，或不属于当前租户
409third_department_id 冲突、部门不可删除、部门移动形成循环

部门接口 ​

部门对象字段 ​

字段类型说明
idstring部门 ID
parent_idstring父部门 ID；根部门可能为空
namestring部门名称
pathstring部门路径，如 /知办AI/研发部
depthinteger部门层级；根部门为 0
sort_orderinteger排序值，越小越靠前
third_department_idstring外部系统部门编码，同租户唯一
member_countinteger当前部门成员数
metadataobject外部系统扩展字段
statusstringactive / deleted；deleted 仅在增量查询中出现
updated_atRFC3339 date-time最后更新时间

GET /org/departments ​

列出部门，支持游标分页和 updated_since 增量查询。

入参：

参数位置类型必填说明
cursorquerystring否上一页返回的 next_cursor
limitqueryinteger否默认 50，最大 200
updated_sincequeryRFC3339 date-time否返回该时间之后变化的部门，含 status=deleted tombstone

出参：

字段类型说明
itemsDepartment[]部门数组
next_cursorstring下一页游标
has_moreboolean是否还有下一页

示例：

bash
curl -H "Authorization: Bearer ek_..." \
  "https://zhiban.creditease.corp/api/external/v1/org/departments?limit=100&updated_since=2026-06-23T10:00:00Z"
json
{
  "items": [
    {
      "id": "11111111-1111-1111-1111-111111111111",
      "parent_id": "00000000-0000-0000-0000-000000000000",
      "name": "研发部",
      "path": "/知办AI/研发部",
      "depth": 1,
      "sort_order": 100,
      "third_department_id": "dept-rd",
      "member_count": 12,
      "metadata": { "source": "hr" },
      "status": "active",
      "updated_at": "2026-06-23T10:30:00Z"
    }
  ],
  "next_cursor": "eyJ1cGRhdGVkX2F0IjoiMjAyNi0wNi0yM1QxMDozMDowMFoiLCJ1dWlkIjoiMTExLi4uIn0=",
  "has_more": false
}

POST /org/departments ​

创建部门。需要 tenant.org.write。

入参：

字段类型必填说明
namestring是部门名称
parent_idstring否父部门 ID；不填则创建在根部门下
sort_orderinteger否排序值，默认 0
third_department_idstring否外部系统部门编码，同租户唯一
metadataobject否外部系统扩展字段

出参：201 Created，返回 Department 对象。

示例：

bash
curl -X POST -H "Authorization: Bearer ek_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "研发部",
    "parent_id": "00000000-0000-0000-0000-000000000000",
    "sort_order": 100,
    "third_department_id": "dept-rd",
    "metadata": { "hr_id": "D1001" }
  }' \
  https://zhiban.creditease.corp/api/external/v1/org/departments
json
{
  "id": "11111111-1111-1111-1111-111111111111",
  "parent_id": "00000000-0000-0000-0000-000000000000",
  "name": "研发部",
  "path": "/知办AI/研发部",
  "depth": 1,
  "sort_order": 100,
  "third_department_id": "dept-rd",
  "member_count": 0,
  "metadata": { "hr_id": "D1001" },
  "status": "active",
  "updated_at": "2026-06-23T10:30:00Z"
}

GET /org/departments/ ​

查看部门详情。需要 tenant.org.read。

入参：

参数位置类型必填说明
department_idpathstring是部门 ID

出参：Department 对象。

示例：

bash
curl -H "Authorization: Bearer ek_..." \
  https://zhiban.creditease.corp/api/external/v1/org/departments/11111111-1111-1111-1111-111111111111
json
{
  "id": "11111111-1111-1111-1111-111111111111",
  "parent_id": "00000000-0000-0000-0000-000000000000",
  "name": "研发部",
  "path": "/知办AI/研发部",
  "depth": 1,
  "sort_order": 100,
  "third_department_id": "dept-rd",
  "member_count": 12,
  "metadata": { "hr_id": "D1001" },
  "status": "active",
  "updated_at": "2026-06-23T10:30:00Z"
}

PATCH /org/departments/ ​

更新部门。需要 tenant.org.write。

入参：

字段类型必填说明
department_idpath string是部门 ID（opaque string）
namestring否部门名称
parent_idstring否新父部门 ID；空串表示解除父级
sort_orderinteger否排序值
third_department_idstring否外部系统部门编码，同租户唯一
metadataobject否外部系统扩展字段

出参：Department 对象。

示例：

bash
curl -X PATCH -H "Authorization: Bearer ek_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "平台研发部",
    "sort_order": 80,
    "metadata": { "hr_id": "D1001", "cost_center": "CC-RD" }
  }' \
  https://zhiban.creditease.corp/api/external/v1/org/departments/11111111-1111-1111-1111-111111111111
json
{
  "id": "11111111-1111-1111-1111-111111111111",
  "parent_id": "00000000-0000-0000-0000-000000000000",
  "name": "平台研发部",
  "path": "/知办AI/平台研发部",
  "depth": 1,
  "sort_order": 80,
  "third_department_id": "dept-rd",
  "member_count": 12,
  "metadata": { "hr_id": "D1001", "cost_center": "CC-RD" },
  "status": "active",
  "updated_at": "2026-06-23T10:35:00Z"
}

DELETE /org/departments/ ​

软删除部门。需要 tenant.org.write。

入参：

参数位置类型必填说明
department_idpathstring是部门 ID

出参：204 No Content，无响应体。

硬约束：

场景返回
删除根部门（depth=0）409
部门下还有子部门409
部门下还有成员409

示例：

bash
curl -i -X DELETE -H "Authorization: Bearer ek_..." \
  https://zhiban.creditease.corp/api/external/v1/org/departments/11111111-1111-1111-1111-111111111111
http
HTTP/1.1 204 No Content

成员接口 ​

成员对象字段 ​

字段类型说明
account_idstring成员账号 ID；成员接口用它作为 path id
display_namestring展示名
emailstring邮箱
phonestring手机号
third_user_idstring对方系统用户 ID（可承载原员工号）
titlestring职务/头衔
department_idstring所属部门 ID
statusstringactive / invited / suspended / left；left 为 tombstone
rolesstring[]租户内角色码
updated_atRFC3339 date-time最后更新时间

GET /org/members ​

列出成员，支持游标分页和 updated_since 增量查询。需要 tenant.org.read。

入参：

参数位置类型必填说明
cursorquerystring否上一页返回的 next_cursor
limitqueryinteger否默认 50，最大 200
updated_sincequeryRFC3339 date-time否返回该时间之后变化的成员，含 status=left tombstone

出参：

字段类型说明
itemsMember[]成员数组
next_cursorstring下一页游标
has_moreboolean是否还有下一页

示例：

bash
curl -H "Authorization: Bearer ek_..." \
  "https://zhiban.creditease.corp/api/external/v1/org/members?limit=100&updated_since=2026-06-23T10:00:00Z"
json
{
  "items": [
    {
      "account_id": "22222222-2222-2222-2222-222222222222",
      "display_name": "Alice",
      "email": "alice@example.com",
      "phone": "13800138000",
      "third_user_id": "E1001",
      "title": "工程师",
      "department_id": "11111111-1111-1111-1111-111111111111",
      "status": "active",
      "roles": ["tenant.member"],
      "updated_at": "2026-06-23T10:40:00Z"
    }
  ],
  "next_cursor": "",
  "has_more": false
}

POST /org/members ​

添加成员。系统会按 phone 或 email 查找已有账号；不存在时自动创建账号并加入当前租户。需要 tenant.org.write。

入参：

字段类型必填说明
phonestring否手机号；phone 和 email 至少填一个
emailstring否邮箱；phone 和 email 至少填一个
display_namestring否展示名
titlestring否职务/头衔
third_user_idstring否对方系统用户 ID（可承载原员工号）
department_idstring否所属部门 ID；不填时自动归入当前租户根部门
role_codestring否只能显式传 tenant.member；不能通过 External API 授予 tenant.admin

出参：201 Created，返回 Member 对象。

示例：

bash
curl -X POST -H "Authorization: Bearer ek_..." \
  -H "Content-Type: application/json" \
  -d '{
    "phone": "13800138000",
    "email": "alice@example.com",
    "display_name": "Alice",
    "department_id": "11111111-1111-1111-1111-111111111111",
    "third_user_id": "E1001",
    "title": "工程师",
    "role_code": "tenant.member"
  }' \
  https://zhiban.creditease.corp/api/external/v1/org/members
json
{
  "account_id": "22222222-2222-2222-2222-222222222222",
  "display_name": "Alice",
  "email": "alice@example.com",
  "phone": "13800138000",
  "third_user_id": "E1001",
  "title": "工程师",
  "department_id": "11111111-1111-1111-1111-111111111111",
  "status": "active",
  "roles": ["tenant.member"],
  "updated_at": "2026-06-23T10:40:00Z"
}

GET /org/members/ ​

查看成员详情。需要 tenant.org.read。

入参：

参数位置类型必填说明
account_idpathstring是成员账号 ID

出参：Member 对象。

示例：

bash
curl -H "Authorization: Bearer ek_..." \
  https://zhiban.creditease.corp/api/external/v1/org/members/22222222-2222-2222-2222-222222222222
json
{
  "account_id": "22222222-2222-2222-2222-222222222222",
  "display_name": "Alice",
  "email": "alice@example.com",
  "phone": "13800138000",
  "third_user_id": "E1001",
  "title": "工程师",
  "department_id": "11111111-1111-1111-1111-111111111111",
  "status": "active",
  "roles": ["tenant.member"],
  "updated_at": "2026-06-23T10:40:00Z"
}

PATCH /org/members/ ​

更新成员信息。需要 tenant.org.write。

入参：

字段类型必填说明
account_idpath uuid是成员账号 ID
display_namestring否展示名
titlestring否职务/头衔
third_user_idstring否对方系统用户 ID（可承载原员工号）
department_idstring否所属部门 ID；不填表示不修改，空串不允许，成员不能脱离部门
statusstring否只允许 active / suspended

出参：Member 对象。

示例：

bash
curl -X PATCH -H "Authorization: Bearer ek_..." \
  -H "Content-Type: application/json" \
  -d '{
    "display_name": "Alice Chen",
    "title": "高级工程师",
    "third_user_id": "E1001",
    "status": "active"
  }' \
  https://zhiban.creditease.corp/api/external/v1/org/members/22222222-2222-2222-2222-222222222222
json
{
  "account_id": "22222222-2222-2222-2222-222222222222",
  "display_name": "Alice Chen",
  "email": "alice@example.com",
  "phone": "13800138000",
  "third_user_id": "E1001",
  "title": "高级工程师",
  "department_id": "11111111-1111-1111-1111-111111111111",
  "status": "active",
  "roles": ["tenant.member"],
  "updated_at": "2026-06-23T10:45:00Z"
}

DELETE /org/members/ ​

移除成员。该操作是软删除，成员状态变为 left，不删除账号。需要 tenant.org.write。

入参：

参数位置类型必填说明
account_idpathstring是成员账号 ID

出参：204 No Content，无响应体。

硬约束：

场景返回
成员持有 tenant.admin 角色403
成员不存在或不属于当前租户404

示例：

bash
curl -i -X DELETE -H "Authorization: Bearer ek_..." \
  https://zhiban.creditease.corp/api/external/v1/org/members/22222222-2222-2222-2222-222222222222
http
HTTP/1.1 204 No Content

职位接口 ​

职位对象字段 ​

字段类型说明
idstring职位 ID
namestring职位名称
descriptionstring职位描述
sort_orderinteger排序值，越小越靠前
third_position_idstring外部系统职位编码，同租户唯一
is_systemboolean是否系统内置职位
member_countinteger使用该职位的成员数
agent_countinteger使用该职位的数字员工数
metadataobject外部系统扩展字段
statusstringactive / deleted；deleted 仅在增量查询中出现
updated_atRFC3339 date-time最后更新时间

GET /org/positions ​

列出职位，支持游标分页和 updated_since 增量查询。需要 tenant.org.read。

入参：

参数位置类型必填说明
cursorquerystring否上一页返回的 next_cursor
limitqueryinteger否默认 50，最大 200
updated_sincequeryRFC3339 date-time否返回该时间之后变化的职位，含 status=deleted tombstone

出参：

字段类型说明
itemsPosition[]职位数组
next_cursorstring下一页游标
has_moreboolean是否还有下一页

示例：

bash
curl -H "Authorization: Bearer ek_..." \
  "https://zhiban.creditease.corp/api/external/v1/org/positions?limit=100"
json
{
  "items": [
    {
      "id": "33333333-3333-3333-3333-333333333333",
      "name": "工程师",
      "description": "研发工程师",
      "sort_order": 100,
      "third_position_id": "pos-engineer",
      "is_system": false,
      "member_count": 8,
      "agent_count": 0,
      "metadata": { "grade": "P5" },
      "status": "active",
      "updated_at": "2026-06-23T10:50:00Z"
    }
  ],
  "next_cursor": "",
  "has_more": false
}

POST /org/positions ​

创建职位。需要 tenant.org.write。

入参：

字段类型必填说明
namestring是职位名称
descriptionstring否职位描述
sort_orderinteger否排序值，默认 0
third_position_idstring否外部系统职位编码，同租户唯一
metadataobject否外部系统扩展字段

出参：201 Created，返回 Position 对象。

示例：

bash
curl -X POST -H "Authorization: Bearer ek_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "工程师",
    "description": "研发工程师",
    "sort_order": 100,
    "third_position_id": "pos-engineer",
    "metadata": { "grade": "P5" }
  }' \
  https://zhiban.creditease.corp/api/external/v1/org/positions
json
{
  "id": "33333333-3333-3333-3333-333333333333",
  "name": "工程师",
  "description": "研发工程师",
  "sort_order": 100,
  "third_position_id": "pos-engineer",
  "is_system": false,
  "member_count": 0,
  "agent_count": 0,
  "metadata": { "grade": "P5" },
  "status": "active",
  "updated_at": "2026-06-23T10:50:00Z"
}

GET /org/positions/ ​

查看职位详情。需要 tenant.org.read。

入参：

参数位置类型必填说明
position_idpathstring是职位 ID

出参：Position 对象。

示例：

bash
curl -H "Authorization: Bearer ek_..." \
  https://zhiban.creditease.corp/api/external/v1/org/positions/33333333-3333-3333-3333-333333333333
json
{
  "id": "33333333-3333-3333-3333-333333333333",
  "name": "工程师",
  "description": "研发工程师",
  "sort_order": 100,
  "third_position_id": "pos-engineer",
  "is_system": false,
  "member_count": 8,
  "agent_count": 0,
  "metadata": { "grade": "P5" },
  "status": "active",
  "updated_at": "2026-06-23T10:50:00Z"
}

PATCH /org/positions/ ​

更新职位。需要 tenant.org.write。

入参：

字段类型必填说明
position_idpath string是职位 ID（opaque string）
namestring否职位名称
descriptionstring否职位描述
sort_orderinteger否排序值
third_position_idstring否外部系统职位编码，同租户唯一
metadataobject否外部系统扩展字段

出参：Position 对象。

示例：

bash
curl -X PATCH -H "Authorization: Bearer ek_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "高级工程师",
    "description": "高级研发工程师",
    "sort_order": 80,
    "metadata": { "grade": "P6" }
  }' \
  https://zhiban.creditease.corp/api/external/v1/org/positions/33333333-3333-3333-3333-333333333333
json
{
  "id": "33333333-3333-3333-3333-333333333333",
  "name": "高级工程师",
  "description": "高级研发工程师",
  "sort_order": 80,
  "third_position_id": "pos-engineer",
  "is_system": false,
  "member_count": 8,
  "agent_count": 0,
  "metadata": { "grade": "P6" },
  "status": "active",
  "updated_at": "2026-06-23T10:55:00Z"
}

DELETE /org/positions/ ​

删除职位。需要 tenant.org.write。

入参：

参数位置类型必填说明
position_idpathstring是职位 ID

出参：204 No Content，无响应体。

示例：

bash
curl -i -X DELETE -H "Authorization: Bearer ek_..." \
  https://zhiban.creditease.corp/api/external/v1/org/positions/33333333-3333-3333-3333-333333333333
http
HTTP/1.1 204 No Content

Webhook 出站通知 ​

当知办AI 侧组织数据变化时，会向租户后台「组织与人员 → 组织同步」配置的回调地址发送薄通知。通知不包含完整实体 body；生产同步建议把 Webhook 当作“有变化了”的唤醒信号，收到后返回 2xx，再按本系统保存的 last_success_updated_at 调用 updated_since 增量查询。

entity_id 不是要求接收方必须逐条回查详情，它主要用于幂等记录、排障定位、低频场景单实体回查。高可靠同步以增量查询结果为准。

POST ​

知办AI 发起的请求头：

Header说明
Content-Type固定为 application/json
X-Zhiban-Event-Id事件幂等 ID
X-Zhiban-Event-Type事件类型，如 org.member.updated
X-Zhiban-TimestampUnix 秒级时间戳
X-Zhiban-Signaturehex(HMAC-SHA256(signing_secret, timestamp + raw_body))

请求体字段：

字段类型说明
schema_versioninteger当前为 1
event_typestring事件类型
tenant_idstring租户 ID
entity_kindstringdepartment / member / position
entity_idstring变化实体 ID；成员事件这里是 account_id。用于排障/幂等/可选单实体回查，不是生产同步主游标
updated_atRFC3339 date-time本次事件对应的变更时间；可用于观测，不建议单独用它替代本地 last_success_updated_at

事件类型：

对象createdupdateddeleted
部门org.department.createdorg.department.updatedorg.department.deleted
成员org.member.createdorg.member.updatedorg.member.deleted
职位org.position.createdorg.position.updatedorg.position.deleted

示例通知：

http
POST /api/org-sync/webhook HTTP/1.1
Host: external.example.com
Content-Type: application/json
X-Zhiban-Event-Id: evt_01J1ABCDEF
X-Zhiban-Event-Type: org.member.updated
X-Zhiban-Timestamp: 1782201000
X-Zhiban-Signature: 44b7...
json
{
  "schema_version": 1,
  "event_type": "org.member.updated",
  "tenant_id": "aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa",
  "entity_kind": "member",
  "entity_id": "22222222-2222-2222-2222-222222222222",
  "updated_at": "2026-06-23T10:45:00Z"
}

接收方响应要求：

响应处理
2xx视为投递成功；建议只表示“通知已接收/已入队”，不要等完整增量同步完成再返回
非 2xx 或超时视为失败，知办AI 按退避策略重试，超过最大次数进入失败记录

签名校验示例：

python
import hashlib
import hmac

def verify(secret: str, timestamp: str, raw_body: bytes, signature: str) -> bool:
    mac = hmac.new(secret.encode("utf-8"), digestmod=hashlib.sha256)
    mac.update(timestamp.encode("utf-8"))
    mac.update(raw_body)
    expected = mac.hexdigest()
    return hmac.compare_digest(expected, signature)

收到通知后触发增量查询（推荐）：

bash
curl -H "Authorization: Bearer ek_..." \
  "https://zhiban.creditease.corp/api/external/v1/org/members?updated_since=2026-06-23T10:00:00Z&limit=100"

低频或排障时，也可以用 entity_id 回查单个实体：

bash
curl -H "Authorization: Bearer ek_..." \
  https://zhiban.creditease.corp/api/external/v1/org/members/22222222-2222-2222-2222-222222222222

增量查询 ​

列表接口都支持 updated_since：

bash
curl -H "Authorization: Bearer ek_..." \
  "https://zhiban.creditease.corp/api/external/v1/org/departments?updated_since=2026-06-23T10:00:00Z&limit=100"

增量返回包含软删除记录：

对象删除状态
部门status=deleted
成员status=left
职位status=deleted

增量查询出参与普通列表接口一致：

字段类型说明
itemsarray变更记录数组；对象字段与对应列表接口一致
items[].statusstring当前状态；软删除记录用 deleted 或 left 标识
items[].updated_atRFC3339 date-time本条记录最后更新时间
next_cursorstring下一页游标；有下一页时继续带上原 updated_since 和这个 cursor 拉取
has_moreboolean是否还有下一页

部门增量返回示例：

json
{
  "items": [
    {
      "id": "11111111-1111-1111-1111-111111111111",
      "parent_id": "00000000-0000-0000-0000-000000000000",
      "name": "平台研发部",
      "path": "/知办AI/平台研发部",
      "depth": 1,
      "sort_order": 80,
      "third_department_id": "dept-rd",
      "member_count": 12,
      "metadata": { "hr_id": "D1001", "cost_center": "CC-RD" },
      "status": "active",
      "updated_at": "2026-06-23T10:35:00Z"
    },
    {
      "id": "11111111-1111-1111-1111-111111111112",
      "parent_id": "00000000-0000-0000-0000-000000000000",
      "name": "临时部门",
      "path": "/知办AI/临时部门",
      "depth": 1,
      "sort_order": 200,
      "third_department_id": "dept-temp",
      "member_count": 0,
      "metadata": {},
      "status": "deleted",
      "updated_at": "2026-06-23T10:36:00Z"
    }
  ],
  "next_cursor": "",
  "has_more": false
}

成员增量返回示例：

json
{
  "items": [
    {
      "account_id": "22222222-2222-2222-2222-222222222222",
      "display_name": "Alice Chen",
      "email": "alice@example.com",
      "phone": "13800138000",
      "third_user_id": "E1001",
      "title": "高级工程师",
      "department_id": "11111111-1111-1111-1111-111111111111",
      "status": "active",
      "roles": ["tenant.member"],
      "updated_at": "2026-06-23T10:45:00Z"
    },
    {
      "account_id": "22222222-2222-2222-2222-222222222223",
      "display_name": "Bob",
      "email": "bob@example.com",
      "phone": "13900139000",
      "third_user_id": "E1002",
      "title": "工程师",
      "department_id": "11111111-1111-1111-1111-111111111111",
      "status": "left",
      "roles": ["tenant.member"],
      "updated_at": "2026-06-23T10:46:00Z"
    }
  ],
  "next_cursor": "",
  "has_more": false
}

职位增量返回示例：

json
{
  "items": [
    {
      "id": "33333333-3333-3333-3333-333333333333",
      "name": "高级工程师",
      "description": "高级研发工程师",
      "sort_order": 80,
      "third_position_id": "pos-engineer",
      "is_system": false,
      "member_count": 8,
      "agent_count": 0,
      "metadata": { "grade": "P6" },
      "status": "active",
      "updated_at": "2026-06-23T10:55:00Z"
    },
    {
      "id": "33333333-3333-3333-3333-333333333334",
      "name": "临时职位",
      "description": "",
      "sort_order": 200,
      "third_position_id": "pos-temp",
      "is_system": false,
      "member_count": 0,
      "agent_count": 0,
      "metadata": {},
      "status": "deleted",
      "updated_at": "2026-06-23T10:56:00Z"
    }
  ],
  "next_cursor": "",
  "has_more": false
}

生产同步建议记录每次成功处理到的最大 updated_at，下一轮作为 updated_since 继续拉取。

相关链接 ​

© 知办AI Team — 开发者公开文档. 平台运维 / 内部架构文档见内部 wiki.