100 lines
4.2 KiB
Markdown
100 lines
4.2 KiB
Markdown
# 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` 仅用于日志对账，不参与业务判断，可选。 |