更换营期

对 导入订单 产生的线下导入订单更换营期：传入新的 plu（营期规格），把订单从原营期迁移到新营期。允许跨营种（新 plu 的 pid 可与原订单不同），直接落库、不走换营审批流（不产生 order_exchange 记录）。

信息

本接口是 导入订单 链路的配套换营期接口，仅适用于导入订单。只改营期 / 营种绑定与库存，不动价格：新旧营期若存在差价，请另行调用 导入订单退款（退差）或收款接口（补差）。

POST/api/changeImportOrderPeriod

核心语义

1. 换营期（允许跨营种）：以新 plu 解析出新的 pid / period_id / sku_str，更新订单的营种与营期绑定字段，并把原状态存入 old_status。跨营种时营员报名表数据仍保留（仅打标记），新旧表单定义的字段差异属"允许跨营种"的固有代价。
2. 不动价格：paymoney、all_price、order_agio、sale_price、post_price 等金额字段保持原值，不因新营期重算，也不产生补差 / 退差流水；差价由上游另行处理。
3. 迁移库存：老营期回退、新营期占用（period.used_count 与库存服务 skuV2 对称处理），与建单口径一致。
4. 营员报名表数据保留：换营不迁移 / 不删除营员已填数据，仅给这些行打上"原营期"标记。
5. 核销码不重生成：核销码只绑订单、与营期无关，换营后保持不变。
6. 亲子转单飞：老营期为亲子营、新营期为非亲子营时，成人名额并入儿童，并同步订单人数。
7. 营期变化自动退保：新营期与原营期不同（period_id 变化）时，原营期保险在事务提交后自动退保。
8. 外部副作用后置：库存服务与退保在数据库事务提交之后执行，失败仅记日志，不影响已提交的换营结果。
9. 幂等拦截：新 pid / period_id / sku_str 与订单当前值完全一致时，直接返回"订单已在该营期，无需更换"。
10. 工具接口契约：code 恒为 0；成功时 msg 为空、data 为换营摘要；失败时 msg 非空、data 为空数组。

请求参数

名称	类型	描述	是否必填	默认值	备注
token	String	身份校验令牌	必填	-	由 获取访问令牌 获得
order_num	String	订单号	必填	-	导入订单 返回的 order_num，形如 NO...
plu	String	新营期规格	必填	-	新营期 plu（营种规格），决定新的 pid / period_id / sku_str；可与原订单不同营种。从 获取营种详情 的 spec_period.period_list[].sku_plu 拉取

CURL

V1

curl --location --request POST 'https://open.xinduobang.cn/api/changeImportOrderPeriod' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'token=YOUR_TOKEN' \
--data-urlencode 'order_num=NO20261009103000123456' \
--data-urlencode 'plu=177413247099'

V2（appid 为 V2 版本）

curl --location --request POST 'https://open.xinduobang.cn/api/changeImportOrderPeriod' \
--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 'order_num=NO20261009103000123456' \
--data-urlencode 'plu=177413247099'

信息

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

请求示例

同营种换营期

POST 字段：order_num + plu，新 plu 与原订单同营种、仅换营期。

--data-urlencode 'order_num=NO20261009103000123456' \
--data-urlencode 'plu=177413247099'

跨营种换营期

POST 字段：order_num + plu，新 plu 属于另一营种。跨营种时返回 cross_product=1，订单的 pid / pName / 表单定义 / product_type 一并切换为新营种；营员报名表数据保留并打原营期标记。

--data-urlencode 'order_num=NO20261009103000123456' \
--data-urlencode 'plu=188922334455'

成功响应

{
  "code": 0,
  "msg": "",
  "data": {
    "order_num": "NO20261009103000123456",
    "old_pid": 2690,
    "new_pid": 2690,
    "old_period_id": 12345,
    "new_period_id": 12399,
    "period": "2026年暑期第一期",
    "sku_str": "1,2",
    "cross_product": 0,
    "order_status": 2
  }
}

响应字段说明

键	类型	说明
order_num	String	命中的订单号
old_pid / new_pid	Number	原营种 ID / 新营种 ID
old_period_id / new_period_id	Number	原营期 ID / 新营期 ID
period	String	新营期名称
sku_str	String	新规格串
cross_product	Number	1=跨营种（new_pid != old_pid）；0=同营种换营期
order_status	Number	换营后订单状态：新营期已结束为 4（已结营），否则为 2（已支付 / 未出行）

失败响应

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

{ "code": 0, "msg": "订单已在该营期，无需更换", "data": [] }

错误文案	说明
order_num不能为空 / plu不能为空	参数缺失
订单不存在	order_num 查无订单
订单已退款，不能更换营期	订单 status=6
订单已删除，不能更换营期	订单 status=5
plu不存在:xxx	查无该 plu
新营种不存在或已删除	新 plu 的 pid 查无
新营期不存在	新 plu 的 period_id 查无
找不到新营期对应的skuV2Id,sku_str:xxx	新营期 + 规格无法定位库存规格
订单已在该营期，无需更换	新 pid / period_id / sku_str 与订单当前值完全一致（幂等拦截）

落库行为

订单主表

1. 更新营期 / 营种绑定：pid、pName、period、period_id、sku_str、period_sku_v2_id、product_type、type、form_id、big_form_id；
2. 状态：old_status 存原状态，status 按新营期推算（已结束→4，否则→2）；
3. 亲子转单飞：small_number += big_number、big_number = 0、number = small_number + big_number（仅名额结构变化时同步）；
4. 不动价格：paymoney、all_price、order_agio、sale_price、post_price 等金额字段保持原值。

营员报名表

• 按订单批量打标记（记录原营期 id），保留营员已填数据，不删除、不迁移。

库存迁移

• 营期已报名人数（事务内）：老营期释放（防负）、新营期占用；
• 库存服务 skuV2（事务提交后）：老营期回滚（库存增加）、新营期扣减（库存减少），均不校验余量。

退保（事务提交后）

• 当 new_period_id != old_period_id 时，退掉原营期保险；失败仅记日志。

注意

换营只改营期绑定与库存，不动价格。若新旧营期存在差价，请另行调用 导入订单退款（退差）或收款接口（补差）。

相关接口

• 导入订单（产出 order_num）：导入订单
• 营种详情（取新营期 plu）：获取营种详情
• 换营后处理差价（退差）：导入订单退款
• 编辑 / 添加营员：编辑/添加营员
• 订单数据结构：订单数据结构

变更记录

日期	变更
2026-10-16	首次发布：/api/changeImportOrderPeriod（POST：order_num + plu），透传上游 /Tools/changeImportOrderPeriod。针对线下导入订单的直接落库换营期，允许跨营种：更新订单营期 / 营种绑定字段，不动价格（差价由上游另行处理），迁移库存（老营期回退、新营期占用），营员报名表数据保留仅打原营期标记，核销码不重生成，营期变化事务后退保，亲子转单飞成人并入儿童；库存 / 退保等外部副作用在事务提交后执行