# 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 代码仓库或日志中。