unis_crm/docs/opportunity-integration-api.md

商机更新对接接口

接口信息

• 请求方式：PUT
• 请求路径：/api/opportunities/integration/update
• 请求头：
  • Content-Type: application/json
  • X-Internal-Secret: <内部接口密钥>

接口说明

• 通过 opportunityCode 定位商机
• 按传入字段做部分更新，未传字段不修改
• 不支持更新商机的最终客户

请求参数

必填

字段	类型	说明
opportunityCode	string	商机编号

可选

字段	类型	说明
opportunityName	string	商机名称
projectLocation	string	项目地
operatorName	string	运作方
amount	number	商机金额，必须大于 0
expectedCloseDate	string	预计结单日期，格式 YYYY-MM-DD
confidencePct	string	把握度，建议传 A、B、C
stage	string	项目阶段，建议传 CRM 当前字典码值
opportunityType	string	建设类型
productType	string	产品类型
source	string	商机来源
salesExpansionId	number	销售拓展 ID，必须大于 0
channelExpansionId	number	渠道拓展 ID，必须大于 0
preSalesId	number	售前 ID，必须大于 0
preSalesName	string	售前姓名
competitorName	string	竞品名称
archived	boolean	是否归档
pushedToOms	boolean	是否已推送 OMS
omsPushTime	string	推送 OMS 时间，建议 ISO 8601 格式
status	string	商机状态，支持 active、closed、won、lost
description	string	备注

关键规则

• 除 opportunityCode 外，至少还要传一个更新字段

请求示例

{
  "opportunityCode": "OPP-20260401-001",
  "stage": "won",
  "status": "won",
  "confidencePct": "A",
  "amount": 2800000,
  "expectedCloseDate": "2026-04-30",
  "description": "外部系统回写成交结果"
}

返回示例

成功

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

失败

{
  "code": "-1",
  "msg": "商机不存在",
  "data": null
}

常见错误

• 内部接口鉴权失败
• 商机不存在
• opportunityCode 不能为空
• 至少传入一个需要更新的字段
• 项目阶段无效: xxx
• 项目把握度仅支持A、B、C

curl 示例

curl -X PUT 'http://localhost:8080/api/opportunities/integration/update' \
  -H 'Content-Type: application/json' \
  -H 'X-Internal-Secret: f0eb247f84db4e328fb27ce8ff6e7be96e73a53a7e9c4793395ad10d999e0d77' \
  -d '{
    "opportunityCode": "OPP-20260401-001",
    "stage": "won",
    "status": "won",
    "confidencePct": "A",
    "amount": 2800000,
    "expectedCloseDate": "2026-04-30",
    "description": "外部系统回写成交结果"
  }'