# Label Replace API Documentation

# Eparcel换单交邮接口文档

## 目录

- 接口概述
- 环境URL
- 推送换单数据接口
- 批量查询换单结果接口
- 注意事项
- 文档更新日志

## 接口概述

该接口用于处理标签替换请求，允许客户端提交中性面单号及其他相关信息来请求替换标签，支持正常换单和取消换单功能。同时提供批量查询换单状态的功能，支持输入多个中性面单或尾程单号，查询换单是否成功及成功时间。

## 环境URL

生产环境：`https://lr.tooexp.com`

测试环境：`http://172.232.21.79:5002`

## 标签替换接口

### 请求信息

#### URL

`POST /api/tag/label-replace`

#### 请求方法

`POST`

#### 请求头

    Content-Type: application/json
    customerCode: string // 客户代码
    apiKey: string // API密钥

头字段名 | 类型 | 必填 | 描述
--- | --- | --- | ---
Content-Type | string | 是 | 请求体类型，固定为application/json
customerCode | string | 否 | 客户代码，用于API身份验证
apiKey | 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）

#### 请求示例

##### 正常换单请求

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

##### 取消换单请求

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

##### 修改数据请求

    {
      "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 | 响应消息

##### 成功响应示例

###### 正常换单响应

    {
      "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"
    }

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

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

#### 错误响应

##### 响应状态码

`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": "Label has been returned and cannot be modified"
    }

###### 服务器错误

    {
      "status": "error",
      "message": "具体错误信息"
    }

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

### 请求信息

#### URL

`POST /api/label/label-replace/status`

#### 请求方法

`POST`

#### 请求头

    Content-Type: application/json
    customerCode: string // 客户代码（必填）
    apiKey: string // API密钥（必填）

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

#### 请求参数

字段名 | 类型 | 必填 | 描述
--- | --- | --- | ---
numbers | array | 是 | 单号列表（中性面单或尾程单号）

#### 请求示例

##### 查询多个单号

    {
      "numbers": ["NW1234567890", "FM9876543210", "NW1122334455"]
    }

### 响应信息

#### 成功响应

##### 响应状态码

`200 OK`

##### 响应头

    Content-Type: application/json

##### 响应参数

字段名 | 类型 | 描述
--- | --- | ---
code | integer | HTTP响应码，成功为200
timestamp | string | 响应时间戳（UTC）
count | integer | 返回的结果数量
data | array | 换单状态查询结果列表

##### data数组元素结构

字段名 | 类型 | 描述
--- | --- | ---
WaybillNumber | string | 中性面单单号
TrackingNumber | string | 尾程跟踪单号
Replaced | boolean | 是否换单成功
ReplacedAt | string | 换单成功时间（UTC），未成功则为null

##### 成功响应示例

    {
      "code": 200,
      "timestamp": "2026-03-10T12:34:56",
      "count": 3,
      "data": [
        {
          "WaybillNumber": "NW1234567890",
          "TrackingNumber": "FM1234567890",
          "Replaced": true,
          "ReplacedAt": "2026-03-10T10:15:30"
        },
        {
          "WaybillNumber": "NW9876543210",
          "TrackingNumber": "FM9876543210",
          "Replaced": false,
          "ReplacedAt": null
        },
        {
          "WaybillNumber": "",
          "TrackingNumber": "FM1122334455",
          "Replaced": true,
          "ReplacedAt": "2026-03-09T14:20:15"
        }
      ]
    }

#### 错误响应

##### 响应状态码

`200 OK`（错误信息在响应体中）

##### 错误响应示例

###### 缺少认证信息

    {
      "code": 400,
      "message": "customerCode and apiKey are required in headers"
    }

###### 无效的认证信息

    {
      "code": 401,
      "message": "Invalid API credentials. Please check your customerCode and apiKey."
    }

###### 缺少查询参数

    {
      "code": 400,
      "message": "Numbers parameter is required"
    }

###### 服务器错误

    {
      "code": 500,
      "message": "An unexpected error occurred.",
      "errorDetails": "具体错误信息"
    }

## 注意事项

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

## 文档更新日志

日期 | 更新内容 | 更新人
--- | --- | ---
2026-01-13 | 1. 初始创建文档 2. 添加换单状态字段说明 3. 完善请求/响应示例 | 系统生成
2026-01-20 | 1. 添加字段长度限制信息 2. 添加修改订单数据的支持说明 3. 添加修改数据的限制条件（标签已返回无法修改） 4. 添加标签已返回无法修改的错误响应示例 5. 完善注意事项部分 6. 添加修改数据请求示例 7. 添加修改数据成功响应示例 8. 添加API请求头信息（customerCode和apiKey字段） | 系统生成
2026-03-06 | 1. 统一API请求头字段命名规范，将customer_code改为customerCode 2. 将api_key改为apiKey | 系统生成
2026-03-10 | 1. 添加批量查询换单状态接口文档 2. 完善接口概述部分，添加批量查询功能说明 3. 修改批量查询换单状态接口，将HTTP方法从GET改为POST 4. 将参数从query改为body中的数组形式 | 系统生成
2026-03-10 | 1. 修改批量查询换单状态接口，使用单个数组参数numbers代表中性面单或尾程单号 2. 将响应中的status字段重命名为code，并使用HTTP响应码 3. 所有响应都返回200状态码，具体错误码在响应体的code字段中显示 | 系统生成