单个创建组织接口

scope: org:create

基本信息

项目	说明
接口路径	`POST /open/api/v1/org/createOneOrg`
Content-Type	`application/json`
所需权限	`org:create`
接口说明	在 Venus 系统中单个创建一个组织，支持标准字段和自定义字段

请求参数

请求体（Request Body）

外层结构（OrgCreateOneRequest）

参数名	类型	是否必填	说明	示例
`corpId`	String	是	企业ID	`"ding4c7c311a701851ac35c2f4657eb6378f"`
`orgData`	Object	是	组织创建数据	见下方

orgData 结构（OrgCreateData）

参数名	类型	是否必填	说明	示例
`bizId`	String	是	本次通信数据唯一标识ID，用于幂等追踪	`"biz-ddd"`
`effectDate`	String	是	生效时间，格式：`YYYY-MM-DD`	`"2025-03-02"`
`createDataMap`	Object	否	组织属性键值对，包含标准字段和自定义字段	见下方

createDataMap 标准字段

参数名	类型	是否必填	说明	示例
`name`	String	取决于企业字段配置	组织名称	`"测试接口创建规则"`
`code`	String	否	组织编码，仅允许数字和英文字母	`"ORG001"`
`type`	String	否	组织类型	`"corporation"`
`parentOrgId`	String	否	上级组织ID	`"1"`
`order`	Long	否	组织序号，范围 0-9999999	`10`
`managerEmpId`	List<String>	否	组织负责人员工ID列表	`["emp001", "emp002"]`
`costCenterId`	String	否	成本中心ID	`"cost_center_001"`
`costCenterCode`	String	否	成本中心编码（与 costCenterId 二选一）	`"CC001"`
`contractCompany`	String	否	合同公司ID	`"company_001"`
`syncStatus`	Boolean	否	是否同步钉钉通讯录	`false`
`field_xxx`	Object	否	自定义字段，key 为字段ID，value 为字段值	见请求示例

注意：name 等字段是否必填取决于企业的字段配置（required 属性），不同企业的字段配置可能不同。

请求示例

{
    "corpId": "ding4c7c311a701851ac35c2f4657eb6378f",
    "orgData": {
        "bizId": "biz-ddd",
        "effectDate": "2025-03-02",
        "createDataMap": {
            "order": "10",
            "name": "测试接口创建规则",
            "type": "corporation",
            "field_3a7b77496b39447da0878a0ee69aba26": [
                "selection_ef14885b856044e4ba806b9d3bf4c146"
            ],
            "field_10b57d9871444254b37fe388df566a9c": "",
            "parentOrgId": "1",
            "field_org_stri_002": "自定义文本字段",
            "field_org_stri_016": "11",
            "syncStatus": false
        }
    }
}

响应参数

外层结构（ApiResponse）

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

data 结构（CreateOpenOrgResponse）

参数名	类型	说明
`corpId`	String	企业ID
`orgId`	String	创建成功后返回的组织ID，失败时为 `null`
`bizId`	String	本次通信唯一标识ID
`errorMsg`	Map<String, String>	错误信息。`null` 表示操作成功；非 `null` 时，key 为字段标识，value 为错误提示

响应示例

创建成功

{
    "data": {
        "corpId": "ding4c7c311a701851ac35c2f4657eb6378f",
        "orgId": "org_14bfa9a7264848ea929a03151121816c",
        "bizId": "biz-ddd",
        "errorMsg": null
    },
    "success": true,
    "errorCode": null,
    "errorMsg": null
}

创建失败 — 组织名称重复

{
    "data": {
        "corpId": "ding4c7c311a701851ac35c2f4657eb6378f",
        "orgId": null,
        "bizId": "biz-ddd",
        "errorMsg": {
            "name": "组织名称重复"
        }
    },
    "success": true,
    "errorCode": null,
    "errorMsg": null
}

创建失败 — 上级组织不存在

{
    "data": {
        "corpId": "ding4c7c311a701851ac35c2f4657eb6378f",
        "orgId": null,
        "bizId": "biz-ddd",
        "errorMsg": {
            "parentOrgId": "上级组织不存在"
        }
    },
    "success": true,
    "errorCode": null,
    "errorMsg": null
}

创建失败 — 多个字段校验错误

{
    "data": {
        "corpId": "ding4c7c311a701851ac35c2f4657eb6378f",
        "orgId": null,
        "bizId": "biz-ddd",
        "errorMsg": {
            "name": "组织名称重复",
            "code": "组织编码已存在",
            "managerEmpId": "负责人不存在或未生效"
        }
    },
    "success": true,
    "errorCode": null,
    "errorMsg": null
}

参数校验失败

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

业务校验规则

序号	校验项	错误信息	错误字段 key
1	企业ID不能为空	企业ID不能为空	参数校验层返回
2	组织数据不能为空	orgData不能为空	参数校验层返回
3	bizId不能为空	bizId不能为空	参数校验层返回
4	生效日期不能为空	生效日期不能为空	参数校验层返回
5	必填字段不能为空（基于企业字段配置）	「字段名」不能为空	对应字段ID
6	相同上级组织下，组织名称在生效时间段内不允许重复	组织名称重复	`name`
7	组织名称不能包含特殊字符（`-`、`,`、`，`）	格式校验错误	`name`
8	上级组织不能是自己	上级组织不能为自己	`parentOrgId`
9	上级组织必须存在	上级组织不存在	`parentOrgId`
10	组织生效日期不能早于上级组织的生效日期	生效日期不能早于上级组织的生效日期：YYYY-MM-DD	`parentOrgId`
11	上级组织不能是已停用状态	上级组织已停用	`parentOrgId`
12	上级组织不能形成循环引用	上级组织不能为子组织	`parentOrgId`
13	组织负责人必须存在且在生效日期有效	负责人不存在或未生效	`managerEmpId`
14	组织负责人不能是已离职状态	X员工已离职	`managerEmpId`
15	组织编码仅允许数字和英文字母	组织编码数据错误	`code`
16	组织编码全局唯一	组织编码已存在	`code`
17	合同公司必须存在	合同公司不存在	`contractCompany`
18	合同公司不能是已停用状态	合同公司已停用	`contractCompany`
19	组织序号必须是 0-9999999 之间的整数	「组织序号」只能设置为0-9999999之间的整数	`order`

业务处理流程

请求进入
  │
  ├── 1. 参数校验（corpId / orgData / bizId / effectDate 不能为空）
  │
  ├── 2. 权限校验（需要 org:create 权限）
  │
  ├── 3. 获取企业的组织字段定义
  │
  ├── 4. 数据转换
  │     ├── 将 createDataMap 中的标准字段映射到 OrgModel
  │     ├── 解析自定义字段（field_xxx）
  │     ├── 设置默认值（生成唯一 orgId、状态设为启用、标记未删除）
  │     └── 解析生效时间
  │
  ├── 5. 字段级校验
  │     ├── 必填性校验（基于企业字段配置的 required 属性）
  │     ├── 数据类型格式校验
  │     └── 字段值有效性校验（如 ID 类型字段是否存在）
  │
  ├── 6. 业务级校验（字段级校验通过后执行）
  │     ├── 组织名称唯一性校验
  │     ├── 上级组织合法性校验（存在性、停用状态、循环引用）
  │     ├── 组织负责人有效性校验
  │     ├── 组织编码格式和唯一性校验
  │     ├── 合同公司有效性校验
  │     └── 组织序号范围校验
  │
  ├── 7. 校验失败 → 返回 errorMsg（包含字段级错误信息）
  │
  ├── 8. 校验成功 → 保存组织数据到数据库
  │
  ├── 9. 发布组织创建事件（触发钉钉同步、日志记录等）
  │
  └── 返回成功响应（orgId + bizId，errorMsg = null）

注意事项

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

幂等性：通过 bizId 标识每次请求，可用于追踪和排查问题

字段必填性：标准字段（如 name）是否必填取决于企业的字段配置，不同企业可能不同

自定义字段：createDataMap 中以 field_ 开头的字段为企业自定义字段，需要先在系统中配置字段定义

选项类型字段：选项类型的自定义字段值需要使用选项ID（如 selection_xxx），不能直接传入选项文本

组织名称限制：同一上级组织下，在生效时间段内组织名称不允许重复，且不能包含 -、,、， 等特殊字符

组织编码限制：编码全局唯一，仅允许数字（0-9）和英文字母（A-z）

组织序号：序号值为字符串类型传入，后端会转换为 Long 类型，范围 0-9999999

生效日期：组织的生效日期不能早于上级组织的生效日期

10.

默认状态：创建的组织默认状态为「启用」

application/json

Bodyapplication/json

示例

{
    "data": {
        "corpId": "", //企业ID
        "orgId": "", //组织Id
        "bizId": "", //本次通信Id
        /**
         * 错误信息
         * 列子
         * name：测试组织重复
         */
        "errorMsg": {
            "key": ""
        }
    },
    "success": false, //请求是否成功标志位
    "errorCode": "", //响应编码
    "errorMsg": "" //响应具体信息
}

单个创建组织

单个创建组织接口

基本信息

请求参数

请求体（Request Body）

外层结构（OrgCreateOneRequest）

orgData 结构（OrgCreateData）

createDataMap 标准字段

请求示例

响应参数

外层结构（ApiResponse）

data 结构（CreateOpenOrgResponse）

响应示例

创建成功

创建失败 — 组织名称重复

创建失败 — 上级组织不存在

创建失败 — 多个字段校验错误

参数校验失败

业务校验规则

业务处理流程

注意事项

请求参数

请求示例代码

返回响应

单个创建组织

单个创建组织接口#

基本信息#

请求参数#

请求体（Request Body）#

外层结构（OrgCreateOneRequest）#

orgData 结构（OrgCreateData）#

createDataMap 标准字段#

请求示例#

响应参数#

外层结构（ApiResponse）#

data 结构（CreateOpenOrgResponse）#

响应示例#

创建成功#

创建失败 — 组织名称重复#

创建失败 — 上级组织不存在#

创建失败 — 多个字段校验错误#

参数校验失败#

业务校验规则#

业务处理流程#

注意事项#

请求参数

请求示例代码

返回响应

单个创建组织接口

基本信息

请求参数

请求体（Request Body）

外层结构（OrgCreateOneRequest）

orgData 结构（OrgCreateData）

createDataMap 标准字段

请求示例

响应参数

外层结构（ApiResponse）

data 结构（CreateOpenOrgResponse）

响应示例

创建成功

创建失败 — 组织名称重复

创建失败 — 上级组织不存在

创建失败 — 多个字段校验错误

参数校验失败

业务校验规则

业务处理流程

注意事项