更新组织历史记录接口

scope: org:history:update

基本信息

项目	说明
接口路径	`POST /open/api/v1/org/updateOrgHistory`
Content-Type	`application/json`
所需权限	`org:history:update`
接口说明	更新指定组织的某一条历史记录，支持修改该记录的组织属性和生效日期

核心机制：增量合并

与「添加组织历史记录」接口相同，采用增量合并机制：

系统会获取 id 对应的目标历史记录作为基础数据

dataMap 中传入的字段会覆盖该记录中对应的字段

未传入的字段保持不变，沿用该记录原有的值

因此 dataMap 只需要传入你想修改的字段即可

请求参数

请求体（Request Body）

参数名	类型	是否必填	说明	示例
`corpId`	String	是	企业ID	`"ding4c7c311a701851ac35c2f4657eb6378f"`
`orgId`	String	是	组织ID	`"org_14bfa9a7264848ea929a03151121816c"`
`id`	String	是	历史记录ID（MongoDB ObjectId），可通过「获取组织历史记录列表」接口返回的 `dataMap.id` 获取	`"69899f58e4b03ff088d62d62"`
`effectDate`	String	是	生效日期，格式: `yyyy-MM-dd`	`"2027-06-01"`
`dataMap`	Object	是	组织数据，key 为字段ID，value 为字段值	见下方说明

dataMap 字段说明

系统字段

fieldId（key）	字段名	字段类型	是否必填	值格式说明
`name`	组织名称	string	是	文本字符串
`order`	组织序号	number	是	整数
`code`	组织编码	string	否	文本字符串
`type`	组织类型	selection（单选）	是	选项 value 值，可选：`businessGroup`（事业群）、`subCorporation`（子公司）、`department`（部门）、`corporation`（公司）、`group`（门店）
`managerEmpId`	组织负责人	emp（多选）	否	员工ID数组，如 `["emp_xxx", "emp_yyy"]`
`parentOrgId`	上级组织	org	是	组织ID字符串
`costCenterId`	成本中心	costCenter	否	成本中心ID字符串
`contractCompany`	合同公司	object	否	合同公司ID字符串

注意：必填字段在增量合并后校验，如果目标记录中已有值且你不需要修改，则无需重复传入。

自定义字段

自定义字段的 fieldId 和类型通过「获取组织字段定义」接口获取。不同字段类型的值格式如下：

字段类型	值格式	示例
`string`（文本）	字符串	`"文本内容"`
`number`（数字）	数字	`123`
`date`（日期）	日期字符串，格式 `yyyy-MM-dd`	`"2027-06-01"`
`selection`（单选）	选项的 `value` 值	`"selection_a8ebd5c1cdec43028a667f509da6304c"`
`selection`（多选，multiSelect=true）	选项 `value` 值的数组	`["selection_xxx", "selection_yyy"]`

请求示例

示例1：修改组织名称

{
    "corpId": "ding4c7c311a701851ac35c2f4657eb6378f",
    "orgId": "org_14bfa9a7264848ea929a03151121816c",
    "id": "693c1f4fc27987593f469002",
    "effectDate": "2025-12-12",
    "dataMap": {
        "name": "新的组织名称"
    }
}

示例2：修改多个字段

{
    "corpId": "ding4c7c311a701851ac35c2f4657eb6378f",
    "orgId": "org_14bfa9a7264848ea929a03151121816c",
    "id": "693c1f4fc27987593f469002",
    "effectDate": "2025-12-12",
    "dataMap": {
        "name": "新的组织名称",
        "code": "NEW_CODE",
        "type": "department",
        "field_org_sele_004": "selection_a8ebd5c1cdec43028a667f509da6304c"
    }
}

响应参数

外层结构（ApiResponse）

参数名	类型	说明
`data`	Object	响应数据体
`success`	Boolean	请求是否成功
`errorCode`	String	错误编码，正常为 `null`
`errorMsg`	String	错误信息，正常为 `null`

data 结构（OpenUpdateOrgHistoryResponse）

参数名	类型	说明
`corpId`	String	企业ID
`orgId`	String	组织ID
`id`	String	历史记录ID
`errorMsg`	Map<String, String>	错误信息。`null` 表示操作成功；非 `null` 时，key 为字段ID，value 为错误提示

响应示例

更新成功

{
    "data": {
        "corpId": "ding4c7c311a701851ac35c2f4657eb6378f",
        "orgId": "org_14bfa9a7264848ea929a03151121816c",
        "id": "693c1f4fc27987593f469002",
        "errorMsg": null
    },
    "success": true,
    "errorCode": null,
    "errorMsg": null
}

更新失败 — 记录不存在

{
    "data": {
        "corpId": "ding4c7c311a701851ac35c2f4657eb6378f",
        "orgId": "org_14bfa9a7264848ea929a03151121816c",
        "id": "invalid_id",
        "errorMsg": {
            "orgId": "记录不存在"
        }
    },
    "success": true,
    "errorCode": null,
    "errorMsg": null
}

更新失败 — 字段校验不通过

{
    "data": {
        "corpId": "ding4c7c311a701851ac35c2f4657eb6378f",
        "orgId": "org_14bfa9a7264848ea929a03151121816c",
        "id": "693c1f4fc27987593f469002",
        "errorMsg": {
            "name": "组织名称不能为空",
            "field_org_numb_002": "请输入正确的数字"
        }
    },
    "success": true,
    "errorCode": null,
    "errorMsg": null
}

参数校验失败

{
    "success": false,
    "errorCode": "400",
    "errorMsg": "企业ID不能为空"
}

业务校验规则

序号	校验项	错误信息	错误字段 key
1	企业ID不能为空	企业ID不能为空	参数校验层返回
2	组织ID不能为空	组织ID不能为空	参数校验层返回
3	历史记录ID不能为空	记录ID不能为空	参数校验层返回
4	生效日期不能为空	生效日期不能为空	参数校验层返回
5	组织数据不能为空	组织数据不能为空	参数校验层返回
6	记录ID必须存在	记录不存在	`orgId`
7	组织字段级校验不通过	根据具体字段返回	对应字段ID

业务处理流程

请求进入
  │
  ├── 1. 参数校验（corpId / orgId / id / effectDate / dataMap 不能为空）
  │
  ├── 2. 权限校验（需要 org:history:update 权限）
  │
  ├── 3. 查询该组织的所有历史记录，根据 id 查找目标记录
  │     └── 未找到 → 返回"记录不存在"
  │
  ├── 4. 获取企业的字段定义
  │
  ├── 5. 将 dataMap 转换为 OrgModel 对象
  │
  ├── 6. 增量合并：用新数据覆盖目标记录中对应的字段
  │
  ├── 7. 更新生效日期
  │
  ├── 8. 执行字段校验（必填性、格式、有效性、业务规则）
  │     └── 校验不通过 → 返回字段级错误信息
  │
  ├── 9. 保存更新后的记录
  │
  ├── 10. 发布组织变更事件（通知下游系统）
  │
  └── 返回成功响应（errorMsg = null）

与「添加组织历史记录」的区别

对比项	添加（addOrgHistory）	更新（updateOrgHistory）
操作对象	在最新记录基础上创建新记录	修改 `id` 指定的已有记录
是否需要 id	不需要	需要，指定要更新哪条记录
合并基础	最新一条历史记录	id 对应的目标记录
结果	多一条历史记录	记录总数不变，目标记录内容被更新

注意事项

增量合并：dataMap 只需传入要修改的字段，未传入的字段会沿用目标记录原有的值

成功判断方式：外层 success 始终为 true，需要通过 data.errorMsg 是否为 null 来判断操作是否真正成功

选项字段传 value 不传 label：选项类型字段需要传选项的 value（如 "selection_xxx"），而不是显示文本

记录ID来源：id 字段的值可通过「获取组织历史记录列表」接口返回的 dataMap.id 获取

生效日期可修改：effectDate 会覆盖目标记录的原生效日期

事件通知：更新成功后会发布组织变更事件（ORG_RECORD_UPDATE），下游系统可监听该事件进行相应处理

application/json

Bodyapplication/json

示例

{
    "data": {
        "corpId": "", //企业ID
        "orgId": "", //组织ID
        "id": "", //历史记录ID
        /**
         * 错误信息（为空表示成功）
         * key: 字段ID
         * value: 错误信息
         */
        "errorMsg": {
            "key": ""
        }
    },
    "success": false, //请求是否成功标志位
    "errorCode": "", //响应编码
    "errorMsg": "" //响应具体信息
}

更新指定的组织历史记录

更新组织历史记录接口

基本信息

核心机制：增量合并

请求参数

请求体（Request Body）

dataMap 字段说明

系统字段

自定义字段

请求示例

示例1：修改组织名称

示例2：修改多个字段

响应参数

外层结构（ApiResponse）

data 结构（OpenUpdateOrgHistoryResponse）

响应示例

更新成功

更新失败 — 记录不存在

更新失败 — 字段校验不通过

参数校验失败

业务校验规则

业务处理流程

与「添加组织历史记录」的区别

注意事项

请求参数

请求示例代码

返回响应

更新指定的组织历史记录

更新组织历史记录接口#

基本信息#

核心机制：增量合并#

请求参数#

请求体（Request Body）#

dataMap 字段说明#

系统字段#

自定义字段#

请求示例#

示例1：修改组织名称#

示例2：修改多个字段#

响应参数#

外层结构（ApiResponse）#

data 结构（OpenUpdateOrgHistoryResponse）#

响应示例#

更新成功#

更新失败 — 记录不存在#

更新失败 — 字段校验不通过#

参数校验失败#

业务校验规则#

业务处理流程#

与「添加组织历史记录」的区别#

注意事项#

请求参数

请求示例代码

返回响应

更新组织历史记录接口

基本信息

核心机制：增量合并

请求参数

请求体（Request Body）

dataMap 字段说明

系统字段

自定义字段

请求示例

示例1：修改组织名称

示例2：修改多个字段

响应参数

外层结构（ApiResponse）

data 结构（OpenUpdateOrgHistoryResponse）

响应示例

更新成功

更新失败 — 记录不存在

更新失败 — 字段校验不通过

参数校验失败

业务校验规则

业务处理流程

与「添加组织历史记录」的区别

注意事项