版本：v2.0

导入订单退款

对 导入订单 产生的线下导入订单直接办理退款：sid 为空 / 0 = 整单全退；sid 有值 = 仅退该营员（部分退）。退款金额由调用方显式传入，直接落库、不走财务审批流。

信息

本接口是 导入订单 链路的配套退款接口，仅适用于导入订单；若订单本身只有 1 名营员，退该营员等同整单全退。一般（审批流）退款请关注发起退款回调与订单变更通知。

POST/api/refundOrder

核心语义

两种退款模式：
- sid 空 / 0 → 整单全退：订单 status=6（已退款），回退全部库存与 period.used_count，全员退保，保留营员记录、不减 number。
- sid 有值 → 仅退该营员（部分退）：删除该营员并释放 1 个名额，不改订单状态。
- 特别地，若该订单只有 1 名营员，退这名营员等同整单全退（走整单全退分支，返回 refund_type=full）。
退款金额由上游显式传入：refund_money 须 ≥ 0（可为 0，表示只退营不退款，如免费订单），并校验不超过订单可退额（已付成功金额 - 已退金额）；refund_money=0 时不写资金流水，仅执行退营 / 整单退的业务动作。
退款流水与导入对称：导入收款记 type=46（正数），退款记 type=47（负数），并把 refund_money 累加到订单成功支付流水的 refund_money。
外部副作用后置：库存回退与退保在数据库事务提交之后执行，失败仅记日志，不影响已提交的退款结果。
工具接口契约：code 恒为 0；成功时 msg 为空、data 为退款摘要；失败时 msg 非空、data 为空数组。

请求参数

名称	类型	描述	是否必填	默认值	备注
token	String	身份校验令牌	必填	-	由获取访问令牌获得
order_num	String	订单号	必填	-	`导入订单` 返回的 `order_num`，形如 `NO...`
refund_money	Number	退款金额	必填	-	须 ≥ 0 且 ≤ 订单可退额；可为 0（只退营不退款 / 免费订单），此时不写资金流水
sid	Number	营员 ID	非必填	`0`	有值 = 仅退该营员（须属于该订单，取获取订单营员信息的 `sid`）；空 / `0` = 整单全退

CURL

V1

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

V2（appid 为 `V2` 版本）

curl --location --request POST 'https://open.xinduobang.cn/api/refundOrder' \
--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 'sid=88123' \
--data-urlencode 'refund_money=1000'

信息

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

请求示例

整单全退（不传 `sid`）

POST 字段：order_num=NO20261009103000123456、refund_money=3000。

单营员退款（部分退，传 `sid`）

POST 字段：order_num=NO20261009103000123456、sid=88123、refund_money=1000。

信息

若 sid 指定的营员是订单里唯一一名营员，则按整单全退处理，返回 refund_type=full、order_status=6。

只退营不退款（`refund_money=0`）

POST 字段：order_num=NO20261009103000123456、sid=88123、refund_money=0。用于免费订单或不退款仅退营的场景：执行删除营员 / 释放名额 / 回退库存等业务动作，但不写资金流水。

成功响应

整单全退

{
  "code": 0,
  "msg": "",
  "data": {
    "order_num": "NO20261009103000123456",
    "sid": 0,
    "refund_money": 3000,
    "refundable": 0,
    "refund_type": "full",
    "order_status": 6
  }
}

单营员部分退

{
  "code": 0,
  "msg": "",
  "data": {
    "order_num": "NO20261009103000123456",
    "sid": 88123,
    "refund_money": 1000,
    "refundable": 2000,
    "refund_type": "partial",
    "order_status": 2
  }
}

响应字段说明

键	类型	说明
order_num	String	命中的订单号
sid	Number	入参 `sid` 原样返回（整单全退未指定时为 `0`）
refund_money	Number	本次退款金额
refundable	Number	本次退款后订单的剩余可退额
refund_type	String	`full`=整单全退；`partial`=单营员部分退
order_status	Number	退款后订单状态：`full` 为 `6`（已退款）；`partial` 为原状态（不变）

失败响应

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

{ "code": 0, "msg": "refund_money不能超过可退金额(2000)", "data": [] }

错误文案	说明
`order_num不能为空` / `refund_money不能为空` / `refund_money不能小于0`	参数缺失或非法（`refund_money` 可为 `0`，但不能为负）
`订单不存在`	`order_num` 查无订单
`订单已退款，不能重复退款`	订单 `status` 已为 `6`
`refund_money不能超过可退金额(N)`	传入金额超过 `已付 - 已退`（可退额按 `0` 兜底）
`营员不属于该订单`	`sid` 有值但不属于该订单

落库行为

公共（两种模式都执行）

refund_money=0 时跳过以下资金流水写入，仅执行后续的退营 / 整单退业务动作。

支付流水：把 refund_money 累加到该订单成功支付流水的 refund_money；
资金流水：新增一条 type=47（支出 / 退款）、金额为负数的流水，字段与导入 type=46 对称。

整单全退（`refund_type=full`）

订单：status 置 6（已退款），保留 number/small_number/big_number 与营员记录；
库存回退（提交后）：period.used_count 回退儿童人数，库存服务按儿童 / 成人人数回退；
退保（提交后）：对订单全部营员调用退保。

单营员部分退（`refund_type=partial`）

营员记录：按 orderId + sid 删除该营员行（学员主档保留，可能被其它订单引用）；
退营标记：新增一条退营记录；
名额释放：number 减 1，且按该营员类型（儿童 / 成人）对应人数减 1（防负）；不改 status；
重算：重新计算订单实付总额与在营员参营统计；
库存回退（提交后）：period.used_count 回退 1（仅儿童），库存服务回退 1 个对应名额；
退保（提交后）：对该 sid 调用退保。

注意

部分退会释放名额并回退库存，因此退款后该营位可被重新加人（编辑/添加营员 type=2）。

变更记录

日期	变更
2026-10-12	改造为透传上游 `/Tools/refundImportOrder` 的代理接口：参数由 `ordernum` + `sid` 改为 `order_num` + `refund_money` + 可选 `sid`；`sid` 空 = 整单全退、有值 = 单营员部分退；`refund_money` 校验不超可退额，`refund_money=0` 表示只退营不退款；返回 `data` 退款摘要（`refund_type` / `order_status` / `refundable`）
2026-10-12	`refund_money` 放开为可等于 `0`（只退营不退款 / 免费订单场景）：`refund_money=0` 时跳过资金流水写入，仅执行退营 / 整单退业务动作

核心语义​

请求参数​

CURL​

V1​

V2（appid 为 V2 版本）​

请求示例​

整单全退（不传 sid）​

单营员退款（部分退，传 sid）​

只退营不退款（refund_money=0）​

成功响应​

整单全退​

单营员部分退​

响应字段说明​

失败响应​

落库行为​

公共（两种模式都执行）​

整单全退（refund_type=full）​

单营员部分退（refund_type=partial）​

相关接口​

变更记录​