1266 lines
41 KiB
HTML
1266 lines
41 KiB
HTML
<!DOCTYPE html>
|
||
<html lang="zh-CN">
|
||
<head>
|
||
<meta charset="UTF-8">
|
||
<meta name="viewport" content="width=device-width, initial-scale=1.0">
|
||
<title>袋牌模块接口对接文档</title>
|
||
<style>
|
||
* {
|
||
margin: 0;
|
||
padding: 0;
|
||
box-sizing: border-box;
|
||
}
|
||
|
||
body {
|
||
font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, 'Helvetica Neue', Arial, sans-serif;
|
||
line-height: 1.6;
|
||
color: #333;
|
||
background-color: #f5f5f5;
|
||
}
|
||
|
||
.container {
|
||
max-width: 1200px;
|
||
margin: 0 auto;
|
||
padding: 20px;
|
||
}
|
||
|
||
header {
|
||
background-color: #4CAF50;
|
||
color: white;
|
||
padding: 30px 0;
|
||
text-align: center;
|
||
margin-bottom: 30px;
|
||
border-radius: 8px;
|
||
box-shadow: 0 2px 4px rgba(0,0,0,0.1);
|
||
}
|
||
|
||
h1 {
|
||
font-size: 2.5em;
|
||
margin-bottom: 10px;
|
||
}
|
||
|
||
h2 {
|
||
font-size: 2em;
|
||
margin: 40px 0 20px;
|
||
color: #4CAF50;
|
||
border-bottom: 2px solid #4CAF50;
|
||
padding-bottom: 10px;
|
||
}
|
||
|
||
h3 {
|
||
font-size: 1.5em;
|
||
margin: 30px 0 15px;
|
||
color: #333;
|
||
}
|
||
|
||
h4 {
|
||
font-size: 1.2em;
|
||
margin: 20px 0 10px;
|
||
color: #555;
|
||
}
|
||
|
||
p {
|
||
margin-bottom: 15px;
|
||
text-align: justify;
|
||
}
|
||
|
||
.section {
|
||
background-color: white;
|
||
padding: 30px;
|
||
margin-bottom: 20px;
|
||
border-radius: 8px;
|
||
box-shadow: 0 2px 4px rgba(0,0,0,0.1);
|
||
}
|
||
|
||
.table-container {
|
||
overflow-x: auto;
|
||
margin: 20px 0;
|
||
}
|
||
|
||
table {
|
||
width: 100%;
|
||
border-collapse: collapse;
|
||
margin: 20px 0;
|
||
}
|
||
|
||
th, td {
|
||
padding: 12px;
|
||
text-align: left;
|
||
border-bottom: 1px solid #ddd;
|
||
}
|
||
|
||
th {
|
||
background-color: #f2f2f2;
|
||
font-weight: bold;
|
||
}
|
||
|
||
tr:hover {
|
||
background-color: #f5f5f5;
|
||
}
|
||
|
||
.code-block {
|
||
background-color: #f8f8f8;
|
||
border: 1px solid #ddd;
|
||
border-radius: 4px;
|
||
padding: 15px;
|
||
margin: 15px 0;
|
||
font-family: 'Courier New', Courier, monospace;
|
||
white-space: pre-wrap;
|
||
overflow-x: auto;
|
||
}
|
||
|
||
.api-endpoint {
|
||
background-color: #e8f5e8;
|
||
border-left: 4px solid #4CAF50;
|
||
padding: 15px;
|
||
margin: 20px 0;
|
||
border-radius: 0 4px 4px 0;
|
||
}
|
||
|
||
.endpoint-path {
|
||
font-family: 'Courier New', Courier, monospace;
|
||
font-weight: bold;
|
||
color: #4CAF50;
|
||
margin-bottom: 10px;
|
||
}
|
||
|
||
.endpoint-method {
|
||
display: inline-block;
|
||
background-color: #4CAF50;
|
||
color: white;
|
||
padding: 4px 10px;
|
||
border-radius: 4px;
|
||
font-size: 0.9em;
|
||
margin-right: 10px;
|
||
}
|
||
|
||
.example {
|
||
background-color: #f0f8ff;
|
||
border: 1px solid #add8e6;
|
||
border-radius: 4px;
|
||
padding: 15px;
|
||
margin: 15px 0;
|
||
}
|
||
|
||
.example-title {
|
||
font-weight: bold;
|
||
margin-bottom: 10px;
|
||
color: #1e90ff;
|
||
}
|
||
|
||
.note {
|
||
background-color: #fff3cd;
|
||
border: 1px solid #ffeeba;
|
||
border-radius: 4px;
|
||
padding: 15px;
|
||
margin: 15px 0;
|
||
color: #856404;
|
||
}
|
||
|
||
.warning {
|
||
background-color: #f8d7da;
|
||
border: 1px solid #f5c6cb;
|
||
border-radius: 4px;
|
||
padding: 15px;
|
||
margin: 15px 0;
|
||
color: #721c24;
|
||
}
|
||
|
||
ul, ol {
|
||
margin: 15px 0;
|
||
padding-left: 30px;
|
||
}
|
||
|
||
li {
|
||
margin-bottom: 8px;
|
||
}
|
||
|
||
.success {
|
||
color: #28a745;
|
||
}
|
||
|
||
.error {
|
||
color: #dc3545;
|
||
}
|
||
|
||
.info {
|
||
color: #17a2b8;
|
||
}
|
||
</style>
|
||
</head>
|
||
<body>
|
||
<div class="container">
|
||
<header>
|
||
<h1>袋牌模块接口对接文档</h1>
|
||
<p>详细的袋牌模块API接口使用说明</p>
|
||
</header>
|
||
|
||
<div class="section">
|
||
<h2>1. 接口概述</h2>
|
||
<p>袋牌模块提供了一系列RESTful API接口，用于袋牌的生成、打开、关闭以及与尾程运单号的关联操作。本文档详细描述了这些接口的使用方法、请求参数和响应格式。</p>
|
||
|
||
<h3>1.1 接口基础信息</h3>
|
||
<ul>
|
||
<li><strong>基础URL</strong>：<code>http://{服务器地址}:{端口}/api/bagtag</code></li>
|
||
<li><strong>测试环境请求地址</strong>：<code>http://172.232.21.79:5002</code></li>
|
||
<li><strong>正式环境请求地址</strong>：<code>https://lr.tooexp.com</code></li>
|
||
<li><strong>请求方式</strong>：POST/GET</li>
|
||
<li><strong>数据格式</strong>：JSON</li>
|
||
<li><strong>响应格式</strong>：JSON</li>
|
||
</ul>
|
||
|
||
<h3>1.2 状态码说明</h3>
|
||
<div class="table-container">
|
||
<table>
|
||
<thead>
|
||
<tr>
|
||
<th>状态码</th>
|
||
<th>描述</th>
|
||
</tr>
|
||
</thead>
|
||
<tbody>
|
||
<tr>
|
||
<td>200</td>
|
||
<td>操作成功</td>
|
||
</tr>
|
||
<tr>
|
||
<td>400</td>
|
||
<td>请求参数错误或操作失败</td>
|
||
</tr>
|
||
<tr>
|
||
<td>404</td>
|
||
<td>资源不存在</td>
|
||
</tr>
|
||
<tr>
|
||
<td>500</td>
|
||
<td>服务器内部错误</td>
|
||
</tr>
|
||
</tbody>
|
||
</table>
|
||
</div>
|
||
</div>
|
||
|
||
<div class="section">
|
||
<h2>2. 接口详细说明</h2>
|
||
|
||
<div class="api-endpoint">
|
||
<h3>2.1 生成袋牌号</h3>
|
||
<div class="endpoint-path">
|
||
<span class="endpoint-method">POST</span>
|
||
<span>/generate</span>
|
||
</div>
|
||
<p>根据渠道商名称和数量生成袋牌号</p>
|
||
|
||
<h4>请求参数</h4>
|
||
<div class="table-container">
|
||
<table>
|
||
<thead>
|
||
<tr>
|
||
<th>参数名</th>
|
||
<th>类型</th>
|
||
<th>必填</th>
|
||
<th>描述</th>
|
||
<th>示例值</th>
|
||
</tr>
|
||
</thead>
|
||
<tbody>
|
||
<tr>
|
||
<td>ChannelName</td>
|
||
<td>string</td>
|
||
<td>是</td>
|
||
<td>渠道商名称</td>
|
||
<td>"USPS"</td>
|
||
</tr>
|
||
<tr>
|
||
<td>Count</td>
|
||
<td>int</td>
|
||
<td>否</td>
|
||
<td>生成数量，默认1</td>
|
||
<td>5</td>
|
||
</tr>
|
||
<tr>
|
||
<td>Creator</td>
|
||
<td>string</td>
|
||
<td>是</td>
|
||
<td>创建人</td>
|
||
<td>"test_user"</td>
|
||
</tr>
|
||
</tbody>
|
||
</table>
|
||
</div>
|
||
|
||
<h4>请求示例</h4>
|
||
<div class="code-block">
|
||
{
|
||
"ChannelName": "USPS",
|
||
"Count": 3,
|
||
"Creator": "test_user"
|
||
}
|
||
</div>
|
||
|
||
<h4>响应格式</h4>
|
||
<p><strong>成功响应</strong>：</p>
|
||
<div class="code-block">
|
||
{
|
||
"code": 0,
|
||
"data": [
|
||
"USPS202601271200000001",
|
||
"USPS202601271200000002",
|
||
"USPS202601271200000003"
|
||
],
|
||
"message": "Bag tags generated successfully"
|
||
}
|
||
</div>
|
||
|
||
<p><strong>失败响应</strong>：</p>
|
||
<div class="code-block">
|
||
{
|
||
"code": 9999,
|
||
"message": "错误信息"
|
||
}
|
||
</div>
|
||
</div>
|
||
|
||
<div class="api-endpoint">
|
||
<h3>2.2 打开袋牌</h3>
|
||
<div class="endpoint-path">
|
||
<span class="endpoint-method">POST</span>
|
||
<span>/open</span>
|
||
</div>
|
||
<p>将袋牌状态设置为"打开"</p>
|
||
|
||
<h4>请求参数</h4>
|
||
<div class="table-container">
|
||
<table>
|
||
<thead>
|
||
<tr>
|
||
<th>参数名</th>
|
||
<th>类型</th>
|
||
<th>必填</th>
|
||
<th>描述</th>
|
||
<th>示例值</th>
|
||
</tr>
|
||
</thead>
|
||
<tbody>
|
||
<tr>
|
||
<td>TagNumber</td>
|
||
<td>string</td>
|
||
<td>是</td>
|
||
<td>袋牌号</td>
|
||
<td>"USPS202601271200000001"</td>
|
||
</tr>
|
||
</tbody>
|
||
</table>
|
||
</div>
|
||
|
||
<h4>请求示例</h4>
|
||
<div class="code-block">
|
||
{
|
||
"TagNumber": "USPS202601271200000001"
|
||
}
|
||
</div>
|
||
|
||
<h4>响应格式</h4>
|
||
<p><strong>成功响应</strong>：</p>
|
||
<div class="code-block">
|
||
{
|
||
"code": 0,
|
||
"message": "Bag tag opened successfully",
|
||
"data": {
|
||
"waybillCount": 10
|
||
}
|
||
}
|
||
</div>
|
||
|
||
<p><strong>失败响应</strong>：</p>
|
||
<div class="code-block">
|
||
{
|
||
"code": 1001,
|
||
"message": "Failed to open bag tag. It may not exist or closed.",
|
||
"data": {}
|
||
}
|
||
</div>
|
||
</div>
|
||
|
||
<div class="api-endpoint">
|
||
<h3>2.3 关闭袋牌</h3>
|
||
<div class="endpoint-path">
|
||
<span class="endpoint-method">POST</span>
|
||
<span>/close</span>
|
||
</div>
|
||
<p>将袋牌状态设置为"关闭"</p>
|
||
|
||
<h4>请求参数</h4>
|
||
<div class="table-container">
|
||
<table>
|
||
<thead>
|
||
<tr>
|
||
<th>参数名</th>
|
||
<th>类型</th>
|
||
<th>必填</th>
|
||
<th>描述</th>
|
||
<th>示例值</th>
|
||
</tr>
|
||
</thead>
|
||
<tbody>
|
||
<tr>
|
||
<td>TagNumber</td>
|
||
<td>string</td>
|
||
<td>是</td>
|
||
<td>袋牌号</td>
|
||
<td>"USPS202601271200000001"</td>
|
||
</tr>
|
||
</tbody>
|
||
</table>
|
||
</div>
|
||
|
||
<h4>请求示例</h4>
|
||
<div class="code-block">
|
||
{
|
||
"TagNumber": "USPS202601271200000001"
|
||
}
|
||
</div>
|
||
|
||
<h4>响应格式</h4>
|
||
<p><strong>成功响应</strong>：</p>
|
||
<div class="code-block">
|
||
{
|
||
"code": 0,
|
||
"message": "Bag tag closed successfully",
|
||
"data": {
|
||
"waybillCount": 10
|
||
}
|
||
}
|
||
</div>
|
||
|
||
<p><strong>失败响应</strong>：</p>
|
||
<div class="code-block">
|
||
{
|
||
"code": 1002,
|
||
"message": "Failed to close bag tag. It may not exist or already closed.",
|
||
"data": {}
|
||
}
|
||
</div>
|
||
</div>
|
||
|
||
<div class="api-endpoint">
|
||
<h3>2.4 关联尾程运单号</h3>
|
||
<div class="endpoint-path">
|
||
<span class="endpoint-method">POST</span>
|
||
<span>/associate-waybill</span>
|
||
</div>
|
||
<p>将尾程运单号与袋牌建立关联</p>
|
||
|
||
<h4>请求参数</h4>
|
||
<div class="table-container">
|
||
<table>
|
||
<thead>
|
||
<tr>
|
||
<th>参数名</th>
|
||
<th>类型</th>
|
||
<th>必填</th>
|
||
<th>描述</th>
|
||
<th>示例值</th>
|
||
</tr>
|
||
</thead>
|
||
<tbody>
|
||
<tr>
|
||
<td>TagNumber</td>
|
||
<td>string</td>
|
||
<td>是</td>
|
||
<td>袋牌号</td>
|
||
<td>"USPS202601271200000001"</td>
|
||
</tr>
|
||
<tr>
|
||
<td>FinalMileTrackingNumber</td>
|
||
<td>string</td>
|
||
<td>是</td>
|
||
<td>尾程运单号</td>
|
||
<td>"1Z999AA10123456789"</td>
|
||
</tr>
|
||
<tr>
|
||
<td>Creator</td>
|
||
<td>string</td>
|
||
<td>是</td>
|
||
<td>创建人</td>
|
||
<td>"test_user"</td>
|
||
</tr>
|
||
</tbody>
|
||
</table>
|
||
</div>
|
||
|
||
<h4>请求示例</h4>
|
||
<div class="code-block">
|
||
{
|
||
"TagNumber": "USPS202601271200000001",
|
||
"FinalMileTrackingNumber": "1Z999AA10123456789",
|
||
"Creator": "test_user"
|
||
}
|
||
</div>
|
||
|
||
<h4>响应格式</h4>
|
||
<p><strong>成功响应</strong>：</p>
|
||
<div class="code-block">
|
||
{
|
||
"code": 0,
|
||
"message": "Final mile tracking number associated successfully",
|
||
"data": {
|
||
"waybillCount": 10
|
||
}
|
||
}
|
||
</div>
|
||
|
||
<p><strong>失败响应</strong>：</p>
|
||
<div class="code-block">
|
||
{
|
||
"code": 10031,
|
||
"message": "Bag tag not found",
|
||
"data": {}
|
||
}
|
||
</div>
|
||
<div class="code-block">
|
||
{
|
||
"code": 10032,
|
||
"message": "Bag tag is not in opened status",
|
||
"data": {}
|
||
}
|
||
</div>
|
||
<div class="code-block">
|
||
{
|
||
"code": 10033,
|
||
"message": "Channel does not match between bag tag and tracking number",
|
||
"data": {}
|
||
}
|
||
</div>
|
||
<div class="code-block">
|
||
{
|
||
"code": 10035,
|
||
"message": "Waybill is already associated with another bag tag",
|
||
"data": {}
|
||
}
|
||
</div>
|
||
</div>
|
||
|
||
<div class="api-endpoint">
|
||
<h3>2.5 获取袋牌信息</h3>
|
||
<div class="endpoint-path">
|
||
<span class="endpoint-method">GET</span>
|
||
<span>/{tagNumber}</span>
|
||
</div>
|
||
<p>根据袋牌号获取袋牌详细信息，包含关联的小包数量</p>
|
||
|
||
<h4>请求参数</h4>
|
||
<div class="table-container">
|
||
<table>
|
||
<thead>
|
||
<tr>
|
||
<th>参数名</th>
|
||
<th>类型</th>
|
||
<th>必填</th>
|
||
<th>描述</th>
|
||
<th>示例值</th>
|
||
</tr>
|
||
</thead>
|
||
<tbody>
|
||
<tr>
|
||
<td>tagNumber</td>
|
||
<td>string</td>
|
||
<td>是</td>
|
||
<td>袋牌号（路径参数）</td>
|
||
<td>"TESTBAG001"</td>
|
||
</tr>
|
||
</tbody>
|
||
</table>
|
||
</div>
|
||
|
||
<h4>请求示例</h4>
|
||
<div class="code-block">
|
||
GET /api/bagtag/TESTBAG001
|
||
</div>
|
||
|
||
<h4>响应格式</h4>
|
||
<p><strong>成功响应</strong>：</p>
|
||
<div class="code-block">
|
||
{
|
||
"code": 0,
|
||
"message": "success",
|
||
"data": {
|
||
"Id": 1,
|
||
"TagNumber": "TESTBAG001",
|
||
"ChannelName": "USPS",
|
||
"Status": "Opened",
|
||
"Creator": "system",
|
||
"CreatedAt": "2026-01-27T12:00:00Z",
|
||
"OpenedAt": "2026-01-27T12:05:00Z",
|
||
"ClosedAt": null,
|
||
"waybillCount": 10
|
||
}
|
||
}
|
||
</div>
|
||
|
||
<p><strong>失败响应</strong>：</p>
|
||
<div class="code-block">
|
||
{
|
||
"code": 1004,
|
||
"message": "Bag tag not found"
|
||
}
|
||
</div>
|
||
</div>
|
||
|
||
<div class="api-endpoint">
|
||
<h3>2.6 获取袋牌关联的尾程运单号</h3>
|
||
<div class="endpoint-path">
|
||
<span class="endpoint-method">GET</span>
|
||
<span>/{tagNumber}/waybills</span>
|
||
</div>
|
||
<p>获取指定袋牌关联的所有尾程运单号</p>
|
||
|
||
<h4>请求参数</h4>
|
||
<div class="table-container">
|
||
<table>
|
||
<thead>
|
||
<tr>
|
||
<th>参数名</th>
|
||
<th>类型</th>
|
||
<th>必填</th>
|
||
<th>描述</th>
|
||
<th>示例值</th>
|
||
</tr>
|
||
</thead>
|
||
<tbody>
|
||
<tr>
|
||
<td>tagNumber</td>
|
||
<td>string</td>
|
||
<td>是</td>
|
||
<td>袋牌号（路径参数）</td>
|
||
<td>"USPS202601271200000001"</td>
|
||
</tr>
|
||
</tbody>
|
||
</table>
|
||
</div>
|
||
|
||
<h4>请求示例</h4>
|
||
<div class="code-block">
|
||
GET /api/bagtag/USPS202601271200000001/waybills
|
||
</div>
|
||
|
||
<h4>响应格式</h4>
|
||
<p><strong>成功响应</strong>：</p>
|
||
<div class="code-block">
|
||
{
|
||
"status": "success",
|
||
"data": [
|
||
{
|
||
"Id": 1,
|
||
"TagNumber": "USPS202601271200000001",
|
||
"FinalMileTrackingNumber": "1Z999AA10123456789",
|
||
"CreatedAt": "2026-01-27T12:10:00Z"
|
||
},
|
||
{
|
||
"Id": 2,
|
||
"TagNumber": "USPS202601271200000001",
|
||
"FinalMileTrackingNumber": "1Z999AA10123456790",
|
||
"CreatedAt": "2026-01-27T12:15:00Z"
|
||
}
|
||
]
|
||
}
|
||
</div>
|
||
|
||
<p><strong>失败响应</strong>：</p>
|
||
<div class="code-block">
|
||
{
|
||
"status": "error",
|
||
"message": "错误信息"
|
||
}
|
||
</div>
|
||
</div>
|
||
|
||
<div class="api-endpoint">
|
||
<h3>2.7 查询袋牌关联小包数量</h3>
|
||
<div class="endpoint-path">
|
||
<span class="endpoint-method">GET</span>
|
||
<span>/{tagNumber}/waybill-count</span>
|
||
</div>
|
||
<p>查询指定袋牌关联的小包数量</p>
|
||
|
||
<h4>请求参数</h4>
|
||
<div class="table-container">
|
||
<table>
|
||
<thead>
|
||
<tr>
|
||
<th>参数名</th>
|
||
<th>类型</th>
|
||
<th>必填</th>
|
||
<th>描述</th>
|
||
<th>示例值</th>
|
||
</tr>
|
||
</thead>
|
||
<tbody>
|
||
<tr>
|
||
<td>tagNumber</td>
|
||
<td>string</td>
|
||
<td>是</td>
|
||
<td>袋牌号（路径参数）</td>
|
||
<td>"TESTBAG001"</td>
|
||
</tr>
|
||
</tbody>
|
||
</table>
|
||
</div>
|
||
|
||
<h4>Mock数据</h4>
|
||
<div class="table-container">
|
||
<table>
|
||
<thead>
|
||
<tr>
|
||
<th>袋牌号</th>
|
||
<th>返回数量</th>
|
||
</tr>
|
||
</thead>
|
||
<tbody>
|
||
<tr>
|
||
<td>TESTBAG001</td>
|
||
<td>10</td>
|
||
</tr>
|
||
<tr>
|
||
<td>TESTBAG002</td>
|
||
<td>5</td>
|
||
</tr>
|
||
<tr>
|
||
<td>TESTBAG003</td>
|
||
<td>0</td>
|
||
</tr>
|
||
</tbody>
|
||
</table>
|
||
</div>
|
||
|
||
<h4>请求示例</h4>
|
||
<div class="code-block">
|
||
GET /api/bagtag/TESTBAG001/waybill-count
|
||
</div>
|
||
|
||
<h4>响应格式</h4>
|
||
<p><strong>成功响应</strong>：</p>
|
||
<div class="code-block">
|
||
{
|
||
"code": 0,
|
||
"message": "success",
|
||
"data": {
|
||
"tagNumber": "USPS202601271200000001",
|
||
"waybillCount": 5
|
||
}
|
||
}
|
||
</div>
|
||
|
||
<p><strong>失败响应</strong>：</p>
|
||
<div class="code-block">
|
||
{
|
||
"code": 9999,
|
||
"message": "错误信息"
|
||
}
|
||
</div>
|
||
</div>
|
||
|
||
<div class="api-endpoint">
|
||
<h3>2.8 移除袋牌和小包关联</h3>
|
||
<div class="endpoint-path">
|
||
<span class="endpoint-method">POST</span>
|
||
<span>/remove-waybill</span>
|
||
</div>
|
||
<p>移除袋牌和小包的关联关系</p>
|
||
|
||
<h4>请求参数</h4>
|
||
<div class="table-container">
|
||
<table>
|
||
<thead>
|
||
<tr>
|
||
<th>参数名</th>
|
||
<th>类型</th>
|
||
<th>必填</th>
|
||
<th>描述</th>
|
||
<th>示例值</th>
|
||
</tr>
|
||
</thead>
|
||
<tbody>
|
||
<tr>
|
||
<td>TagNumber</td>
|
||
<td>string</td>
|
||
<td>是</td>
|
||
<td>袋牌号</td>
|
||
<td>"TESTBAG001"</td>
|
||
</tr>
|
||
<tr>
|
||
<td>FinalMileTrackingNumber</td>
|
||
<td>string</td>
|
||
<td>是</td>
|
||
<td>尾程运单号</td>
|
||
<td>"TESTWAYBILL001"</td>
|
||
</tr>
|
||
</tbody>
|
||
</table>
|
||
</div>
|
||
|
||
<h4>Mock数据</h4>
|
||
<div class="table-container">
|
||
<table>
|
||
<thead>
|
||
<tr>
|
||
<th>袋牌号</th>
|
||
<th>尾程运单号</th>
|
||
<th>返回结果</th>
|
||
</tr>
|
||
</thead>
|
||
<tbody>
|
||
<tr>
|
||
<td>TESTBAG001</td>
|
||
<td>TESTWAYBILL001</td>
|
||
<td>成功</td>
|
||
</tr>
|
||
<tr>
|
||
<td>TESTBAG001</td>
|
||
<td>TESTWAYBILL999</td>
|
||
<td>失败（运单未关联）</td>
|
||
</tr>
|
||
<tr>
|
||
<td>TESTBAG999</td>
|
||
<td>任意</td>
|
||
<td>失败（袋牌不存在）</td>
|
||
</tr>
|
||
</tbody>
|
||
</table>
|
||
</div>
|
||
|
||
<h4>请求示例</h4>
|
||
<div class="code-block">
|
||
{
|
||
"TagNumber": "TESTBAG001",
|
||
"FinalMileTrackingNumber": "TESTWAYBILL001"
|
||
}
|
||
</div>
|
||
|
||
<h4>响应格式</h4>
|
||
<p><strong>成功响应</strong>：</p>
|
||
<div class="code-block">
|
||
{
|
||
"code": 0,
|
||
"message": "Waybill removed from bag tag successfully"
|
||
}
|
||
</div>
|
||
|
||
<p><strong>失败响应</strong>：</p>
|
||
<div class="code-block">
|
||
{
|
||
"code": 10031,
|
||
"message": "Bag tag not found"
|
||
}
|
||
</div>
|
||
<div class="code-block">
|
||
{
|
||
"code": 10032,
|
||
"message": "Bag tag is not in opened status"
|
||
}
|
||
</div>
|
||
<div class="code-block">
|
||
{
|
||
"code": 10034,
|
||
"message": "Waybill is not associated with this bag tag"
|
||
}
|
||
</div>
|
||
</div>
|
||
|
||
<div class="api-endpoint">
|
||
<h3>2.9 根据扫描单号查询袋牌与小包关联信息</h3>
|
||
<div class="endpoint-path">
|
||
<span class="endpoint-method">GET</span>
|
||
<span>/waybill/{finalMileTrackingNumber}</span>
|
||
</div>
|
||
<p>根据尾程运单号查询袋牌与小包的关联信息</p>
|
||
|
||
<h4>请求参数</h4>
|
||
<div class="table-container">
|
||
<table>
|
||
<thead>
|
||
<tr>
|
||
<th>参数名</th>
|
||
<th>类型</th>
|
||
<th>必填</th>
|
||
<th>描述</th>
|
||
<th>示例值</th>
|
||
</tr>
|
||
</thead>
|
||
<tbody>
|
||
<tr>
|
||
<td>finalMileTrackingNumber</td>
|
||
<td>string</td>
|
||
<td>是</td>
|
||
<td>尾程运单号（路径参数）</td>
|
||
<td>"1Z999AA10123456789"</td>
|
||
</tr>
|
||
</tbody>
|
||
</table>
|
||
</div>
|
||
|
||
<h4>请求示例</h4>
|
||
<div class="code-block">
|
||
GET /api/bagtag/waybill/1Z999AA10123456789
|
||
</div>
|
||
|
||
<h4>响应格式</h4>
|
||
<p><strong>成功响应</strong>：</p>
|
||
<div class="code-block">
|
||
{
|
||
"code": 0,
|
||
"message": "success",
|
||
"data": {
|
||
"Id": 1,
|
||
"TagNumber": "USPS202601271200000001",
|
||
"FinalMileTrackingNumber": "1Z999AA10123456789",
|
||
"Creator": "system",
|
||
"CreatedAt": "2026-01-27T12:10:00Z",
|
||
"Remark": null,
|
||
"bagTag": {
|
||
"ChannelName": "USPS",
|
||
"Status": "Opened",
|
||
"OpenedAt": "2026-01-27T12:05:00Z",
|
||
"ClosedAt": null
|
||
}
|
||
}
|
||
}
|
||
</div>
|
||
|
||
<p><strong>失败响应</strong>：</p>
|
||
<div class="code-block">
|
||
{
|
||
"code": 10036,
|
||
"message": "Waybill not associated with any bag tag"
|
||
}
|
||
</div>
|
||
</div>
|
||
|
||
<div class="api-endpoint">
|
||
<h3>2.10 袋牌标签打印</h3>
|
||
<div class="endpoint-path">
|
||
<span class="endpoint-method">GET</span>
|
||
<span>/{tagNumber}/print</span>
|
||
</div>
|
||
<p>打印袋牌标签，返回PDF格式的袋牌字节流</p>
|
||
|
||
<h4>请求参数</h4>
|
||
<div class="table-container">
|
||
<table>
|
||
<thead>
|
||
<tr>
|
||
<th>参数名</th>
|
||
<th>类型</th>
|
||
<th>必填</th>
|
||
<th>描述</th>
|
||
<th>示例值</th>
|
||
</tr>
|
||
</thead>
|
||
<tbody>
|
||
<tr>
|
||
<td>tagNumber</td>
|
||
<td>string</td>
|
||
<td>是</td>
|
||
<td>袋牌号（路径参数）</td>
|
||
<td>"USPS202601271200000001"</td>
|
||
</tr>
|
||
</tbody>
|
||
</table>
|
||
</div>
|
||
|
||
<h4>请求示例</h4>
|
||
<div class="code-block">
|
||
GET /api/bagtag/USPS202601271200000001/print
|
||
</div>
|
||
|
||
<h4>响应格式</h4>
|
||
<p><strong>成功响应</strong>：</p>
|
||
<ul>
|
||
<li>响应类型：<code>application/pdf</code></li>
|
||
<li>响应内容：袋牌标签的PDF字节流</li>
|
||
<li>文件名：<code>bag_tag_{tagNumber}.pdf</code></li>
|
||
</ul>
|
||
|
||
<p><strong>失败响应</strong>：</p>
|
||
<ul>
|
||
<li>响应类型：<code>application/pdf</code></li>
|
||
<li>响应内容：空字节流</li>
|
||
</ul>
|
||
</div>
|
||
|
||
<div class="api-endpoint">
|
||
<h3>2.11 查询可用袋牌</h3>
|
||
<div class="endpoint-path">
|
||
<span class="endpoint-method">GET</span>
|
||
<span>/available</span>
|
||
</div>
|
||
<p>查询指定渠道的可用袋牌（已关闭且未绑定到出库交接单的袋牌）</p>
|
||
|
||
<h4>请求参数</h4>
|
||
<div class="table-container">
|
||
<table>
|
||
<thead>
|
||
<tr>
|
||
<th>参数名</th>
|
||
<th>类型</th>
|
||
<th>必填</th>
|
||
<th>描述</th>
|
||
<th>示例值</th>
|
||
</tr>
|
||
</thead>
|
||
<tbody>
|
||
<tr>
|
||
<td>channel</td>
|
||
<td>string</td>
|
||
<td>是</td>
|
||
<td>渠道商名称</td>
|
||
<td>"USPS"</td>
|
||
</tr>
|
||
</tbody>
|
||
</table>
|
||
</div>
|
||
|
||
<h4>请求示例</h4>
|
||
<div class="code-block">
|
||
GET /api/bagtag/available?channel=USPS
|
||
</div>
|
||
|
||
<h4>响应格式</h4>
|
||
<p><strong>成功响应</strong>：</p>
|
||
<div class="code-block">
|
||
{
|
||
"code": 0,
|
||
"message": "success",
|
||
"data": [
|
||
{
|
||
"id": 1,
|
||
"tagNumber": "USPS202601271200000001",
|
||
"channelName": "USPS",
|
||
"status": "Closed",
|
||
"creator": "system",
|
||
"createdAt": "2026-01-27T12:00:00Z",
|
||
"openedAt": "2026-01-27T12:05:00Z",
|
||
"closedAt": "2026-01-27T12:30:00Z",
|
||
"waybillCount": 10
|
||
}
|
||
]
|
||
}
|
||
</div>
|
||
|
||
<p><strong>失败响应</strong>：</p>
|
||
<div class="code-block">
|
||
{
|
||
"code": 400,
|
||
"message": "Channel parameter is required"
|
||
}
|
||
</div>
|
||
<div class="code-block">
|
||
{
|
||
"code": 9999,
|
||
"message": "错误信息"
|
||
}
|
||
</div>
|
||
</div>
|
||
</div>
|
||
|
||
<div class="section">
|
||
<h2>3. 接口调用示例</h2>
|
||
|
||
<h3>3.1 使用cURL调用</h3>
|
||
|
||
<h4>生成袋牌号</h4>
|
||
<div class="code-block">
|
||
curl -X POST "http://localhost:5003/api/bagtag/generate" \
|
||
-H "Content-Type: application/json" \
|
||
-d '{"ChannelName": "USPS", "Count": 2}'
|
||
</div>
|
||
|
||
<h4>打开袋牌</h4>
|
||
<div class="code-block">
|
||
curl -X POST "http://localhost:5003/api/bagtag/open" \
|
||
-H "Content-Type: application/json" \
|
||
-d '{"TagNumber": "USPS202601271200000001"}'
|
||
</div>
|
||
|
||
<h4>关联尾程运单号</h4>
|
||
<div class="code-block">
|
||
curl -X POST "http://localhost:5003/api/bagtag/associate-waybill" \
|
||
-H "Content-Type: application/json" \
|
||
-d '{"TagNumber": "USPS202601271200000001", "FinalMileTrackingNumber": "1Z999AA10123456789"}'
|
||
</div>
|
||
|
||
<h3>3.2 使用PowerShell调用</h3>
|
||
|
||
<h4>生成袋牌号</h4>
|
||
<div class="code-block">
|
||
Invoke-RestMethod -Uri "http://localhost:5003/api/bagtag/generate" `
|
||
-Method POST `
|
||
-ContentType "application/json" `
|
||
-Body '{"ChannelName": "USPS", "Count": 2}'
|
||
</div>
|
||
|
||
<h4>打开袋牌</h4>
|
||
<div class="code-block">
|
||
Invoke-RestMethod -Uri "http://localhost:5003/api/bagtag/open" `
|
||
-Method POST `
|
||
-ContentType "application/json" `
|
||
-Body '{"TagNumber": "USPS202601271200000001"}'
|
||
</div>
|
||
|
||
<h4>关联尾程运单号</h4>
|
||
<div class="code-block">
|
||
Invoke-RestMethod -Uri "http://localhost:5003/api/bagtag/associate-waybill" `
|
||
-Method POST `
|
||
-ContentType "application/json" `
|
||
-Body '{"TagNumber": "USPS202601271200000001", "FinalMileTrackingNumber": "1Z999AA10123456789"}'
|
||
</div>
|
||
</div>
|
||
|
||
<div class="section">
|
||
<h2>4. 业务流程示例</h2>
|
||
|
||
<h3>4.1 完整业务流程</h3>
|
||
<ol>
|
||
<li><strong>生成袋牌</strong>：根据渠道商生成袋牌号</li>
|
||
<li><strong>打开袋牌</strong>：将袋牌状态设置为"打开"</li>
|
||
<li><strong>关联尾程运单号</strong>：将尾程运单号与袋牌建立关联</li>
|
||
<li><strong>关闭袋牌</strong>：当袋牌使用完毕后，将其状态设置为"关闭"</li>
|
||
</ol>
|
||
|
||
<h3>4.2 流程示例</h3>
|
||
<div class="code-block">
|
||
# 1. 生成袋牌
|
||
POST /api/bagtag/generate
|
||
{"ChannelName": "UPS", "Count": 1}
|
||
|
||
# 2. 打开袋牌
|
||
POST /api/bagtag/open
|
||
{"TagNumber": "UPS202601271200000001"}
|
||
|
||
# 3. 关联尾程运单号
|
||
POST /api/bagtag/associate-waybill
|
||
{"TagNumber": "UPS202601271200000001", "FinalMileTrackingNumber": "1Z888BB20234567890"}
|
||
|
||
# 4. 关闭袋牌
|
||
POST /api/bagtag/close
|
||
{"TagNumber": "UPS202601271200000001"}
|
||
</div>
|
||
</div>
|
||
|
||
<div class="section">
|
||
<h2>5. 注意事项</h2>
|
||
|
||
<h3>5.1 袋牌状态管理</h3>
|
||
<ul>
|
||
<li>只有状态为"Generated"的袋牌才能被打开</li>
|
||
<li>只有状态为"Opened"的袋牌才能关联尾程运单号</li>
|
||
<li>只有状态为"Opened"的袋牌才能被关闭</li>
|
||
<li>已关闭的袋牌不能再次打开或关联尾程运单号</li>
|
||
</ul>
|
||
|
||
<h3>5.2 袋牌号唯一性</h3>
|
||
<ul>
|
||
<li>系统确保生成的袋牌号唯一</li>
|
||
<li>袋牌号格式：`{渠道商名称}{时间戳}{序号}`</li>
|
||
<li>时间戳精确到秒，序号为4位数字</li>
|
||
</ul>
|
||
|
||
<h3>5.3 数据验证</h3>
|
||
<ul>
|
||
<li>渠道商名称不能为空</li>
|
||
<li>袋牌号不能为空且必须存在</li>
|
||
<li>尾程运单号不能为空</li>
|
||
<li>生成数量必须为正整数</li>
|
||
</ul>
|
||
|
||
<h3>5.4 性能考虑</h3>
|
||
<ul>
|
||
<li>批量生成袋牌时，建议单次生成数量不超过100个</li>
|
||
<li>频繁的袋牌操作可能会影响系统性能，建议合理控制调用频率</li>
|
||
</ul>
|
||
</div>
|
||
|
||
<div class="section">
|
||
<h2>6. 常见问题</h2>
|
||
|
||
<h3>6.1 生成袋牌失败</h3>
|
||
<p><strong>可能原因</strong>：</p>
|
||
<ul>
|
||
<li>渠道商名称为空</li>
|
||
<li>生成数量为负数或零</li>
|
||
</ul>
|
||
<p><strong>解决方案</strong>：</p>
|
||
<ul>
|
||
<li>确保渠道商名称不为空</li>
|
||
<li>确保生成数量为正整数</li>
|
||
</ul>
|
||
|
||
<h3>6.2 打开袋牌失败</h3>
|
||
<p><strong>可能原因</strong>：</p>
|
||
<ul>
|
||
<li>袋牌不存在</li>
|
||
<li>袋牌已被打开</li>
|
||
<li>袋牌已被关闭</li>
|
||
</ul>
|
||
<p><strong>解决方案</strong>：</p>
|
||
<ul>
|
||
<li>检查袋牌号是否正确</li>
|
||
<li>检查袋牌当前状态</li>
|
||
</ul>
|
||
|
||
<h3>6.3 关联尾程运单号失败</h3>
|
||
<p><strong>可能原因</strong>：</p>
|
||
<ul>
|
||
<li>袋牌不存在</li>
|
||
<li>袋牌未被打开</li>
|
||
<li>袋牌已被关闭</li>
|
||
</ul>
|
||
<p><strong>解决方案</strong>：</p>
|
||
<ul>
|
||
<li>检查袋牌号是否正确</li>
|
||
<li>确保袋牌状态为"Opened"</li>
|
||
</ul>
|
||
|
||
<h3>6.4 关闭袋牌失败</h3>
|
||
<p><strong>可能原因</strong>：</p>
|
||
<ul>
|
||
<li>袋牌不存在</li>
|
||
<li>袋牌未被打开</li>
|
||
<li>袋牌已被关闭</li>
|
||
</ul>
|
||
<p><strong>解决方案</strong>：</p>
|
||
<ul>
|
||
<li>检查袋牌号是否正确</li>
|
||
<li>确保袋牌状态为"Opened"</li>
|
||
</ul>
|
||
</div>
|
||
|
||
<div class="section">
|
||
<h2>7. 接口版本管理</h2>
|
||
<div class="table-container">
|
||
<table>
|
||
<thead>
|
||
<tr>
|
||
<th>版本</th>
|
||
<th>变更内容</th>
|
||
<th>发布日期</th>
|
||
</tr>
|
||
</thead>
|
||
<tbody>
|
||
<tr>
|
||
<td>v1.0</td>
|
||
<td>初始版本，包含所有基础接口</td>
|
||
<td>2026-01-27</td>
|
||
</tr>
|
||
</tbody>
|
||
</table>
|
||
</div>
|
||
</div>
|
||
|
||
<div class="section">
|
||
<h2>8. 联系信息</h2>
|
||
<p>如有接口使用问题，请联系系统管理员或开发团队。</p>
|
||
</div>
|
||
</div>
|
||
</body>
|
||
</html> |