# OMS 退单回调接口 · 调用失败排查与注意事项

> 本文档说明 OMS 调用 `POST /api/oms/callback/order-return` 时**最常见的失败原因**，以及**配置/联调前必须注意的事项**。

## 一、最常见的失败原因（必看）

### 1. 接口未加入登录认证白名单（本次已修复）

系统启用了安全过滤（`unisbase.security.enabled=true`），不在 `permit-all-urls` 白名单内的接口**必须先登录（携带 Bearer token）才能访问**。OMS 是系统级外呼，不携带用户登录态，因此会被安全过滤器拦截导致失败。

- 影响接口（本次修复前）：`/api/oms/callback/order-return`
- 修复位置（已在如下文件加入白名单）：
  - `backend/src/main/resources/application.yml`
  - `backend/src/main/resources/application-prod.yml`
- 新增项：`- /api/oms/callback/order-return`

**注意：修改配置文件后必须重启后端服务才能生效。**

### 2. 鉴权头 `X-Internal-Secret` 不匹配

接口使用内部密钥校验（`unisbase.internal-auth`），请求头 `X-Internal-Secret` 必须与配置的 `secret` 一致，否则返回 401：

- header 名称：`X-Internal-Secret`（可在 `unisbase.internal-auth.header-name` 覆盖）
- secret 值：`unisbase.internal-auth.secret`
- 触发条件：`unisbase.internal-auth.enabled=true` 时强制校验
- 常见错误：OMS 侧配置的 secret 与后端不一致、头名写错、大小写不一致。

## 二、调用方（OMS）必须满足的调用要求

### 1. 地址与路径

| 项 | 要求 |
| --- | --- |
| 方法 | `POST`（不是 GET/PUT） |
| 完整路径 | `/api/oms/callback/order-return`（注意拼写与大小写） |
| 网络 | OMS 与 CRM 需网络可达；若经网关/反向代理，请确认路径透传、末尾保持一致 |

### 2. 请求头

| Header | 是否必需 | 值 |
| --- | --- | --- |
| `Content-Type` | 是 | `application/json` |
| `X-Internal-Secret` | 是 | 与后端 `unisbase.internal-auth.secret` 一致 |

### 3. 请求体

```json
{
  "opportunityCode": "OPP-20260916-001",
  "orderNo": "OMS-20260916-0001"
}
```

- `opportunityCode`：**必填**，为空或空白会返回参数校验失败（400）。
- `orderNo`：可选，仅用于日志，不影响结果。

## 三、常见失败场景与返回说明

| 失败场景 | 返回 | 原因/处理 |
| --- | --- | --- |
| 未放行白名单（未重启） | 需要登录 / 401 | 确认已加白名单并重启服务 |
| `X-Internal-Secret` 缺失或不符 | 401 内部接口鉴权失败 | 核对 secret 与头名 |
| `content-type` 非 json | 415 | 设置 `Content-Type: application/json` |
| 请求方法不是 POST | 405 | 使用 POST |
| `opportunityCode` 为空 | 400 | 补齐必填字段 |
| 商机编号不存在 | 400 商机不存在 | 确认该编号在 CRM 中存在 |
| 更新影响 0 行 | 400 商机更新失败 | 复核商机 id/DB 状态 |
| 白名单已放行但头不符 | 401 | 见第一节·二 |

## 四、联调前检查清单

- [ ] 后端已重启，配置文件（开发/prod）均已加白名单
- [ ] OMS 侧 `X-Internal-Secret` 与后端 `secret` 完全一致
- [ ] 请求方法为 POST、`Content-Type: application/json`
- [ ] 传入了真实的、CRM 中存在的 `opportunityCode`
- [ ] 网络/网关可达，路径未被改写（注意带不带前缀 `/api`）
- [ ] 用 `curl` 先在本地自测（见下）

## 五、本地自测命令（参考）

```bash
curl -X POST "http://<host>:<port>/api/oms/callback/order-return" \
  -H "Content-Type: application/json" \
  -H "X-Internal-Secret: <配置的secret>" \
  -d '{"opportunityCode":"OPP-20260916-001","orderNo":"OMS-0001"}'
```

成功返回示例：

```json
{ "code": 0, "message": "success", "data": 123 }
```

## 六、注意事项汇总

1. **白名单默认不含新接口**，新增 OMS 类外部接口后必须同步加入 `permit-all-urls`，否则调用方拿不到登录态必然失败——这是本次失败的最可能根因。
2. **配置修改需重启**。
3. **内部密钥不要使用默认值**，生产环境务必设置独立强随机的 `secret`，并同步给 OMS。
4. 接口是**可重试/幂等**的：重复调用只会把阶段保持为 S4、签约信息清空，不会产生副作用。
5. `orderNo` 仅用于日志对账，不参与业务判断，可选。