订单客户状态查询接口文档编写

2026-09-22 11:07:30 +08:00
parent e0df965d89
commit cb08a1deb2
1 changed files with 201 additions and 0 deletions
@@ -0,0 +1,201 @@
+# TMS 订单账单状态查询接口
+
+## 1. 接口用途
+
+TMS 根据订单号、运单号或转单号查询 BMS 中的订单计费记录，以及该订单对应的客户状态和额度状态。
+
+
+## 2. 基本信息
+
+| 项目 | 内容 |
+|---|---|
+| 请求方式 | `GET` |
+| 请求地址 | `/api/tms/order-bill/status` |
+| 完整地址示例 | `http://{BMS_HOST}:{PORT}/api/tms/order-bill/status` |
+| 登录要求 | 不需要登录 Token |
+| 接口鉴权 | 必须携带请求头 `X-Api-Code` |
+| 字符编码 | UTF-8 |
+| 响应格式 | JSON |
+
+> `X-Api-Code` 的实际值由 BMS 管理方通过安全渠道提供，不在业务代码、接口文档或工单中明文传播。
+
+## 3. 请求参数
+
+### 3.1 请求头
+
+| 参数名 | 类型 | 必填 | 说明 |
+|---|---|---|---|
+| `X-Api-Code` | String | 是 | BMS 分配给 TMS 的接口识别码 |
+
+### 3.2 Query 参数
+
+| 参数名 | 类型 | 必填 | 长度 | 说明 |
+|---|---|---|---|---|
+| `identifier` | String | 是 | 1～64 | 订单号、运单号或转单号，三者只传一个 |
+
+接口会对 `identifier` 做首尾空格清理，然后使用精确匹配：
+
+```text
+order_no = identifier
+OR tracking_no = identifier
+OR transfer_no = identifier
+```
+
+请勿传递模糊查询字符，也不要在一次请求中传递多个 `identifier`。
+
+## 4. 请求示例
+
+```bash
+curl --location \
+  'http://{BMS_HOST}:{PORT}/api/tms/order-bill/status?identifier=TMS20260918005496762601' \
+  --header 'X-Api-Code: {BMS_API_CODE}'
+```
+
+按运单号查询：
+
+```bash
+curl --location \
+  'http://{BMS_HOST}:{PORT}/api/tms/order-bill/status?identifier=UBI89033506177CN' \
+  --header 'X-Api-Code: {BMS_API_CODE}'
+```
+
+按转单号查询：
+
+```bash
+curl --location \
+  'http://{BMS_HOST}:{PORT}/api/tms/order-bill/status?identifier=TRANSFER001' \
+  --header 'X-Api-Code: {BMS_API_CODE}'
+```
+
+## 5. 响应结构
+
+### 5.1 通用响应外层
+
+```json
+{
+  "code": 200,
+  "msg": "操作成功",
+  "data": {}
+}
+```
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| `code` | Integer | `200` 表示接口请求处理成功 |
+| `msg` | String | 接口处理信息，正常成功时为“操作成功” |
+| `data` | Object | 订单账单状态查询结果 |
+
+### 5.2 `data` 字段
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| `found` | Boolean | 是否查询到数据 |
+| `matchedCount` | Integer | 匹配记录数；接口最多统计返回 `2`，大于 `1` 表示存在歧义 |
+| `matchType` | String | 唯一命中类型：`ORDER_NO`、`TRACKING_NO`、`TRANSFER_NO`；多条匹配为 `MULTIPLE` |
+| `billId` | String | BMS 计费订单 ID；唯一命中时返回 |
+| `orderNo` | String | 订单号；唯一命中时返回 |
+| `trackingNo` | String | 运单号；唯一命中时返回 |
+| `transferNo` | String | 转单号；唯一命中时返回 |
+| `customerId` | Long | 客户 ID；唯一命中时返回 |
+| `customerCode` | String | 客户编码；唯一命中时返回 |
+| `customerActiveStatus` | String | 客户生效状态：`ACTIVE` 正常、`MISSING` 不存在、`DISABLED` 停用 |
+| `creditArrearsStatus` | String | 额度欠费状态：`NORMAL` 正常、`ARREARS` 欠费 |
+
+## 6. 返回示例
+
+### 6.1 唯一命中
+
+```json
+{
+  "code": 200,
+  "msg": "操作成功",
+  "data": {
+    "found": true,
+    "matchedCount": 1,
+    "matchType": "ORDER_NO",
+    "billId": "4c1f0d1e-6f6d-4a5e-9ab5-7a7f5d3b6e01",
+    "orderNo": "TMS20260918005496762601",
+    "trackingNo": "UBI89033506177CN",
+    "transferNo": "TRANSFER001",
+    "customerId": 140,
+    "customerCode": "C00142",
+    "customerActiveStatus": "ACTIVE",
+    "creditArrearsStatus": "NORMAL"
+  }
+}
+```
+
+### 6.2 未查询到数据
+
+```json
+{
+  "code": 200,
+  "msg": "操作成功",
+  "data": {
+    "found": false,
+    "matchedCount": 0
+  }
+}
+```
+
+未命中时不会返回客户或账单数据。是否继续后续流程由 TMS 根据自身业务规则决定。
+
+### 6.3 匹配到多条数据
+
+```json
+{
+  "code": 200,
+  "msg": "操作成功",
+  "data": {
+    "found": true,
+    "matchedCount": 2,
+    "matchType": "MULTIPLE"
+  }
+}
+```
+
+匹配多条时，接口不随机返回其中一条账单详情。TMS 应根据自身规则处理该结果；如需唯一查询，优先使用唯一的订单号。
+
+## 7. 状态字段说明
+
+### 7.1 客户生效状态 `customerActiveStatus`
+
+| 值 | 含义 |
+|---|---|
+| `ACTIVE` | 客户存在且正常生效 |
+| `MISSING` | 未找到对应客户 |
+| `DISABLED` | 客户存在但已停用 |
+| 其他非空值 | BMS 保留并原样转大写返回，供 TMS 识别新状态或异常数据 |
+| `null` | BMS 中该状态为空 |
+
+### 7.2 额度欠费状态 `creditArrearsStatus`
+
+| 值 | 含义 |
+|---|---|
+| `NORMAL` | 额度正常 |
+| `ARREARS` | 额度欠费 |
+| 其他非空值 | BMS 保留并原样转大写返回，供 TMS 识别新状态或异常数据 |
+| `null` | BMS 中该状态为空 |
+
+## 8. 异常情况
+
+| 场景 | 返回情况 |
+|---|---|
+| 缺少 `X-Api-Code` | 请求失败，返回 `API_CODE_INVALID` |
+| `X-Api-Code` 错误 | 请求失败，返回 `API_CODE_INVALID` |
+| `identifier` 为空或全为空格 | 请求失败，提示标识不能为空 |
+| `identifier` 超过 64 个字符 | 请求失败，提示标识长度不能超过 64 个字符 |
+| 数据库未查询到记录 | HTTP 业务响应正常，`data.found=false` |
+| 同一标识匹配多条记录 | HTTP 业务响应正常，`data.matchType=MULTIPLE` |
+
+> 当前项目统一使用 `AjaxResult` 返回异常，具体 HTTP 状态码以 BMS 网关和全局异常处理配置为准。TMS 集成时应优先判断响应体中的 `code`，再读取 `data`。
+
+## 9. 集成建议
+
+1. TMS 每次只传一个 `identifier`，不要同时传订单号、运单号和转单号。
+2. 先判断响应体 `code` 是否为 `200`，再判断 `data.found`。
+3. `found=false`、`matchedCount>1`、状态为空或出现未知状态时，不要当作唯一有效订单使用；具体处理策略由 TMS 自行决定。
+4. 建议设置连接超时和读取超时，并对网络异常进行有限次数重试；查询接口本身是只读接口，可安全重试。
+5. `X-Api-Code` 属于接口凭证，应通过配置中心或密钥管理方式保存，不要硬编码到 TMS 代码仓库或日志中。
+
+