LabelChange-server/接口文档.md

# 标签替换服务接口文档

## 1. 接口概述

本文档描述了标签替换服务提供的RESTful API接口，包括接口地址、请求参数、响应格式和示例等信息。所有接口均遵循RESTful设计原则，使用JSON格式进行数据交换。

## 2. 接口列表

| 接口名称 | 接口地址 | 请求方法 | 功能描述 |
|----------|----------|----------|----------|
| 标签替换 | /api/Tag/replace | POST | 替换文本中的标签变量 |
| 物流消息解析 | /api/Tag/logistics-parse | POST | 解析物流接口消息 |
| 标签替换请求处理 | /api/Tag/label-replace | POST | 处理标签替换请求 |

## 3. 标签替换接口

### 3.1 接口地址
```
POST /api/Tag/replace
```

### 3.2 请求参数

**请求体 (JSON格式):**

| 参数名 | 类型 | 必填 | 描述 |
|--------|------|------|------|
| Id | string | 否 | 请求ID |
| Text | string | 是 | 包含标签的文本 |
| Variables | Dictionary<string, string> | 是 | 标签变量键值对 |

**请求示例:**
```json
{
  "Id": "request-123",
  "Text": "Hello {name}, welcome to {company}!",
  "Variables": {
    "name": "张三",
    "company": "标签替换服务"
  }
}
```

### 3.3 响应参数

**响应体 (JSON格式):**

| 参数名 | 类型 | 描述 |
|--------|------|------|
| status | string | 请求状态，ok表示成功，error表示失败 |
| timestamp | datetime | 响应时间戳 |
| input | string | 输入文本 |
| variables | Dictionary<string, string> | 标签变量 |
| result | string | 替换后的文本 |

**响应示例 (成功):**
```json
{
  "status": "ok",
  "timestamp": "2026-01-16T08:30:00Z",
  "input": "Hello {name}, welcome to {company}!",
  "variables": {
    "name": "张三",
    "company": "标签替换服务"
  },
  "result": "Hello 张三, welcome to 标签替换服务!"
}
```

**响应示例 (失败):**
```json
{
  "status": "error",
  "message": "请求处理失败"
}
```

## 4. 物流消息解析接口

### 4.1 接口地址
```
POST /api/Tag/logistics-parse
```

### 4.2 请求参数

**请求体 (JSON格式):**

| 参数名 | 类型 | 必填 | 描述 |
|--------|------|------|------|
| Id | string | 否 | 请求ID |
| RequestType | string | 是 | 请求类型 |
| LogisticsInterface | string | 是 | 物流接口消息内容 |

**请求示例:**
```json
{
  "Id": "logistics-123",
  "RequestType": "order",
  "LogisticsInterface": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<orderInfo>\n  <orderNo>ORD-20260116-001</orderNo>\n  <consignee>李四</consignee>\n  <phone>13800138000</phone>\n  <address>北京市朝阳区</address>\n</orderInfo>"
}
```

### 4.3 响应参数

**响应体 (JSON格式):**

| 参数名 | 类型 | 描述 |
|--------|------|------|
| status | string | 请求状态，ok表示成功，error表示失败 |
| timestamp | datetime | 响应时间戳 |
| requestId | string | 请求ID |
| requestType | string | 请求类型 |
| parsedData | Dictionary<string, string> | 解析后的物流数据 |

**响应示例 (成功):**
```json
{
  "status": "ok",
  "timestamp": "2026-01-16T08:45:00Z",
  "requestId": "logistics-123",
  "requestType": "order",
  "parsedData": {
    "orderNo": "ORD-20260116-001",
    "consignee": "李四",
    "phone": "13800138000",
    "address": "北京市朝阳区"
  }
}
```

**响应示例 (失败):**
```json
{
  "status": "error",
  "message": "物流接口消息不能为空"
}
```

## 5. 标签替换请求处理接口

### 5.1 接口地址
```
POST /api/Tag/label-replace
```

### 5.2 请求头

| 头名称 | 类型 | 必填 | 描述 |
|--------|------|------|------|
| customer_code | string | 是 | 客户代码 |
| api_key | string | 是 | API密钥 |

### 5.3 请求参数

**请求体 (JSON格式):**

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

**请求示例:**
```json
{
  "BillOfLadingNumber": "BL-2026-001",
  "MasterPackageNumber": "MP-2026-001",
  "ReferenceNumber": "REF-2026-001",
  "NeutralWaybillNumber": "NW-20260116-0001",
  "FinalMileTrackingNumber": "FM-20260116-0001",
  "Label": "base64 encoded PDF content...",
  "ReplaceStatus": "Y"
}
```

### 5.4 响应参数

**响应体 (JSON格式):**

| 参数名 | 类型 | 描述 |
|--------|------|------|
| Status | string | 请求状态，ok表示成功，error表示失败 |
| Timestamp | datetime | 响应时间戳 |
| Id | int | 记录ID |
| NeutralWaybillNumber | string | 中性面单单号 |
| ReplaceStatus | string | 换单状态 |
| LabelReplaced | bool | 是否成功换单 |
| Message | string | 操作消息 |
| ErrorDetails | string | 错误详情（仅状态为error时有效） |

**响应示例 (成功):**
```json
{
  "Status": "ok",
  "Timestamp": "2026-01-16T09:00:00Z",
  "Id": 1001,
  "NeutralWaybillNumber": "NW-20260116-0001",
  "ReplaceStatus": "Y",
  "LabelReplaced": true,
  "Message": "标签替换成功"
}
```

**响应示例 (失败):**
```json
{
  "Status": "error",
  "Timestamp": "2026-01-16T09:00:00Z",
  "NeutralWaybillNumber": "NW-20260116-0001",
  "ReplaceStatus": null,
  "LabelReplaced": false,
  "Message": "Invalid API credentials",
  "ErrorDetails": "API密钥验证失败"
}
```

## 6. 错误码说明

| 错误码 | HTTP状态码 | 错误信息 | 说明 |
|--------|------------|----------|------|
| 400 | 400 | Bad Request | 请求参数错误或格式不正确 |
| 401 | 401 | Unauthorized | API密钥验证失败 |
| 500 | 500 | Internal Server Error | 服务器内部错误 |

## 7. 调用示例

### 7.1 使用cURL调用标签替换接口

```bash
curl -X POST -H "Content-Type: application/json" -d '{"Text": "Hello {name}!", "Variables": {"name": "张三"}}' http://localhost:5000/api/Tag/replace
```

### 7.2 使用Python调用标签替换请求处理接口

```python
import requests
import json

url = "http://localhost:5000/api/Tag/label-replace"
headers = {
    "Content-Type": "application/json",
    "customer_code": "customer-001",
    "api_key": "your-api-key"
}

payload = {
    "NeutralWaybillNumber": "NW-20260116-0001",
    "Label": "base64 encoded PDF content..."
}

response = requests.post(url, headers=headers, data=json.dumps(payload))
print(response.json())
```

## 8. 接口调用限制

- 每个API密钥的调用频率限制为1000次/分钟
- 每个请求的最大大小限制为10MB
- 对于大量数据的处理，建议使用批量接口（如果提供）

## 9. 文档版本控制

| 版本 | 更新日期 | 更新内容 | 更新人 |
|------|----------|----------|--------|
| 1.0 | 2026-01-16 | 初始版本 | API文档团队 |