mipu-open/docs/04-04_booking-cancel.md

booking/cancel - 取消订单

取消订单(booking/cancel) API 说明文档

使用场景

1. 客户主动取消未支付的订单
2. 客户因行程变更取消已确认的订单（需符合退改规则）
3. 系统自动取消过期未支付的订单
4. 客服代客取消订单

错误场景(不应该使用本接口的场景)

1. 订单已不可取消（如已起飞航班）
2. 订单不属于当前客户（clientCode 不匹配）
3. 重复取消已取消的订单

性能指标

• 响应速度：98% 的请求响应速度 < 2000ms
• 接口成功率：> 95%

请求说明

请求地址	https://${endpoint}/booking/cancel
请求方法	POST

请求参数

Header

参数名称	类型	是否必选	示例值	说明
Content-Type	String	是	application/json	固定值，指定请求体格式为 JSON
Accept-Encoding	String	是	gzip, deflate, br	必须要填写，否则服务器会拒绝。
client-key	String	是	xxxxx	联系我们获取生产环境 key
client-secret	String	是	xxxxx	联系我们获取生产环境 secret

请求体

{
  "orderId": "abbc4b57fb75",
  "cancelReason": "Customer request - flight change"
}

参数详情

参数名称	类型	是否必选	示例值（默认值）	说明
orderId	String	是	abbc4b57fb75	客户的订单号，用于取消订单
cancelReason	String	是	"Customer request"	取消原因，用于记录和审计 客户主动取消：Customer request 行程变更：Flight change 重复订单：Duplicate booking 支付超时：Payment timeout 其他：Other reason

返回参数

成功响应

{
  "code": 0,
  "msg": "Booking cancelled successfully",
  "historyId": 789
}

失败响应

订单不存在

{
  "code": 1,
  "msg": "Failed to cancel booking"
}

响应字段说明

参数名称	类型	示例值	说明
code	Integer	0	系统状态码 0：取消成功 1：取消失败
msg	String	"Booking cancelled successfully"	系统消息：成功或失败的详细信息
historyId	Long	789	历史记录 ID，用于追踪取消操作记录

业务流程

订单取消流程

1. 客户下单（booking/hold）→ 获取 orderId
         ↓
2. 订单状态变化
         ├─ 未支付超时 → 系统自动取消
         ├─ 客户主动取消 → 调用取消接口
         └─ 行程变更取消 → 调用取消接口
         ↓
3. 调用取消接口（booking/cancel）→ 提供取消原因
         ↓
4a. 成功：code=0，订单状态更新为 CANCELLED
         ↓
4b. 失败：code=1，返回错误信息

取消后状态变化

取消前：
- 状态：PENDING / CONFIRMED
- PNR：已生成（如已确认）

取消后：
- 状态：CANCELLED
- PNR：被航司释放
- 历史记录：保存取消操作记录

常见问题

取消订单后可以恢复吗？

通常不可以。订单一旦取消：

1. PNR 被释放，座位被释放回库存
2. 如果需要恢复，需要重新下单
3. 某些航司可能支持恢复，但需要联系客服处理

哪些订单可以取消？

可以取消的订单：

1. 状态为 PENDING：处理中的订单
2. 状态为 CONFIRMED：已确认但未起飞的订单
3. 符合退改规则：在退改规则允许的时间范围内

不可取消的订单：

1. 已起飞：航班已经起飞
2. 已取消：订单已经被取消过
3. 已使用：乘客已办理登机

cancelReason 有什么用？

cancelReason 用于：

1. 审计追踪：记录取消原因，便于后续分析
2. 统计分析：统计取消原因分布，优化产品
3. 客服支持：客服可以查看取消原因
4. 退款处理：根据取消原因判断是否退款及退款金额

取消成功后如何退款？

取消成功后：

1. 系统会自动触发退款流程
2. 退款金额根据退改规则和取消时间决定
3. 退款通常需要 3-7 个工作日到账
4. 可以通过 booking/query 查询退款状态

重复取消会怎样？

如果订单已经是 CANCELLED 状态：

1. 再次调用取消接口会返回失败（code=1）
2. 不会重复处理退款
3. 建议取消前先通过 booking/query 查询订单状态

业务案例

客户主动取消订单

请求（Request）

{
  "orderId": "abbc4b57fb75",
  "cancelReason": "Customer request - flight change"
}

响应（Response）

{
  "code": 0,
  "msg": "Booking cancelled successfully",
  "historyId": 789
}

行程变更取消订单

请求（Request）

{
  "orderId": "abbc4b57fb75",
  "cancelReason": "Itinerary change - customer requested new dates"
}

响应（Response）

{
  "code": 0,
  "msg": "Booking cancelled successfully",
  "historyId": 790
}

重复订单取消

请求（Request）

{
  "orderId": "abbc4b57fb75",
  "cancelReason": "Duplicate booking - same itinerary booked twice"
}

响应（Response）

{
  "code": 0,
  "msg": "Booking cancelled successfully",
  "historyId": 791
}

取消不存在的订单

请求（Request）

{
  "orderId": "nonexistent-order-id",
  "cancelReason": "Test cancellation"
}

响应（Response）

{
  "code": 1,
  "msg": "Failed to cancel booking"
}

取消原因建议

标准取消原因

场景	建议的 cancelReason	说明
客户主动取消	"Customer request"	客户主动要求取消
行程变更	"Flight change"	客户需要更改行程
重复预订	"Duplicate booking"	同一航班重复预订
支付超时	"Payment timeout"	支付时间超过限制
价格问题	"Price issue"	客户认为价格不合理
个人原因	"Personal reason"	客户个人原因
系统错误	"System error"	系统导致的错误
其他原因	"Other reason"	其他未列出的原因

详细取消原因

建议在标准原因后添加详细说明：

{
  "orderId": "abbc4b57fb75",
  "cancelReason": "Customer request - found better price elsewhere"
}

取消最佳实践

1. 取消前先查询状态

// 1. 先查询订单状态
const order = await bookingQuery({ orderId: "xxx" });

// 2. 确认订单可以取消后再取消
if (order.status === "CONFIRMED" || order.status === "PENDING") {
  const result = await bookingCancel({
    orderId: "xxx",
    cancelReason: "Customer request"
  });

  if (result.code === 0) {
    console.log("取消成功");
  }
}

2. 记录取消原因

始终提供清晰、准确的取消原因：

{
  "cancelReason": "Customer request - passenger name change needed"
}

而不是：

{
  "cancelReason": "Cancel"
}

3. 处理取消失败

const result = await bookingCancel({
  orderId: "xxx",
  cancelReason: "Customer request"
});

if (result.code !== 0) {
  // 记录错误日志
  console.error("取消失败:", result.msg);

  // 联系客服处理
  await contactSupport({
    orderId: "xxx",
    issue: "Cancel failed",
    message: result.msg
  });
}

错误处理

常见错误及处理方式

错误场景	code	msg	处理建议
订单不存在	1	"Failed to cancel booking"	确认 orderId 是否正确
订单已取消	1	"Failed to cancel booking"	先查询订单状态
订单不可取消	1	"Failed to cancel booking"	检查退改规则和航班状态
系统错误	1	"Failed to cancel booking"	稍后重试或联系技术支持