Label Replace API Documentation

标签替换接口文档

接口概述

该接口用于处理标签替换请求，允许客户端提交中性面单号及其他相关信息来请求替换标签，支持正常换单和冻结换单功能。

请求信息

URL

POST http://172.232.21.79:5002/api/tag/label-replace

请求方法

POST

请求头

Content-Type: application/json

请求参数

字段名 类型 长度 必填 描述
BillOfLadingNumber string 100 否 提单号
MasterPackageNumber string 100 否 大包号
ReferenceNumber string 100 否 参考号（一般表示订单号）
NeutralWaybillNumber string 100 是 中性面单单号（必填）
FinalMileTrackingNumber string 100 否 尾程跟踪单号
Label string Long 否 标签内容（一般为PDF，可能是base64或其他格式）
ReplaceStatus string 1 否 换单状态（Y表示正常换单，N表示冻结换单，默认为Y）

请求示例

正常换单请求

{
  "BillOfLadingNumber": "BL12345678",
  "MasterPackageNumber": "MP98765432",
  "ReferenceNumber": "ORD123456",
  "NeutralWaybillNumber": "NW1234567890",
  "FinalMileTrackingNumber": "FM1234567890",
  "Label": "base64_encoded_pdf_content",
  "ReplaceStatus": "Y"
}

冻结换单请求

{
  "NeutralWaybillNumber": "NW1234567890",
  "ReplaceStatus": "N"
}

响应信息

成功响应

响应状态码

200 OK

响应头

Content-Type: application/json

响应参数

字段名 类型 长度 描述
status string 5 状态，成功为"ok"
timestamp string 20 响应时间戳（UTC）
id integer 10 记录ID（数据库主键）
neutralWaybillNumber string 100 请求中的中性面单单号
replaceStatus string 1 实际使用的换单状态
labelReplaced boolean - 标签是否成功替换（正常换单为true，冻结换单为false）
message string 200 响应消息

成功响应示例

正常换单响应
{
  "status": "ok",
  "timestamp": "2026-01-13T12:34:56",
  "neutralWaybillNumber": "NW1234567890",
  "replaceStatus": "Y",
  "labelReplaced": true,
  "message": "Label replacement request processed successfully"
}
冻结换单响应
{
  "status": "ok",
  "timestamp": "2026-01-13T12:34:56",
  "neutralWaybillNumber": "NW1234567890",
  "replaceStatus": "N",
  "labelReplaced": false,
  "message": "Label replacement request has been frozen"
}

错误响应

响应状态码

400 Bad Request

错误响应示例

缺少必填字段
{
  "status": "error",
  "message": "Neutral waybill number is required"
}
请求体为空
{
  "status": "error",
  "message": "Neutral waybill number is required"
}
无效的换单状态
{
  "status": "error",
  "message": "Invalid replace status. Use 'Y' for normal replacement or 'N' for frozen replacement"
}
服务器错误
{
  "status": "error",
  "message": "具体错误信息"
}

注意事项

  1. 必填字段：必须提供NeutralWaybillNumber字段
  2. 换单状态：如果提供ReplaceStatus字段，只能是"Y"或"N"，默认为"Y"
  3. 数据格式：所有字符串字段应确保格式正确
  4. 标签内容：如果提供Label字段，应确保其为有效的格式（如base64编码的PDF）
  5. 并发处理：接口设计支持并发请求，每个请求相互独立
  6. 错误处理：所有错误都会返回适当的HTTP状态码和详细的错误消息

文档更新日志

日期 更新内容 更新人
2026-01-13 1. 初始创建文档
2. 添加换单状态字段说明
3. 完善请求/响应示例		 系统生成