init: mipu-open 对外开放项目统一管理仓库
- 添加 mipu-api 作为 git submodule (Claude Code Skill) - 迁移 API 文档源文件到 docs/ 目录统一维护 - 添加 Gitea Actions 工作流：tag推送自动打包docs并发布Release - Skill 运行时自动从 mipu-open Release 下载最新文档 Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
杨柳杰
343
docs/04-04_booking-cancel.md
Normal file
343
docs/04-04_booking-cancel.md
Normal file
@@ -0,0 +1,343 @@
|
||||
<!-- 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" | 稍后重试或联系技术支持 |
|
||||
Reference in New Issue
Block a user