BMS/bms-back/doc/TMS订单额度欠费状态和客户状态查询接口文档.md

TMS 订单额度欠费状态和客户状态查询接口

1. 接口用途

TMS 根据订单号、运单号或转单号查询 BMS 中的订单计费记录，并获取该订单关联客户的当前启用状态和订单计费记录中的欠费状态快照。其他字段返回用于TMS辅助判断。

2. 基本信息

项目	内容
请求方式	GET
请求地址	/api/tms/order-bill/status
完整地址示例	https://bms.lionquexpress.com/prod-api/api/tms/order-bill/status
登录要求	不需要登录 Token
接口鉴权	必须携带请求头 X-Api-Code
字符编码	UTF-8
响应格式	JSON

X-Api-Code = BMS.TMS.ZYaOvlQzpcfau8TUaCFfO3Hp8ieHIqGw

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。同一标识命中多条订单时，接口不会任选其中一条返回。

若同一条订单的多个字段恰好与 identifier 相同，matchType 按 ORDER_NO、TRACKING_NO、TRANSFER_NO 的顺序返回。

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	是否查询到订单计费记录；订单不存在时为 false
matchedCount	Integer	匹配记录数；接口最多读取 2 条，返回 2 表示至少匹配到两条，存在歧义
matchType	String	NOT_FOUND 未找到订单；唯一命中为 ORDER_NO、TRACKING_NO、TRANSFER_NO；多条匹配为 MULTIPLE
billId	String	BMS 计费订单 ID；唯一命中时返回
orderNo	String	订单号；唯一命中时返回
trackingNo	String	运单号；唯一命中时返回
transferNo	String	转单号；唯一命中时返回
customerId	Long	订单计费记录保存的客户 ID；唯一命中时返回，不代表当前客户档案一定存在
customerCode	String	订单计费记录保存的客户编码；唯一命中时返回，不代表当前客户档案一定存在
customerFound	Boolean	当前客户是否存在；唯一命中时返回；订单未找到或多条匹配时为 null
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",
    "customerFound": true,
    "customerActiveStatus": "ACTIVE",
    "creditArrearsStatus": "NORMAL"
  }
}

6.2 未查询到数据

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

未命中时不会查询客户档案，也不会返回账单、客户或状态数据。逻辑上的 customerFound、customerActiveStatus、creditArrearsStatus 均为 null；实际 JSON 是否省略 null 字段取决于 BMS 的序列化配置。

6.3 匹配到多条数据

{
  "code": 200,
  "msg": "操作成功",
  "data": {
    "found": true,
    "matchedCount": 2,
    "matchType": "MULTIPLE",
    "customerFound": null
  }
}

匹配多条时，接口不查询客户档案，也不随机返回其中一条账单详情；matchedCount=2 表示至少两条。TMS 应根据自身规则处理该结果；如需唯一查询，优先使用唯一的订单号。

6.4 订单存在但客户不存在

{
  "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",
    "customerFound": false,
    "customerActiveStatus": "MISSING",
    "creditArrearsStatus": "ARREARS"
  }
}

MISSING 表示订单存在，但根据订单中的 customerId 未找到有效客户，包括客户不存在、已逻辑删除或客户 ID 为空/无效。此时 customerActiveStatus 返回 MISSING。

creditArrearsStatus 与客户当前是否存在相互独立，仍按 prc_order_bill.credit_arrears_status 的订单快照返回，不代表客户当前实时欠费状态；如果订单快照本身为空，则返回 null。

6.5 订单存在且客户已停用

{
  "code": 200,
  "msg": "操作成功",
  "data": {
    "found": true,
    "matchedCount": 1,
    "matchType": "TRACKING_NO",
    "billId": "4c1f0d1e-6f6d-4a5e-9ab5-7a7f5d3b6e02",
    "orderNo": "TMS20260918005496762602",
    "trackingNo": "UBI89033506178CN",
    "transferNo": "TRANSFER002",
    "customerId": 141,
    "customerCode": "C00143",
    "customerFound": true,
    "customerActiveStatus": "DISABLED",
    "creditArrearsStatus": "NORMAL"
  }
}

7. 状态字段说明

7.1 客户生效状态 customerActiveStatus

值	含义
ACTIVE	bms_customer.is_enable = '0'，客户存在且正常生效
MISSING	订单存在，但未找到对应的有效客户；包括客户不存在、已逻辑删除或客户 ID 无效
DISABLED	bms_customer.is_enable = '1'，客户存在但已停用；客户启用状态为空或异常时也按非正常状态返回 DISABLED
null	订单不存在或匹配到多条订单时，不判断客户状态

7.2 额度欠费状态 creditArrearsStatus

值	含义
NORMAL	订单计费记录中保存的额度正常快照
ARREARS	订单计费记录中保存的额度欠费快照
其他非空值	BMS 保留并原样转大写返回，表示订单快照数据异常或扩展状态
null	订单计费记录中的该状态为空；订单不存在或多条匹配时也不返回该状态

8. 异常情况

场景	返回情况
缺少 X-Api-Code	请求失败，返回 API_CODE_INVALID
X-Api-Code 错误	请求失败，返回 API_CODE_INVALID
BMS 未配置 X-Api-Code	请求失败，返回 API_CODE_NOT_CONFIGURED
identifier 为空或全为空格	请求失败，提示标识不能为空
identifier 超过 64 个字符	请求失败，提示标识长度不能超过 64 个字符
数据库未查询到订单记录	HTTP 业务响应正常，data.found=false、data.matchType=NOT_FOUND
订单存在但客户不存在	HTTP 业务响应正常，data.found=true、data.customerFound=false、data.customerActiveStatus=MISSING
同一标识匹配多条记录	HTTP 业务响应正常，data.matchType=MULTIPLE
数据库或系统异常	请求失败，不会伪装为 NOT_FOUND 或 MISSING；TMS 应按非 200 的业务响应处理

当前项目统一使用 AjaxResult 返回异常，具体 HTTP 状态码以 BMS 网关和全局异常处理配置为准。TMS 集成时应优先判断响应体中的 code，再读取 data。

9. 集成建议

1. TMS 每次只传一个 identifier，不要同时传订单号、运单号和转单号。
2. 先判断响应体 code 是否为 200，再判断 data.found。
3. found=false 且 matchType=NOT_FOUND 表示订单不存在；此时不应把客户状态为空理解为客户不存在。
4. found=true 且 customerFound=false 表示订单存在但客户不存在；matchedCount>1 或 matchType=MULTIPLE 表示订单匹配有歧义；具体处理策略由 TMS 自行决定。
5. customerActiveStatus 只返回 ACTIVE、MISSING、DISABLED 三种约定状态；只有 ACTIVE 表示客户当前启用，其他状态由 TMS 根据自身规则处理。
6. creditArrearsStatus 是订单计费记录中的状态快照，不代表客户当前实时额度状态。
7. 建议设置连接超时和读取超时，并对网络异常进行有限次数重试；查询接口本身是只读接口，可安全重试。