feat: add enterprise order cancel open api

2026-06-16 16:35:55 +08:00
parent 9be60fbe17
commit a982ee2b60
5 changed files with 556 additions and 67 deletions
--- a/docs/api/third-party-openapi.md
+++ b/docs/api/third-party-openapi.md
@@ -1,7 +1,7 @@
 # 第三方订单对接文档

-版本：v1.1
-更新日期：2026-06-11
+版本：v1.2
+更新日期：2026-06-16

 ## 1. 对接说明

@@ -507,7 +507,69 @@ GET /api/open/v1/orders?order_no=AXY20260508120000123
 }
 ```

-## 7. 发货通知
+## 7. 取消订单
+
+第三方订单尚未寄送前，可以调用本接口取消订单。取消成功后订单状态变为 `cancelled`，后台待处理鉴定任务会同步移除。
+
+```text
+POST /api/open/v1/orders/cancel
+```
+
+### 7.1 请求参数
+
+| 字段 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `external_order_no` | string | 是 | 第三方订单号。只能取消当前 `app_key` 所属客户下的订单 |
+| `cancel_reason` | string | 否 | 取消原因，最长 255 个字符 |
+
+### 7.2 请求示例
+
+```json
+{
+  "external_order_no": "THIRD202606160001",
+  "cancel_reason": "客户取消鉴定"
+}
+```
+
+### 7.3 成功响应示例
+
+```json
+{
+  "code": 0,
+  "message": "订单已取消",
+  "data": {
+    "cancelled": true,
+    "order": {
+      "customer_id": "CUST001",
+      "customer_code": "CUST001",
+      "external_order_no": "THIRD202606160001",
+      "order_no": "AXY20260616120000123",
+      "order_status": "cancelled",
+      "display_status": "已取消",
+      "payment_status": "paid",
+      "timeline": [
+        {
+          "node_code": "cancelled",
+          "node_text": "订单已取消",
+          "node_desc": "第三方客户取消订单：客户取消鉴定",
+          "occurred_at": "2026-06-16 12:00:00"
+        }
+      ]
+    }
+  }
+}
+```
+
+### 7.4 取消规则
+
+- 仅 `pending_shipping` 且尚未提交寄入运单的订单允许取消。
+- 创建订单时已传 `inbound_logistics`，或已调用发货通知接口提交 `express_company`、`tracking_no` 的订单不允许取消，返回 `422`。
+- 已到仓、鉴定中、补料中、已出报告、已完成等状态不允许取消，返回 `422`。
+- 找不到当前客户下的 `external_order_no` 时返回 `404`。
+- 重复取消已取消订单会返回成功，`data.cancelled` 为 `false`，不会重复写入取消时间线。
+- 取消接口不触发 webhook 回调；调用方以接口响应或订单查询结果为准。
+
+## 8. 发货通知

 第三方在商品实际寄出后，可以调用本接口通知平台写入寄入物流。创建订单接口中的 `inbound_logistics` 仍然可用；但如果订单创建和商品寄出不是同一时点，建议创建订单时只建单，实际寄出后再调用本接口提交快递信息。

@@ -515,7 +577,7 @@ GET /api/open/v1/orders?order_no=AXY20260508120000123
 POST /api/open/v1/orders/shipping
 ```

-### 7.1 请求参数
+### 8.1 请求参数

 | 字段 | 类型 | 必填 | 说明 |
 | --- | --- | --- | --- |
@@ -523,7 +585,7 @@ POST /api/open/v1/orders/shipping
 | `express_company` | string | 是 | 寄入快递公司 |
 | `tracking_no` | string | 是 | 寄入运单号 |

-### 7.2 请求示例
+### 8.2 请求示例

 ```json
 {
@@ -533,7 +595,7 @@ POST /api/open/v1/orders/shipping
 }
 ```

-### 7.3 成功响应示例
+### 8.3 成功响应示例

 ```json
 {
@@ -568,14 +630,14 @@ POST /api/open/v1/orders/shipping
 }
 ```

-### 7.4 重复提交规则
+### 8.4 重复提交规则

 - 相同 `external_order_no`、`express_company`、`tracking_no` 重复提交时，接口返回成功，`idempotent` 为 `true`，不会重复写物流节点或订单时间线。
 - 同一订单在 `pending_shipping` 状态下提交不同快递公司或运单号时，会更新最新一条寄入物流，`updated` 为 `true`，并追加“已更新运单”时间线。
 - 非 `pending_shipping` 状态的订单不允许提交或更新寄入运单，返回 `422`。
 - 找不到当前客户下的 `external_order_no` 时返回 `404`。

-## 8. 订单状态
+## 9. 订单状态

 常见订单状态如下，最终以接口返回的 `order_status` 和 `display_status` 为准。

@@ -589,8 +651,9 @@ POST /api/open/v1/orders/shipping
 | `return_shipped` | 物品已寄回 | 物品已退回寄出 |
 | `completed` | 已完成 | 订单完成 |
 | `pending_supplement` | 需要补充资料 | 需要补充资料 |
+| `cancelled` | 已取消 | 订单已取消 |

-## 9. Webhook 事件回调
+## 10. Webhook 事件回调

 如需接收订单状态变化通知，第三方需向平台提供可公网访问的 `webhook_url`，并由平台开启回调。

@@ -611,7 +674,7 @@ POST /api/open/v1/orders/shipping
 | 总超时 | 6 秒 |
 | 成功判定 | HTTP 状态码为 2xx 且无网络错误 |

-### 9.1 回调报文
+### 10.1 回调报文

 ```json
 {
@@ -630,7 +693,7 @@ POST /api/open/v1/orders/shipping
 }
 ```

-### 9.2 事件类型
+### 10.2 事件类型

 | event_code | event_text | status_code | status_text |
 | --- | --- | --- | --- |
@@ -643,7 +706,7 @@ POST /api/open/v1/orders/shipping
 | `completed` | 订单已完成 | `completed` | 已完成 |
 | `supplement_required` | 需要补充资料 | `pending_supplement` | 需要补充资料 |

-### 9.3 回调接收建议
+### 10.3 回调接收建议

 第三方接收 webhook 时建议：

@@ -651,13 +714,14 @@ POST /api/open/v1/orders/shipping
 - 收到事件后返回 HTTP 2xx。
 - 如需强一致的最新状态，可以收到 webhook 后再调用订单查询接口确认。

-## 10. 对接流程建议
+## 11. 对接流程建议

 1. 平台分配 `app_key` 和 `app_secret`。
 2. 第三方完成签名调试。
 3. 第三方调用套餐获取接口，确认可用套餐和 `price_package_code`。
 4. 第三方调用创建订单接口。最小只传 `external_order_no` 即可；如需要减少后续人工补录，建议同步传 `price_package_code`、`product_info`、`return_address`、`materials` 和 `inbound_logistics`。
-5. 如建单时未提供寄回地址，或后续需要变更，可调用寄回地址接口补录或更新 `return_address`。
-6. 商品实际寄出后，第三方调用发货通知接口提交 `express_company` 和 `tracking_no`。
-7. 第三方可通过查询接口主动查询订单状态，并核对 `return_address`、物流和报告结果。
-8. 如启用 webhook，平台在订单状态变化时主动通知第三方。
+5. 如订单尚未寄送且需要取消，可调用取消订单接口；已提交寄入物流后不再支持取消。
+6. 如建单时未提供寄回地址，或后续需要变更，可调用寄回地址接口补录或更新 `return_address`。
+7. 商品实际寄出后，第三方调用发货通知接口提交 `express_company` 和 `tracking_no`。
+8. 第三方可通过查询接口主动查询订单状态，并核对 `return_address`、物流和报告结果。
+9. 如启用 webhook，平台在订单状态变化时主动通知第三方。