unis_crm/OMS退单回调接口文档.md

OMS 退单回调接口文档

OMS 系统退单后，主动回调 CRM，将对应商机的项目阶段更新为 S4，并清空签约信息。

基本信息

项目	内容
接口路径	POST /api/oms/callback/order-return
调用方	OMS 系统
请求头鉴权	X-Internal-Secret（内部接口密钥）
幂等性	可重试，重复调用不产生副作用

鉴权方式

与商机集成更新接口 PUT /api/opportunities/integration/update 保持一致，使用 unisbase.internal-auth 配置的密钥校验。

• 请求头字段：X-Internal-Secret（可通过 unisbase.internal-auth.header-name 覆盖）
• 秘钥值：unisbase.internal-auth.secret
• 校验逻辑：
  • 当 unisbase.internal-auth.enabled=true 时强制校验，头信息与配置密钥不一致则返回鉴权失败；
  • 当 enabled=false 时跳过鉴权（仅用于本地开发）。

请求示例：

POST /api/oms/callback/order-return
Content-Type: application/json
X-Internal-Secret: <配置的secret>

请求参数

Body（application/json）

字段	类型	必填	说明
opportunityCode	string	是	CRM 商机编号，用于定位商机（≤50 字符）
orderNo	string	否	OMS 退单号，仅用于日志记录（≤50 字符）

请求体示例：

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

业务处理逻辑

退单回调成功后，CRM 对目标商机执行如下更新：

字段	更新后值
项目阶段 stage	S4
状态 status	active
实际签约金额 actual_signed_amount	置空（null）
是否签约 archived	false
签约/归档时间 archived_at	置空（null）
更新时间 updated_at	now()

定位逻辑：按 opportunity_code 精确匹配商机；未匹配到或编号为空时抛出异常，不更新任何数据。整个操作在同一事务内完成。

响应

统一响应体：

字段	类型	说明
code	int	业务状态码，0 表示成功，非 0 表示失败
message	string	提示信息
data	object	返回数据

成功响应

data 为被更新商机的 id（Long）。

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

失败响应

场景	说明
鉴权失败	内部接口鉴权失败（X-Internal-Secret 不匹配时抛异常）
商机编号为空	商机编号不能为空
商机不存在	未按 opportunityCode 匹配到商机
更新失败	数据库更新影响行数为 0

失败示例：

{
  "code": 1,
  "message": "内部接口鉴权失败",
  "data": null
}

注：message 具体文案以实际业务异常为准，示例仅供参考。

相关代码

• Controller：OmsCallbackController.java
• 请求 DTO：OmsOrderReturnRequest.java
• Service 接口：OpportunityService.java
• Service 实现：OpportunityServiceImpl.java
• Mapper 实现：OpportunityMapper.xml

备注

• crm_opportunity 表无独立的「签约时间/是否签约」列，系统以 archived（是否签单）、archived_at（归档/签约时间）、actual_signed_amount（实际签约金额）表达签约状态，退单时三者一并清空。