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

```text
order_no = identifier
OR tracking_no = identifier
OR transfer_no = identifier
```

请勿传递模糊查询字符，也不要在一次请求中传递多个 `identifier`。同一标识命中多条订单时，接口不会任选其中一条返回。

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

## 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 | 是否查询到订单计费记录；订单不存在时为 `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 唯一命中

```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",
    "customerFound": true,
    "customerActiveStatus": "ACTIVE",
    "creditArrearsStatus": "NORMAL"
  }
}
```

### 6.2 未查询到数据

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

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

### 6.3 匹配到多条数据

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

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

### 6.4 订单存在但客户不存在

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

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

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

### 6.5 订单存在且客户已停用

```json
{
  "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. 建议设置连接超时和读取超时，并对网络异常进行有限次数重试；查询接口本身是只读接口，可安全重试。