4.2 KiB

Raw Blame History

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. 请求体

{
  "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 先在本地自测（见下）

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

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"}'

成功返回示例：

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

六、注意事项汇总

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

4.2 KiB Raw Blame History Unescape Escape