LabelChange-server/InterfaceDocument.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>	是	标签变量键值对

请求示例:

{
  "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	替换后的文本

响应示例 (成功):

{
  "status": "ok",
  "timestamp": "2026-01-16T08:30:00Z",
  "input": "Hello {name}, welcome to {company}!",
  "variables": {
    "name": "张三",
    "company": "标签替换服务"
  },
  "result": "Hello 张三, welcome to 标签替换服务!"
}

响应示例 (失败):

{
  "status": "error",
  "message": "请求处理失败"
}

4. 物流消息解析接口

4.1 接口地址

POST /api/Tag/logistics-parse

4.2 请求参数

请求体 (JSON格式):

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

请求示例:

{
  "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>	解析后的物流数据

响应示例 (成功):

{
  "status": "ok",
  "timestamp": "2026-01-16T08:45:00Z",
  "requestId": "logistics-123",
  "requestType": "order",
  "parsedData": {
    "orderNo": "ORD-20260116-001",
    "consignee": "李四",
    "phone": "13800138000",
    "address": "北京市朝阳区"
  }
}

响应示例 (失败):

{
  "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表示冻结换单）

请求示例:

{
  "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时有效）

响应示例 (成功):

{
  "Status": "ok",
  "Timestamp": "2026-01-16T09:00:00Z",
  "Id": 1001,
  "NeutralWaybillNumber": "NW-20260116-0001",
  "ReplaceStatus": "Y",
  "LabelReplaced": true,
  "Message": "标签替换成功"
}

响应示例 (失败):

{
  "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调用标签替换接口

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

7.2 使用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文档团队