112 lines
5.1 KiB
Markdown
112 lines
5.1 KiB
Markdown
# 讯通回传接口规范文档
|
||
|
||
## 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%
|