到货及出库模块接口对接文档

详细的到货及出库模块API接口使用说明

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": "错误信息"
}
                

业务规则

一旦执行确认出库操作后，系统不允许对同一交接单再次执行出库操作
每次出库操作至少关联一个袋牌信息
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. 联系信息

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