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

<!-- mipuyun-api-doc: booking-cancel -->
# booking/cancel - 取消订单

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

## 使用场景

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

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

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

## 性能指标

> - 响应速度：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 |

###

### 请求体

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

#### 参数详情

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

## 返回参数

### 成功响应

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

### 失败响应

#### 订单不存在
```json
{
  "code": 1,
  "msg": "Failed to cancel booking"
}
```

### 响应字段说明

| **参数名称** | **类型** | **示例值** | **说明** |
| --- | --- | --- | --- |
| code | Integer | 0 | 系统状态码<br>**0**：取消成功<br>**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）

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

#### 响应（Response）

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

### 行程变更取消订单

#### 请求（Request）

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

#### 响应（Response）

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

### 重复订单取消

#### 请求（Request）

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

#### 响应（Response）

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

### 取消不存在的订单

#### 请求（Request）

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

#### 响应（Response）

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

## 取消原因建议

### 标准取消原因

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

### 详细取消原因

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

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

## 取消最佳实践

### 1. 取消前先查询状态

```javascript
// 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. 记录取消原因

始终提供清晰、准确的取消原因：
```json
{
  "cancelReason": "Customer request - passenger name change needed"
}
```

而不是：
```json
{
  "cancelReason": "Cancel"
}
```

### 3. 处理取消失败

```javascript
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" | 稍后重试或联系技术支持 |