取消组织关联钉钉通讯录部门接口

scope: org:relation:dingtalk:cancel

基本信息

项目	说明
接口路径	`POST /open/api/v1/org/cancelOrgDingTalkDept`
Content-Type	`application/json`
所需权限	`org:relation:dingtalk:cancel`
接口说明	取消 Venus 系统中组织与钉钉通讯录部门的关联映射关系

请求参数

请求体（Request Body）

参数名	类型	是否必填	说明	示例
`corpId`	String	是	企业ID	`"ding4c7c311a701851ac35c2f4657eb6378f"`
`orgId`	String	是	Venus 系统组织ID	`"org_14bfa9a7264848ea929a03151121816c"`

请求示例

{
    "corpId": "ding4c7c311a701851ac35c2f4657eb6378f",
    "orgId": "org_14bfa9a7264848ea929a03151121816c"
}

响应参数

外层结构（ApiResponse）

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

data 结构（OpenCancelOrgDingTalkDeptResponse）

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

响应示例

取消关联成功

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

取消关联失败 — 组织不存在

{
    "data": {
        "corpId": "ding4c7c311a701851ac35c2f4657eb6378f",
        "orgId": "org_xxxx",
        "errorMsg": {
            "orgId": "组织不存在"
        }
    },
    "success": true,
    "errorCode": null,
    "errorMsg": null
}

取消关联失败 — 未关联

该组织尚未与钉钉部门建立关联关系，无法取消。

{
    "data": {
        "corpId": "ding4c7c311a701851ac35c2f4657eb6378f",
        "orgId": "org_14bfa9a7264848ea929a03151121816c",
        "errorMsg": {
            "orgId": "组织未关联钉钉部门"
        }
    },
    "success": true,
    "errorCode": null,
    "errorMsg": null
}

参数校验失败

{
    "success": false,
    "errorCode": "400",
    "errorMsg": "组织ID不能为空"
}

业务校验规则

序号	校验项	错误信息	错误字段 key
1	企业ID不能为空	企业ID不能为空	参数校验层返回
2	组织ID不能为空	组织ID不能为空	参数校验层返回
3	组织必须存在（基于当前日期生效的记录）	组织不存在	`orgId`
4	组织必须已关联钉钉部门（映射存在且同步完成）	组织未关联钉钉部门	`orgId`

业务处理流程

请求进入
  │
  ├── 1. 参数校验（corpId / orgId 不能为空）
  │
  ├── 2. 权限校验（需要 org:relation:dingtalk:cancel 权限）
  │
  ├── 3. 校验组织是否存在（基于当前日期查询生效中的组织记录）
  │     └── 不存在 → 返回"组织不存在"
  │
  ├── 4. 查询该组织的钉钉部门映射关系
  │     └── 不存在或未同步完成 → 返回"组织未关联钉钉部门"
  │
  ├── 5. 更新映射状态
  │     ├── 清空 deptId
  │     ├── 同步类型设为 NOT_SYNC（不关联）
  │     └── 同步状态设为 NOT_SYNC（不关联）
  │
  ├── 6. 保存映射关系
  │
  └── 返回成功响应（errorMsg = null）

注意事项

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

组织存在性校验：基于当前日期查询生效中的组织记录，如果组织已停用或尚未生效，会返回"组织不存在"

必须已关联：只有已经成功关联钉钉部门的组织才能取消关联，未关联的组织调用此接口会返回"组织未关联钉钉部门"

重新关联：取消关联后，如需重新建立关联关系，请调用「设置组织关联钉钉通讯录部门」接口（/open/api/v1/org/setOrgDingTalkDept）

请求示例代码

Shell

JavaScript

Java

Swift

PHP

Python

HTTP

Objective-C

Ruby

OCaml

Dart

返回响应

🟢200取消组织关联钉钉通讯录部门-Example

application/json

Bodyapplication/json

示例

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

取消组织关联钉钉通讯录部门

取消组织关联钉钉通讯录部门接口#

基本信息#

请求参数#

请求体（Request Body）#

请求示例#

响应参数#

外层结构（ApiResponse）#

data 结构（OpenCancelOrgDingTalkDeptResponse）#

响应示例#

取消关联成功#

取消关联失败 — 组织不存在#

取消关联失败 — 未关联#

参数校验失败#

业务校验规则#

业务处理流程#

注意事项#

请求参数

请求示例代码

返回响应

取消组织关联钉钉通讯录部门接口

基本信息

请求参数

请求体（Request Body）

请求示例

响应参数

外层结构（ApiResponse）

data 结构（OpenCancelOrgDingTalkDeptResponse）

响应示例

取消关联成功

取消关联失败 — 组织不存在

取消关联失败 — 未关联

参数校验失败

业务校验规则

业务处理流程

注意事项