## 1. 接口概述

到货及出库模块提供了一系列RESTful API接口，用于到货交接单和出库交接单的创建、查询、更新以及与袋牌的关联操作。本文档详细描述了这些接口的使用方法、请求参数和响应格式。

### 1.1 接口基础信息

- 基础URL：`http://{服务器地址}:{端口}/api/shipping-handover`
- 测试环境请求地址：`http://172.232.21.79:5002`
- 正式环境请求地址：`https://lr.tooexp.com`
- 请求方式：POST/GET
- 数据格式：JSON
- 响应格式：JSON

### 1.2 状态码说明

状态码 | 描述
--- | ---
200 | 操作成功
400 | 请求参数错误或操作失败
404 | 资源不存在
500 | 服务器内部错误

## 2. 接口详细说明

### 2.1 到货交接单模块

#### 2.1.1 查询到货交接单信息

POST /receipt-query

根据到货编号查询到货交接单详细信息，包括包裹数、已有标签率、到货时间等

##### 请求参数

参数名 | 类型 | 必填 | 描述 | 示例值
--- | --- | --- | --- | ---
arrivalNumber | string | 是 | 到货编号（提单号或大箱号） | "TEST1ZX30Y730494260906"
callback | string | 否 | JSONP回调函数 | "callback"

##### 请求体示例

{ "arrivalNumber": "TEST1ZX30Y730494260906", "callback": null }

##### Mock数据

到货编号 | 包裹数 | 已有标签率 | 到货时间 | 提单号 | 大箱号
--- | --- | --- | --- | --- | ---
TEST1ZX30Y730494260906 | 1200 | 0.8 | 1744032000000 | TEST1ZX30Y730494260906 | testS169-3-20-2-1
TEST1ZX30Y730494260907 | - | - | - | TEST1ZX30Y730494260907 | -

##### 请求示例

POST /api/arrival-handover/receipt-query Content-Type: application/json { "arrivalNumber": "TEST1ZX30Y730494260906" }

##### 响应格式

成功响应：

{ "code": 0, "message": "success", "data": { "packageCount": 1200, "labelRate": 0.8, "arrivalTime": 1744032000000, "billOfLadingNumber": "TEST1ZX30Y730494260906", "masterPackageNumber": "testS169-3-20-2-1" } }

##### 响应字段说明

字段名 | 类型 | 描述
--- | --- | ---
packageCount | int | 包裹总数
labelRate | double | 已有标签率
arrivalTime | long? | 到货时间戳（毫秒，UTC）
billOfLadingNumber | string | 提单号
masterPackageNumber | string | 大箱号

失败响应：

{ "code": 9999, "message": "无预报数据", "data": { "billOfLadingNumber": "TEST1ZX30Y730494260907", "masterPackageNumber": "" } }

### 2.2 出库交接单模块

#### 2.2.1 查询出库交接单详细信息

GET /details/{handoverNumber}

根据出库交接单号查询详细信息，包括BOL单号、渠道商、袋牌数量、总包裹数和交接单状态

##### 请求参数

参数名 | 类型 | 必填 | 描述 | 示例值
--- | --- | --- | --- | ---
handoverNumber | string | 是 | 出库交接单号（路径参数） | "TESTBOL001"
callback | string | 否 | JSONP回调函数 | "callback"

##### Mock数据

出库交接单号 | 渠道商 | 袋牌数量 | 总包裹数 | 状态
--- | --- | --- | --- | ---
TESTBOL001 | GOFO | 3 | 150 | Draft
TESTBOL002 | USPS | 5 | 250 | Draft
TESTBOL003 | UPS | 0 | 0 | Draft

##### 请求示例

GET /api/shipping-handover/details/TESTBOL001

##### 响应格式

成功响应：

{ "code": 0, "message": "success", "data": { "handoverNumber": "TESTBOL001", "channel": "GOFO", "bagTagCount": 3, "totalPackageCount": 150, "status": "Draft" } }

##### 响应字段说明

字段名 | 类型 | 描述
--- | --- | ---
handoverNumber | string | 交接单号
channel | string | 渠道商
bagTagCount | int | 袋牌数量
totalPackageCount | int | 总包裹数
status | string | 状态

失败响应：

{ "code": 9999, "message": "Shipping handover form not found" }

#### 2.2.2 确认出库交接单

POST /confirm

确认出库交接单，将状态从草稿修改为已出库

##### 请求参数

参数名 | 类型 | 必填 | 描述 | 示例值
--- | --- | --- | --- | ---
handoverNumber | string | 是 | 出库交接单号 | "TESTBOL001"
deliveryTime | long? | 否 | 出货时间戳（毫秒，UTC） | 1744032000000
pod | string | 是 | POD图片链接，至少包含两张图片，用逗号分隔 | "https://example.com/pod1.jpg,https://example.com/pod2.jpg"
callback | string | 否 | JSONP回调函数 | "callback"

##### 请求体示例

{ "handoverNumber": "TESTBOL001", "deliveryTime": 1744032000000, "pod": "https://example.com/pod1.jpg,https://example.com/pod2.jpg", "callback": null }

##### Mock数据

出库交接单号 | 操作结果
--- | ---
TESTBOL001 | 成功
TESTBOL002 | 成功
TESTBOL003 | 成功

##### 请求示例

POST /api/shipping-handover/confirm Content-Type: application/json { "handoverNumber": "TESTBOL001", "deliveryTime": 1744032000000, "pod": "https://example.com/pod1.jpg,https://example.com/pod2.jpg" }

##### 响应格式

成功响应：

{ "code": 0, "message": "success", "data": true }

##### 响应字段说明

字段名 | 类型 | 描述
--- | --- | ---
data | bool | 操作结果

失败响应：

{ "code": 9999, "message": "错误信息" }

##### 业务规则

1. 一旦执行确认出库操作后，系统不允许对同一交接单再次执行出库操作
2. 每次出库操作至少关联一个袋牌信息
3. POD字段必须至少包含两张图片的S3链接

#### 2.2.3 创建出库交接单

GET /create

创建出库交接单

##### 请求参数

参数名 | 类型 | 必填 | 描述 | 示例值
--- | --- | --- | --- | ---
HandoverNumber | string | 否 | 交接单号，为空时自动生成 | "BOL-ORD-GOFO-20260325-001"
Channel | string | 是 | 渠道 | "GOFO"
DeliveryTime | DateTime? | 否 | 交货时间 | "2026-05-08T10:00:00Z"
POD | string | 否 | POD图片链接 | "https://example.com/pod1.jpg,https://example.com/pod2.jpg"
Remarks | string | 否 | 备注 | "测试备注"
Creator | string | 是 | 创建人 | "test_user"
TimeZone | string | 是 | 时区 | "America/New_York"
callback | string | 否 | JSONP回调函数 | "callback"

##### 请求示例

GET /api/shipping-handover/create?Channel=GOFO&Creator=test_user&TimeZone=America/New_York

##### 响应格式

成功响应：

{ "code": 0, "message": "success", "data": 1 }

##### 响应字段说明

字段名 | 类型 | 描述
--- | --- | ---
data | int | 新增记录ID

失败响应：

{ "code": 9999, "message": "错误信息" }

#### 2.2.4 获取出库交接单列表

GET /list

获取出库交接单列表，支持分页和筛选

##### 请求参数

参数名 | 类型 | 必填 | 描述 | 示例值
--- | --- | --- | --- | ---
page | int | 否 | 页码，默认1 | 1
pageSize | int | 否 | 每页数量，默认10 | 10
sortBy | string | 否 | 排序字段，默认CreatedAt | "CreatedAt"
sortOrder | string | 否 | 排序方向，默认desc | "desc"
handoverNumber | string | 否 | 交接单号 | "BOL-ORD-GOFO-20260325-001"
channel | string | 否 | 渠道 | "GOFO"
creator | string | 否 | 创建人 | "test_user"
startDeliveryTime | DateTime? | 否 | 开始交货时间 | "2026-05-08T10:00:00Z"
endDeliveryTime | DateTime? | 否 | 结束交货时间 | "2026-05-09T10:00:00Z"
callback | string | 否 | JSONP回调函数 | "callback"

##### 请求示例

GET /api/shipping-handover/list?page=1&pageSize=10&channel=GOFO

##### 响应格式

成功响应：

{ "code": 0, "message": "success", "data": { "forms": [ { "Id": 1, "HandoverNumber": "BOL-ORD-GOFO-20260325-001", "BigBagCount": 3, "SmallBagCount": 150, "Channel": "GOFO", "DeliveryTime": 1744032000000, "POD": "https://example.com/pod1.jpg", "Remarks": "测试备注", "Creator": "test_user", "CreatedAt": 1744032000000, "UpdatedAt": 1744032000000, "TimeZone": "America/New_York", "Status": 0 } ], "totalCount": 1 } }

##### 响应字段说明

字段名 | 类型 | 描述
--- | --- | ---
forms | array | 交接单列表
totalCount | int | 总记录数

##### ShippingHandoverFormEntity 字段说明

字段名 | 类型 | 描述
--- | --- | ---
Id | int | 主键ID
HandoverNumber | string | 交接单号
BigBagCount | int | 袋牌数量
SmallBagCount | int | 包裹数量
Channel | string | 渠道
DeliveryTime | long? | 交货时间戳（毫秒，UTC）
POD | string | POD图片链接
Remarks | string | 备注
Creator | string | 创建人
CreatedAt | long | 创建时间戳（毫秒，UTC）
UpdatedAt | long | 更新时间戳（毫秒，UTC）
TimeZone | string | 时区
Status | int | 状态（0=草稿，1=已出库）

失败响应：

{ "code": 9999, "message": "错误信息" }

### 2.3 出库交接单与袋牌关联模块

#### 2.3.1 关联袋牌到出货交接单

POST /bag-tag/associate/{shippingHandoverFormId}

关联袋牌到出货交接单

##### 请求参数

参数名 | 类型 | 必填 | 描述 | 示例值
--- | --- | --- | --- | ---
shippingHandoverFormId | int | 是 | 出货交接单ID（路径参数） | 1
bagTagIds | List<int> | 是 | 袋牌ID列表（请求体） | [1, 2, 3]

##### 请求示例

POST /api/shipping-handover/bag-tag/associate/1 Content-Type: application/json [1, 2, 3]

##### 响应格式

成功响应：

{ "code": 0, "message": "success", "data": true }

失败响应：

{ "code": 9999, "message": "错误信息" }

#### 2.3.2 获取出货交接单关联的袋牌列表

GET /bag-tag/list/{shippingHandoverFormId}

获取出货交接单关联的袋牌列表

##### 请求参数

参数名 | 类型 | 必填 | 描述 | 示例值
--- | --- | --- | --- | ---
shippingHandoverFormId | int | 是 | 出货交接单ID（路径参数） | 1
callback | string | 否 | JSONP回调函数 | "callback"

##### 请求示例

GET /api/shipping-handover/bag-tag/list/1

##### 响应格式

成功响应：

{ "code": 0, "message": "success", "data": [ { "Id": 1, "TagNumber": "USPS202601271200000001", "ChannelName": "USPS", "Status": "Closed", "Creator": "system", "CreatedAt": 1706361600000, "OpenedAt": 1706361900000, "ClosedAt": 1706363400000 } ] }

##### BagTagEntity 字段说明

字段名 | 类型 | 描述
--- | --- | ---
Id | int | 主键ID
TagNumber | string | 袋牌号
ChannelName | string | 渠道名
Status | string | 状态
Creator | string | 创建人
CreatedAt | long | 创建时间戳（毫秒，UTC）
OpenedAt | long? | 开袋时间戳（毫秒，UTC）
ClosedAt | long? | 封袋时间戳（毫秒，UTC）

失败响应：

{ "code": 9999, "message": "错误信息" }

#### 2.3.3 从出货交接单中移除袋牌

GET /bag-tag/remove/{relationId}

从出货交接单中移除袋牌

##### 请求参数

参数名 | 类型 | 必填 | 描述 | 示例值
--- | --- | --- | --- | ---
relationId | int | 是 | 关联ID（路径参数） | 1
callback | string | 否 | JSONP回调函数 | "callback"

##### 请求示例

GET /api/shipping-handover/bag-tag/remove/1

##### 响应格式

成功响应：

{ "code": 0, "message": "success", "data": true }

失败响应：

{ "code": 9999, "message": "错误信息" }

#### 2.3.4 清空出货交接单的所有袋牌关联

GET /bag-tag/clear/{shippingHandoverFormId}

清空出货交接单的所有袋牌关联

##### 请求参数

参数名 | 类型 | 必填 | 描述 | 示例值
--- | --- | --- | --- | ---
shippingHandoverFormId | int | 是 | 出货交接单ID（路径参数） | 1
callback | string | 否 | JSONP回调函数 | "callback"

##### 请求示例

GET /api/shipping-handover/bag-tag/clear/1

##### 响应格式

成功响应：

{ "code": 0, "message": "success", "data": true }

失败响应：

{ "code": 9999, "message": "错误信息" }

#### 2.3.5 统计出货交接单的袋牌数量和包裹数量

GET /bag-tag/count/{shippingHandoverFormId}

统计出货交接单的袋牌数量和包裹数量

##### 请求参数

参数名 | 类型 | 必填 | 描述 | 示例值
--- | --- | --- | --- | ---
shippingHandoverFormId | int | 是 | 出货交接单ID（路径参数） | 1
callback | string | 否 | JSONP回调函数 | "callback"

##### 请求示例

GET /api/shipping-handover/bag-tag/count/1

##### 响应格式

成功响应：

{ "code": 0, "message": "success", "data": { "bagTagCount": 3, "packageCount": 150 } }

##### 响应字段说明

字段名 | 类型 | 描述
--- | --- | ---
bagTagCount | int | 袋牌数量
packageCount | int | 包裹数量

失败响应：

{ "code": 9999, "message": "错误信息" }

#### 2.3.6 检查袋牌是否已关联到出货交接单

GET /bag-tag/check/{bagTagId}

检查袋牌是否已关联到出货交接单

##### 请求参数

参数名 | 类型 | 必填 | 描述 | 示例值
--- | --- | --- | --- | ---
bagTagId | int | 是 | 袋牌ID（路径参数） | 1
callback | string | 否 | JSONP回调函数 | "callback"

##### 请求示例

GET /api/shipping-handover/bag-tag/check/1

##### 响应格式

成功响应：

{ "code": 0, "message": "success", "data": true }

失败响应：

{ "code": 9999, "message": "错误信息" }

#### 2.3.7 通过袋牌号关联袋牌到出货交接单

GET /bag-tag/associate-by-number/{shippingHandoverFormId}

通过袋牌号关联袋牌到出货交接单

##### 请求参数

参数名 | 类型 | 必填 | 描述 | 示例值
--- | --- | --- | --- | ---
shippingHandoverFormId | int | 是 | 出货交接单ID（路径参数） | 1
bagTagNumbers | string | 是 | 袋牌号列表（逗号分隔） | "USPS202601271200000001,USPS202601271200000002"
callback | string | 否 | JSONP回调函数 | "callback"

##### 请求示例

GET /api/shipping-handover/bag-tag/associate-by-number/1?bagTagNumbers=USPS202601271200000001,USPS202601271200000002

##### 响应格式

成功响应：

{ "code": 0, "message": "success", "data": true }

失败响应：

{ "code": 9999, "message": "错误信息" }

## 3. 接口调用示例

### 3.1 使用cURL调用

#### 查询出库交接单详细信息

curl -X GET "http://localhost:5002/api/shipping-handover/details/TESTBOL001"

#### 创建出库交接单

curl -X GET "http://localhost:5002/api/shipping-handover/create?Channel=GOFO&Creator=test_user&TimeZone=America/New_York"

#### 查询到货交接单信息（POST请求）

curl -X POST "http://localhost:5002/api/arrival-handover/receipt-query" \ -H "Content-Type: application/json" \ -d '{"arrivalNumber": "TEST1ZX30Y730494260906"}'

### 3.2 使用PowerShell调用

#### 查询出库交接单详细信息

Invoke-RestMethod -Uri "http://localhost:5002/api/shipping-handover/details/TESTBOL001" ` -Method GET

#### 创建出库交接单

Invoke-RestMethod -Uri "http://localhost:5002/api/shipping-handover/create?Channel=GOFO&Creator=test_user&TimeZone=America/New_York" ` -Method GET

#### 查询到货交接单信息（POST请求）

$body = @{ arrivalNumber = "TEST1ZX30Y730494260906" } | ConvertTo-Json Invoke-RestMethod -Uri "http://localhost:5002/api/arrival-handover/receipt-query" ` -Method POST ` -Body $body ` -ContentType "application/json"

## 4. 注意事项

### 4.1 数据验证

- 渠道不能为空
- 创建人不能为空
- 时区不能为空
- 时间戳均使用UTC时间（毫秒）

### 4.2 性能考虑

- 批量操作时，建议合理控制数据量
- 频繁的接口调用可能会影响系统性能，建议合理控制调用频率

## 5. 常见问题

### 5.1 创建出库交接单失败

可能原因：

- 渠道为空
- 创建人为空
- 时区为空

解决方案：

- 确保必填参数不为空

### 5.2 查询出库交接单失败

可能原因：

- 出库交接单号不存在

解决方案：

- 检查出库交接单号是否正确

## 6. 接口版本管理

版本 | 变更内容 | 发布日期
--- | --- | ---
v1.5 | 修改确认出库交接单接口的deliveryTime入参为long类型时间戳 | 2026-05-09
v1.4 | 恢复接口入参时间参数类型为DateTime/string，返回值保持为long类型时间戳 | 2026-05-08
v1.3 | 修改确认出库交接单接口为POST方法 | 2026-05-08
v1.2 | 修改receipt-query接口为POST方法，时间字段改为long类型时间戳，增加响应字段类型说明 | 2026-05-08
v1.1 | 新增查询到货交接单信息接口 | 2026-03-25
v1.0 | 初始版本，包含所有基础接口 | 2026-03-25

## 7. 联系信息

如有接口使用问题，请联系系统管理员或开发团队。