版本：v2.0

创建营期组

在指定团（cut_id）下创建一个组。调用方只需提供组别名（group_nick_name），组序号（页面显示的"1组""2组"）由平台在该团内自动顺延；组的营期归属继承所属团、无需传入，返回中的 period_id 即团所在营期。

信息

本接口须先有团：cut_id 必须是 创建营期团 接口返回的团 ID，团不存在时直接失败、不会自动创建营期团，也不支持按团名称匹配。同一团内别名唯一即复用同一组，重复调用为幂等（返回原有 group_id、is_create=0）；不同团下允许同名组，彼此互不影响。

POST/api/createGroup

核心语义

须先有团：cut_id 必须是有效团 ID（由 创建营期团 返回），团不存在直接失败；不自动建团、不按名称匹配。
营期由团决定：组的营期继承所属团，调用方不传 period_id，避免组被挂到与团不一致的营期下；响应中 period_id 即团所在营期。
只传别名，序号在该团内自动顺延：调用方仅提供 group_nick_name；组序号取该团已有最大组序号 +1，尚无组时为 1，不支持由调用方指定。
展示名自动生成：响应中的 group_name = 组序号 + "组"（如"1组"），仅作展示用途、无需回传。平台团组页面按"别名优先、无别名时显示展示名"规则呈现。
同团别名唯一，幂等复用：同一 cut_id 下若已有同名组，不新建、直接返回原有 group_id 与 is_create=0；不同团下同名互不影响。
只做新增：不删除/覆盖已有组；不调整营员团组归属；不分配营员（营员分组在平台侧按既有流程完成）。
工具接口契约：code 恒为 0；成功时 msg 为空、data 为结果对象；失败时 msg 非空、data 为空数组。业务成功与否以 msg 判定。
并发建议：同一团下需要创建多个组时，用同一 cut_id 逐别名串行调用，避免并发写入产生重复组。

请求参数

名称	类型	描述	是否必填	默认值	备注
token	String	身份校验令牌	必填	-	由获取访问令牌获得
cut_id	Number	团 ID	必填	-	由 `创建营期团` 返回；`cut_id <= 0` 视为未传
group_nick_name	String	组别名	必填	-	如"心理"；首尾空白自动去除，去除后为空视为未传

备注

营期与组序号均不是请求参数：营期由所属团决定，组序号由平台在该团内自动顺延。

CURL

V1

curl --location --request POST 'https://open.xinduobang.cn/api/createGroup' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'token=YOUR_TOKEN' \
--data-urlencode 'cut_id=43' \
--data-urlencode 'group_nick_name=心理'

V2（appid 为 `V2` 版本）

curl --location --request POST 'https://open.xinduobang.cn/api/createGroup' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--header 'X-Timestamp: 1770000000' \
--header 'X-Nonce: 3f9c1a7b2e6d4058' \
--header 'X-Signature: <computed_hmac_sha256>' \
--data-urlencode 'token=YOUR_TOKEN' \
--data-urlencode 'cut_id=43' \
--data-urlencode 'group_nick_name=心理'

信息

V2 签名算法及 X-Signature 计算方式见 V2 接入示例。

同团批量建组（串行）

同一团下依次创建多个组时，逐别名各调一次即可，切勿并发：

for g in "心理" "物理1营" "化学2营"; do
  curl --location --request POST 'https://open.xinduobang.cn/api/createGroup' \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode 'token=YOUR_TOKEN' \
  --data-urlencode 'cut_id=43' \
  --data-urlencode "group_nick_name=$g"
done

成功响应

新建成功

{
  "code": 0,
  "msg": "",
  "data": {
    "period_id": 33045,
    "cut_id": 43,
    "team_name": "1团",
    "team_nick_name": "牛剑2期",
    "group_id": 518,
    "group_name": "1组",
    "group_nick_name": "心理",
    "is_create": 1
  }
}

幂等复用（同团已存在同名组）

{
  "code": 0,
  "msg": "",
  "data": {
    "period_id": 33045,
    "cut_id": 43,
    "team_name": "1团",
    "team_nick_name": "牛剑2期",
    "group_id": 518,
    "group_name": "1组",
    "group_nick_name": "心理",
    "is_create": 0
  }
}

响应字段说明

键	类型	说明
data.period_id	Number	营期 ID（继承自所属团）
data.cut_id	Number	团 ID，即请求传入值
data.team_name	String	所属团展示名（团序号 + "团"），仅展示用
data.team_nick_name	String	所属团别名；团未设置别名时为空字符串
data.group_id	Number	组 ID
data.group_name	String	组展示名（组序号 + "组"），仅展示用
data.group_nick_name	String	组别名（首尾空白已去除）
data.is_create	Number	`1`=本次新建；`0`=同团内同名组已存在并复用

失败响应

工具接口契约下 code 恒为 0，失败通过非空 msg 与空 data 标识。

{ "code": 0, "msg": "团不存在cut_id=999999，请先调用 createTeam 拿到 cut_id", "data": [] }

错误文案	说明
`cut_id不能为空`	`cut_id` 缺失或非法（`<= 0`），请先调用 `创建营期团` 取得团 ID
`group_nick_name不能为空`	`group_nick_name` 缺失或去除空白后为空串
`团不存在cut_id=x，请先调用 createTeam 拿到 cut_id`	团 ID 无效（不存在或已被删除），请重新调用创建营期团接口获取
`创建组失败 cut_id=x group_nick_name=y`	参数校验通过但创建未成功，请联系平台核查

变更记录

日期	变更
2026-10-19	首次发布：`/api/createGroup`（POST：`cut_id` + `group_nick_name`），透传上游 `/Tools/createGroup`。须使用 `创建营期团` 返回的 `cut_id`，营期继承所属团；只传组别名，组序号在该团内自动顺延；同一团内别名唯一即复用同一组（幂等，`is_create=0`），不同团下同名互不影响；返回 `group_id` 及所属团、营期信息

核心语义​

请求参数​

CURL​

V1​

V2（appid 为 V2 版本）​

同团批量建组（串行）​

成功响应​

新建成功​

幂等复用（同团已存在同名组）​

响应字段说明​

失败响应​

相关接口​

变更记录​