设置组织关联钉钉通讯录部门接口

scope: org:relation:dingtalk

基本信息

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

请求参数

请求体（Request Body）

参数名	类型	是否必填	说明	示例
`corpId`	String	是	企业ID	`"ding4c7c311a701851ac35c2f4657eb6378f"`
`orgId`	String	是	Venus 系统组织ID	`"org_14bfa9a7264848ea929a03151121816c"`
`deptId`	String	是	钉钉通讯录部门ID	`"12345678"`

请求示例

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

响应参数

外层结构（ApiResponse）

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

data 结构（OpenSetOrgDingTalkDeptResponse）

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

响应示例

关联成功

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

关联失败 — 组织不存在

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

关联失败 — 已经关联

该组织与该钉钉部门已存在关联关系，不能重复关联。

{
    "data": {
        "corpId": "ding4c7c311a701851ac35c2f4657eb6378f",
        "orgId": "org_14bfa9a7264848ea929a03151121816c",
        "deptId": "12345678",
        "errorMsg": {
            "orgId": "已经关联"
        }
    },
    "success": true,
    "errorCode": null,
    "errorMsg": null
}

参数校验失败

{
    "success": false,
    "errorCode": "400",
    "errorMsg": "钉钉部门ID不能为空"
}

业务校验规则

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

业务处理流程

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

注意事项

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

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

不能重复关联：同一个 orgId + deptId 组合已经成功关联后，再次调用会返回"已经关联"

取消关联：如需取消已建立的关联关系，请调用「取消组织关联钉钉通讯录部门」接口（/open/api/v1/org/cancelOrgDingTalkDept）

请求示例代码

Shell

JavaScript

Java

Swift

PHP

Python

HTTP

Objective-C

Ruby

OCaml

Dart

返回响应

🟢200设置组织关联钉钉通讯录部门-Example

application/json

Bodyapplication/json

示例

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

设置组织关联钉钉通讯录部门

设置组织关联钉钉通讯录部门接口#

基本信息#

请求参数#

请求体（Request Body）#

请求示例#

响应参数#

外层结构（ApiResponse）#

data 结构（OpenSetOrgDingTalkDeptResponse）#

响应示例#

关联成功#

关联失败 — 组织不存在#

关联失败 — 已经关联#

参数校验失败#

业务校验规则#

业务处理流程#

注意事项#

请求参数

请求示例代码

返回响应

设置组织关联钉钉通讯录部门接口

基本信息

请求参数

请求体（Request Body）

请求示例

响应参数

外层结构（ApiResponse）

data 结构（OpenSetOrgDingTalkDeptResponse）

响应示例

关联成功

关联失败 — 组织不存在

关联失败 — 已经关联

参数校验失败

业务校验规则

业务处理流程

注意事项