# 讯通回传接口规范文档

## 1. 接口概述

### 1.1 功能定位
该接口用于在更新面单、单号后，向速递管家系统回传中性面单号、换单结果、换单时间及换单描述，以完成换单结果的同步与记录。

### 1.2 核心功能
准确回传换单的最终处理状态（如换单成功、换单失败等业务结果）。

### 1.3 技术规范
- 请求方法：POST
- Content-Type：multipart/form-data
- 测试环境地址：http://toms.ruantongbao.com/webservice/ChangeLabel/LabelService.ashx
- 正式环境地址：需咨询系统使用方获取
- 通信协议：HTTP

## 2. 请求规范

### 2.1 请求头部（Headers）
- 必须设置标准表单提交头部：Content-Type: multipart/form-data
- 确保请求头部符合RFC标准，无额外自定义头部除非系统使用方特殊要求

### 2.2 请求体（Body - form-data）

| 参数名 (Key) | 类型               | 是否必填 | 描述                                   | 约束条件                     |
|--------------|--------------------|----------|----------------------------------------|------------------------------|
| code         | String             | 是       | 操作指令码                             | 固定值为：PRINTMARK          |
| data         | String (JSON格式)  | 是       | 包含具体业务结果数据的JSON字符串       | 必须符合JSON格式规范         |

### 2.3 data参数详细结构（JSON对象）

| 字段名          | 类型   | 是否必填 | 描述                                   | 格式约束                          | 示例值                  |
|-----------------|--------|----------|----------------------------------------|-----------------------------------|-------------------------|
| neutralWaybillNo| String | 是       | 中性面单号                             | 不可为空，长度不超过50个字符      | "33474254025971"        |
| exchangeResult  | String | 是       | 换单结果                               | 仅允许值："SUCCESS" 或 "FAILURE"  | "SUCCESS"               |
| exchangeTime    | String | 是       | 换单时间                               | 严格遵循格式："YYYY/MM/DD HH:MM:SS"| "2026/3/25 15:27:19"    |
| resultMsg       | String | 否       | 换单描述                               | 长度不超过200个字符               | "测试"                  |

## 3. 响应规范

### 3.1 响应格式：application/json

### 3.2 响应体（JSON对象）

| 字段名   | 类型    | 描述                                                                 |
|----------|---------|----------------------------------------------------------------------|
| success  | Boolean | 接口调用是否成功。true表示请求被服务器正确接收和处理；false表示请求格式错误、鉴权失败等 |
| msg      | String  | 接口调用的返回信息，成功时返回操作结果，失败时返回具体错误原因               |

### 3.3 响应示例

- 成功示例（接口调用成功）：
  ```json
  {
    "success": true,
    "msg": "处理成功"
  }
  ```

- 失败示例（接口调用失败）：
  ```json
  {
    "success": false,
    "msg": "没有订单信息"
  }
  ```

## 4. 接口调用示例（cURL）

```bash
curl -X POST "http://toms.ruantongbao.com/webservice/ChangeLabel/LabelService.ashx" \
  -F "code=PRINTMARK" \
  -F 'data={
        "neutralWaybillNo": "33474254025971",
        "exchangeResult": "FAILURE",
        "exchangeTime": "2026/3/25 15:27:19",
        "resultMsg": "换单失败"
      }'
```

## 5. 状态码与错误处理机制

### 5.1 HTTP状态码处理：
- HTTP 200 OK：请求已送达服务器，需根据返回JSON中的success字段判断业务逻辑
- HTTP 4xx：客户端错误，需检查请求参数格式、认证信息等
- HTTP 5xx：服务器错误，需检查服务端状态并联系系统使用方

### 5.2 业务逻辑判断流程：
1. 首先验证HTTP状态码是否为200，非200状态需进行网络层错误处理
2. 解析响应JSON，检查success字段：
   - 若success为false：接口调用失败，需根据msg字段内容排查错误原因
   - 若success为true：从data字段解析exchangeResult判断具体业务处理结果
3. 实现完整的错误重试机制，对网络超时、服务器错误等情况进行指数退避重试

## 6. 实现要求

- 必须对所有输入参数进行严格校验，特别是data字段的JSON格式及各子字段的格式约束
- 实现请求超时控制，建议超时时间设置为30秒
- 记录详细的接口调用日志，包括请求参数、响应结果、耗时等信息
- 确保接口调用的安全性，敏感信息需加密传输（如适用）
- 代码实现需遵循项目编码规范，包含必要的注释和文档
- 编写单元测试和集成测试，确保接口功能的正确性和健壮性

## 7. 验收标准

- 能够正确处理所有必填参数和可选参数的各种组合情况
- 对无效参数、格式错误等异常情况能返回明确的错误信息
- 接口在网络不稳定环境下具有一定的容错能力和重试机制
- 响应时间满足业务要求（建议平均响应时间<500ms）
- 与速递管家系统的联调测试通过率达到100%