wuweihua/BMS

Fork 0

Files

T

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

2026-09-22 11:07:30 +08:00

6.0 KiB

Raw Blame History

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 做首尾空格清理，然后使用精确匹配：

order_no = identifier
OR tracking_no = identifier
OR transfer_no = identifier

请勿传递模糊查询字符，也不要在一次请求中传递多个 identifier。

4. 请求示例

curl --location \
  'http://{BMS_HOST}:{PORT}/api/tms/order-bill/status?identifier=TMS20260918005496762601' \
  --header 'X-Api-Code: {BMS_API_CODE}'

按运单号查询：

curl --location \
  'http://{BMS_HOST}:{PORT}/api/tms/order-bill/status?identifier=UBI89033506177CN' \
  --header 'X-Api-Code: {BMS_API_CODE}'

按转单号查询：

curl --location \
  'http://{BMS_HOST}:{PORT}/api/tms/order-bill/status?identifier=TRANSFER001' \
  --header 'X-Api-Code: {BMS_API_CODE}'

5. 响应结构

5.1 通用响应外层

{
  "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 唯一命中

{
  "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 未查询到数据

{
  "code": 200,
  "msg": "操作成功",
  "data": {
    "found": false,
    "matchedCount": 0
  }
}

未命中时不会返回客户或账单数据。是否继续后续流程由 TMS 根据自身业务规则决定。

6.3 匹配到多条数据

{
  "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. 集成建议

TMS 每次只传一个 identifier，不要同时传订单号、运单号和转单号。
先判断响应体 code 是否为 200，再判断 data.found。
found=false、matchedCount>1、状态为空或出现未知状态时，不要当作唯一有效订单使用；具体处理策略由 TMS 自行决定。
建议设置连接超时和读取超时，并对网络异常进行有限次数重试；查询接口本身是只读接口，可安全重试。
X-Api-Code 属于接口凭证，应通过配置中心或密钥管理方式保存，不要硬编码到 TMS 代码仓库或日志中。

6.0 KiB Raw Blame History Unescape Escape