# Label Replace API Documentation
# 标签替换接口文档

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

## 请求信息

### URL
```
POST http://172.232.21.79:5002/api/tag/label-replace
```

### 请求方法
`POST`

### 请求头
```
Content-Type: application/json
customer_code: string // 客户代码（可选）
api_key: string // API密钥（可选）
```

| 头字段名 | 类型 | 必填 | 描述 |
|----------|------|------|------|
| Content-Type | string | 是 | 请求体类型，固定为application/json |
| customer_code | string | 否 | 客户代码，用于API身份验证 |
| api_key | string | 否 | API密钥，用于API身份验证 |

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

### 请求示例

#### 正常换单请求

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

#### 冻结换单请求

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

#### 修改数据请求

```json
{
  "NeutralWaybillNumber": "NW1234567890",
  "BillOfLadingNumber": "BL87654321",
  "MasterPackageNumber": "MP23456789",
  "ReferenceNumber": "ORD654321",
  "FinalMileTrackingNumber": "FM9876543210"
}
```

## 响应信息

### 成功响应

#### 响应状态码
`200 OK`

#### 响应头
```
Content-Type: application/json
```

#### 响应参数
| 字段名 | 类型 | 描述 |
|--------|------|------|
| status | string | 状态，成功为"ok" |
| timestamp | string | 响应时间戳（UTC） |
| neutralWaybillNumber | string | 请求中的中性面单单号 |
| replaceStatus | string | 实际使用的换单状态 |
| labelReplaced | boolean | 标签是否成功替换（正常换单为true，冻结换单为false） |
| message | string | 响应消息 |

#### 成功响应示例

##### 正常换单响应
```json
{
  "status": "ok",
  "timestamp": "2026-01-13T12:34:56",
  "neutralWaybillNumber": "NW1234567890",
  "replaceStatus": "Y",
  "labelReplaced": true,
  "message": "Label replacement request processed successfully"
}
```

##### 冻结换单响应

```json
{
  "status": "ok",
  "timestamp": "2026-01-13T12:34:56",
  "neutralWaybillNumber": "NW1234567890",
  "replaceStatus": "N",
  "labelReplaced": false,
  "message": "Label replacement request has been frozen"
}
```

##### 修改数据成功响应

```json
{
  "status": "ok",
  "timestamp": "2026-01-20T14:30:00",
  "neutralWaybillNumber": "NW1234567890",
  "replaceStatus": "Y",
  "labelReplaced": true,
  "message": "Label replacement data updated successfully"
}
```

### 错误响应

#### 响应状态码
`400 Bad Request`

#### 错误响应示例

##### 缺少必填字段
```json
{
  "status": "error",
  "message": "Neutral waybill number is required"
}
```

##### 请求体为空
```json
{
  "status": "error",
  "message": "Neutral waybill number is required"
}
```

##### 无效的换单状态
```json
{
  "status": "error",
  "message": "Invalid replace status. Use 'Y' for normal replacement or 'N' for frozen replacement"
}
```

##### 标签已返回无法修改
```json
{
  "status": "error",
  "message": "Label has been returned and cannot be modified"
}
```

##### 服务器错误
```json
{
  "status": "error",
  "message": "具体错误信息"
}
```

## 注意事项

1. **必填字段**：必须提供`NeutralWaybillNumber`字段
2. **换单状态**：如果提供`ReplaceStatus`字段，只能是"Y"或"N"，默认为"Y"
3. **数据格式**：所有字符串字段应确保格式正确
4. **标签内容**：如果提供`Label`字段，应确保其为有效的格式（如base64编码的PDF）
5. **并发处理**：接口设计支持并发请求，每个请求相互独立
6. **错误处理**：所有错误都会返回适当的HTTP状态码和详细的错误消息
7. **修改支持**：接口支持通过提供`NeutralWaybillNumber`来修改已存在的订单数据
8. **修改限制**：如果标签已被返回（即该订单存在扫描结果为"已返回面单"的记录），则无法修改该订单数据
9. **字段长度**：除`Label`字段外，所有字符串字段的长度限制为100字符

## 批量查询换单状态接口

### URL
```
GET http://172.232.21.79:5002/api/Label/label-replace/status
```

### 请求方法
`GET`

### 请求头
| 头字段名 | 类型 | 必填 | 描述 |
|----------|------|------|------|
| customerCode | string | 是 | 客户代码 |
| apiKey | string | 是 | API密钥 |

### 查询参数
| 字段名 | 类型 | 必填 | 描述 |
|--------|------|------|------|
| waybills | string | 否 | 中性面单单号，多个单号用逗号分隔 |
| trackings | string | 否 | 尾程跟踪单号，多个单号用逗号分隔 |

### 请求示例

#### 查询多个中性面单号
```
GET /api/Label/label-replace/status?waybills=WB1234567890,WB0987654321
Headers:
  customerCode: TEST_CUSTOMER
  apiKey: test_api_key
```

#### 查询多个尾程跟踪单号
```
GET /api/Label/label-replace/status?trackings=TN9876543210,TN1234567890
Headers:
  customerCode: TEST_CUSTOMER
  apiKey: test_api_key
```

#### 混合查询
```
GET /api/Label/label-replace/status?waybills=WB1234567890&trackings=TN9876543210
Headers:
  customerCode: TEST_CUSTOMER
  apiKey: test_api_key
```

### 响应信息

#### 成功响应

##### 响应状态码
`200 OK`

##### 响应参数
| 字段名 | 类型 | 描述 |
|--------|------|------|
| status | string | 状态，成功为"ok" |
| timestamp | string | 响应时间戳（UTC） |
| count | number | 返回结果数量 |
| data | array | 换单状态查询结果列表 |

##### 数据项参数
| 字段名 | 类型 | 描述 |
|--------|------|------|
| waybillNumber | string | 中性面单单号 |
| trackingNumber | string | 尾程跟踪单号 |
| replaced | boolean | 是否换单成功 |
| replacedAt | string | 换单成功时间（UTC），未成功则为null |

##### 成功响应示例

```json
{
  "status": "ok",
  "timestamp": "2026-03-10T10:00:00Z",
  "count": 2,
  "data": [
    {
      "waybillNumber": "WB1234567890",
      "trackingNumber": "TN9876543210",
      "replaced": true,
      "replacedAt": "2026-03-10T09:30:00Z"
    },
    {
      "waybillNumber": "WB0987654321",
      "trackingNumber": "TN1234567890",
      "replaced": false,
      "replacedAt": null
    }
  ]
}
```

#### 错误响应

##### 响应状态码
`200 OK`

##### 错误响应示例

##### 缺少头部参数
```json
{
  "status": "error",
  "message": "customerCode and apiKey are required in headers"
}
```

##### API凭证无效
```json
{
  "status": "error",
  "message": "Invalid API credentials. Please check your customerCode and apiKey."
}
```

##### 缺少查询参数
```json
{
  "status": "error",
  "message": "At least one of waybills or trackings parameter is required"
}
```

##### 服务器错误
```json
{
  "status": "error",
  "message": "An unexpected error occurred.",
  "errorDetails": "详细错误信息"
}
```

## 文档更新日志

| 日期 | 更新内容 | 更新人 |
|------|----------|--------|
| 2026-01-13 | 1. 初始创建文档<br>2. 添加换单状态字段说明<br>3. 完善请求/响应示例 | 系统生成 |
| 2026-01-20 | 1. 添加字段长度限制信息<br>2. 添加修改订单数据的支持说明<br>3. 添加修改数据的限制条件（标签已返回无法修改）<br>4. 添加标签已返回无法修改的错误响应示例<br>5. 完善注意事项部分<br>6. 添加修改数据请求示例<br>7. 添加修改数据成功响应示例<br>8. 添加API请求头信息（customer_code和api_key字段） | 系统生成 |
| 2026-03-10 | 1. 添加批量查询换单状态接口文档 | 系统生成 |
