LabelChange-server/讯通回传接口规范.md

讯通回传接口规范文档

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 响应示例

• 成功示例（接口调用成功）：

  {
    "success": true,
    "msg": "处理成功"
  }
  

• 失败示例（接口调用失败）：

  {
    "success": false,
    "msg": "没有订单信息"
  }
  

4. 接口调用示例（cURL）

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%