316702372/anxinyan
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat: add open warehouse list api

Browse Source
This commit is contained in:
wushumin
2026-06-18 13:56:20 +08:00
parent a982ee2b60
commit 9aa7788b7f
6 changed files with 307 additions and 34 deletions
Download Patch File Download Diff File Expand all files Collapse all files

135
docs/api/third-party-openapi.md
View File

@@ -1,7 +1,7 @@
# 第三方订单对接文档
版本：v1.2
更新日期：2026-06-16
版本：v1.3
更新日期：2026-06-18
## 1. 对接说明
@@ -177,7 +177,76 @@ GET 请求参与签名的 `raw_body` 为空字符串，`path_with_query` 需要
- `price_package_code` 可直接作为创建订单接口的 `price_package_code` 参数。
- `default_price_package_code` 表示该服务方当前默认套餐；创建订单不传 `price_package_code` 时，平台会使用当前服务方默认启用套餐。
## 5. 创建订单
## 5. 仓库地址列表
第三方创建订单或通知寄入物流前，可以调用本接口获取当前可寄送的安心验仓库地址列表。
```text
GET /api/open/v1/warehouses
```
### 5.1 查询参数
| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `service_provider` | string | 否 | 服务方，可选 `anxinyan`、`zhongjian`；不传返回全部启用仓库 |
### 5.2 cURL 示例
```bash
curl -X GET 'https://{api-domain}/api/open/v1/warehouses?service_provider=anxinyan' \
-H 'Content-Type: application/json' \
-H 'X-AXY-App-Key: your_app_key' \
-H 'X-AXY-Timestamp: 1778227200' \
-H 'X-AXY-Nonce: random_nonce' \
-H 'X-AXY-Signature: calculated_signature'
```
GET 请求参与签名的 `raw_body` 为空字符串，`path_with_query` 需要包含实际查询字符串。
### 5.3 成功响应示例
```json
{
"code": 0,
"message": "ok",
"data": {
"warehouses": [
{
"id": 1,
"warehouse_name": "安心验鉴定中心",
"warehouse_code": "AXY-WH-DEFAULT",
"service_provider": "anxinyan",
"service_provider_text": "实物鉴定",
"receiver_name": "安心验鉴定中心",
"receiver_mobile": "400-800-1314",
"province": "广东省",
"city": "深圳市",
"district": "南山区",
"detail_address": "科技园鉴定路 88 号 安心验收件中心",
"full_address": "广东省深圳市南山区科技园鉴定路 88 号 安心验收件中心",
"service_time": "周一至周日 09:30-18:30",
"notice": "寄送前请确认订单信息完整，包裹内附上订单号可提升签收后的处理效率。",
"supported_category_ids": [],
"supported_category_names": [],
"service_area_provinces": [],
"service_area_cities": [],
"is_default": true,
"sort_order": 1
}
]
}
}
```
### 5.4 响应说明
- 接口只返回启用仓库，不返回停用仓库。
- `warehouse_code` 可用于第三方系统识别仓库；寄件时请以接口返回的收件人、手机号和地址为准。
- `supported_category_ids`、`service_area_provinces`、`service_area_cities` 为空数组时表示不限制对应条件。
- 响应不包含后台备注、启停状态和创建更新时间等内部管理字段。
## 6. 创建订单
```text
POST /api/open/v1/orders
@@ -185,7 +254,7 @@ POST /api/open/v1/orders
第三方创建订单时，最小只需要传 `external_order_no`。平台会创建一笔待寄送商品订单；如请求中包含套餐、物品、地址、资料或寄入物流，平台会同步写入订单主表、商品资料、寄回地址、初始鉴定资料和寄入物流记录。
### 5.1 请求参数
### 6.1 请求参数
| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
@@ -200,7 +269,7 @@ POST /api/open/v1/orders
| `tracking_no` | string | 否 | 寄入运单号，可替代 `inbound_logistics.tracking_no` |
| `extra_info` | object | 否 | 购买、成色、附件、备注等扩展信息 |
### 5.3 单独设置寄回地址
### 6.2 单独设置寄回地址
```text
POST /api/open/v1/orders/return-address
@@ -208,14 +277,14 @@ POST /api/open/v1/orders/return-address
第三方可以在建单后单独补录或更新寄回地址。订单已生成回寄运单后，不允许再修改。
### 5.4 请求参数
### 6.3 请求参数
| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `external_order_no` | string | 是 | 第三方订单号 |
| `return_address` | object | 是 | 寄回地址，字段要求同创建订单接口 |
### 5.5 请求示例
### 6.4 请求示例
```json
{
@@ -231,7 +300,7 @@ POST /api/open/v1/orders/return-address
}
```
### 5.2 可选对象字段
### 6.5 可选对象字段
`product_info` 支持：
@@ -298,7 +367,7 @@ POST /api/open/v1/orders/return-address
如果希望创建订单时同步写入寄入物流，需要同时提供快递公司和运单号。也可以直接使用顶层 `express_company` 和 `tracking_no`，含义与 `inbound_logistics` 内字段一致。
### 5.3 最小请求示例
### 6.6 最小请求示例
```json
{
@@ -306,7 +375,7 @@ POST /api/open/v1/orders/return-address
}
```
### 5.4 带可选字段请求示例
### 6.7 带可选字段请求示例
```json
{
@@ -355,7 +424,7 @@ POST /api/open/v1/orders/return-address
}
```
### 5.5 cURL 示例
### 6.8 cURL 示例
```bash
curl -X POST 'https://{api-domain}/api/open/v1/orders' \
@@ -367,7 +436,7 @@ curl -X POST 'https://{api-domain}/api/open/v1/orders' \
-d '{"external_order_no":"THIRD202605080001"}'
```
### 5.6 成功响应示例
### 6.9 成功响应示例
```json
{
@@ -413,7 +482,7 @@ curl -X POST 'https://{api-domain}/api/open/v1/orders' \
}
```
### 5.7 幂等规则
### 6.10 幂等规则
同一个对接客户下，`external_order_no` 作为幂等键：
@@ -424,11 +493,11 @@ curl -X POST 'https://{api-domain}/api/open/v1/orders' \
建议第三方重试创建订单时保持请求 JSON 内容一致，仅重新生成 `timestamp`、`nonce` 和 `signature`。
## 6. 查询订单
## 7. 查询订单
支持按第三方订单号或平台订单号查询订单进度。
### 6.1 按第三方订单号查询
### 7.1 按第三方订单号查询
```text
GET /api/open/v1/orders/{external_order_no}
@@ -445,14 +514,14 @@ curl -X GET 'https://{api-domain}/api/open/v1/orders/THIRD202605080001' \
-H 'X-AXY-Signature: calculated_signature'
```
### 6.2 通过查询参数查询
### 7.2 通过查询参数查询
```text
GET /api/open/v1/orders?external_order_no=THIRD202605080001
GET /api/open/v1/orders?order_no=AXY20260508120000123
```
### 6.3 响应示例
### 7.3 响应示例
```json
{
@@ -507,7 +576,7 @@ GET /api/open/v1/orders?order_no=AXY20260508120000123
}
```
## 7. 取消订单
## 8. 取消订单
第三方订单尚未寄送前，可以调用本接口取消订单。取消成功后订单状态变为 `cancelled`，后台待处理鉴定任务会同步移除。
@@ -515,14 +584,14 @@ GET /api/open/v1/orders?order_no=AXY20260508120000123
POST /api/open/v1/orders/cancel
```
### 7.1 请求参数
### 8.1 请求参数
| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `external_order_no` | string | 是 | 第三方订单号。只能取消当前 `app_key` 所属客户下的订单 |
| `cancel_reason` | string | 否 | 取消原因，最长 255 个字符 |
### 7.2 请求示例
### 8.2 请求示例
```json
{
@@ -531,7 +600,7 @@ POST /api/open/v1/orders/cancel
}
```
### 7.3 成功响应示例
### 8.3 成功响应示例
```json
{
@@ -560,7 +629,7 @@ POST /api/open/v1/orders/cancel
}
```
### 7.4 取消规则
### 8.4 取消规则
- 仅 `pending_shipping` 且尚未提交寄入运单的订单允许取消。
- 创建订单时已传 `inbound_logistics`，或已调用发货通知接口提交 `express_company`、`tracking_no` 的订单不允许取消，返回 `422`。
@@ -569,7 +638,7 @@ POST /api/open/v1/orders/cancel
- 重复取消已取消订单会返回成功，`data.cancelled` 为 `false`，不会重复写入取消时间线。
- 取消接口不触发 webhook 回调；调用方以接口响应或订单查询结果为准。
## 8. 发货通知
## 9. 发货通知
第三方在商品实际寄出后，可以调用本接口通知平台写入寄入物流。创建订单接口中的 `inbound_logistics` 仍然可用；但如果订单创建和商品寄出不是同一时点，建议创建订单时只建单，实际寄出后再调用本接口提交快递信息。
@@ -577,7 +646,7 @@ POST /api/open/v1/orders/cancel
POST /api/open/v1/orders/shipping
```
### 8.1 请求参数
### 9.1 请求参数
| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
@@ -585,7 +654,7 @@ POST /api/open/v1/orders/shipping
| `express_company` | string | 是 | 寄入快递公司 |
| `tracking_no` | string | 是 | 寄入运单号 |
### 8.2 请求示例
### 9.2 请求示例
```json
{
@@ -595,7 +664,7 @@ POST /api/open/v1/orders/shipping
}
```
### 8.3 成功响应示例
### 9.3 成功响应示例
```json
{
@@ -630,14 +699,14 @@ POST /api/open/v1/orders/shipping
}
```
### 8.4 重复提交规则
### 9.4 重复提交规则
- 相同 `external_order_no`、`express_company`、`tracking_no` 重复提交时，接口返回成功，`idempotent` 为 `true`，不会重复写物流节点或订单时间线。
- 同一订单在 `pending_shipping` 状态下提交不同快递公司或运单号时，会更新最新一条寄入物流，`updated` 为 `true`，并追加“已更新运单”时间线。
- 非 `pending_shipping` 状态的订单不允许提交或更新寄入运单，返回 `422`。
- 找不到当前客户下的 `external_order_no` 时返回 `404`。
## 9. 订单状态
## 10. 订单状态
常见订单状态如下，最终以接口返回的 `order_status` 和 `display_status` 为准。
@@ -653,7 +722,7 @@ POST /api/open/v1/orders/shipping
| `pending_supplement` | 需要补充资料 | 需要补充资料 |
| `cancelled` | 已取消 | 订单已取消 |
## 10. Webhook 事件回调
## 11. Webhook 事件回调
如需接收订单状态变化通知，第三方需向平台提供可公网访问的 `webhook_url`，并由平台开启回调。
@@ -674,7 +743,7 @@ POST /api/open/v1/orders/shipping
| 总超时 | 6 秒 |
| 成功判定 | HTTP 状态码为 2xx 且无网络错误 |
### 10.1 回调报文
### 11.1 回调报文
```json
{
@@ -693,7 +762,7 @@ POST /api/open/v1/orders/shipping
}
```
### 10.2 事件类型
### 11.2 事件类型
| event_code | event_text | status_code | status_text |
| --- | --- | --- | --- |
@@ -706,7 +775,7 @@ POST /api/open/v1/orders/shipping
| `completed` | 订单已完成 | `completed` | 已完成 |
| `supplement_required` | 需要补充资料 | `pending_supplement` | 需要补充资料 |
### 10.3 回调接收建议
### 11.3 回调接收建议
第三方接收 webhook 时建议：
@@ -714,7 +783,7 @@ POST /api/open/v1/orders/shipping
- 收到事件后返回 HTTP 2xx。
- 如需强一致的最新状态，可以收到 webhook 后再调用订单查询接口确认。
## 11. 对接流程建议
## 12. 对接流程建议
1. 平台分配 `app_key` 和 `app_secret`。
2. 第三方完成签名调试。