# 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. 完善请求/响应示例 | 系统生成