118 lines
4.0 KiB
Markdown
118 lines
4.0 KiB
Markdown
# 商机更新对接接口
|
||
|
||
## 接口信息
|
||
|
||
- 请求方式：`PUT`
|
||
- 请求路径：`/api/opportunities/integration/update`
|
||
- 请求头：
|
||
- `Content-Type: application/json`
|
||
- `X-Internal-Secret: <内部接口密钥>`
|
||
|
||
## 接口说明
|
||
|
||
- 通过 `opportunityCode` 定位商机
|
||
- 按传入字段做部分更新，未传字段不修改
|
||
- 不支持更新商机的最终客户
|
||
|
||
## 请求参数
|
||
|
||
### 必填
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
| ----------------- | ------ | ---- |
|
||
| `opportunityCode` | string | 商机编号 |
|
||
|
||
### 可选
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
| -------------------- | ------- | -------------------------------------- |
|
||
| `opportunityName` | string | 商机名称 |
|
||
| `projectLocation` | string | 项目地 |
|
||
| `operatorName` | string | 运作方 |
|
||
| `amount` | number | 商机金额，历史数据回写不再限制必须大于 0 |
|
||
| `actualSignedAmount` | number | 实际签约金额，兼容字段名 `actual_signed_amount` |
|
||
| `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 格式 |
|
||
| `isPoc` | boolean | 是否 POC 测试项目，兼容字段名 `is_poc` |
|
||
| `status` | string | 商机状态，支持 `active`、`closed`、`won`、`lost` |
|
||
| `description` | string | 备注 |
|
||
|
||
## 关键规则
|
||
|
||
- `opportunityCode` 仅用于定位商机，仍需传入
|
||
- 其他字段均为可选；未传字段不修改
|
||
- 为兼容历史数据，接口不再要求除 `opportunityCode` 外必须存在更新字段
|
||
|
||
## 请求示例
|
||
|
||
```json
|
||
{
|
||
"opportunityCode": "OPP-20260401-001",
|
||
"stage": "won",
|
||
"status": "won",
|
||
"confidencePct": "A",
|
||
"amount": 2800000,
|
||
"expectedCloseDate": "2026-04-30",
|
||
"description": "外部系统回写成交结果"
|
||
}
|
||
```
|
||
|
||
## 返回示例
|
||
|
||
### 成功
|
||
|
||
```json
|
||
{
|
||
"code": "0",
|
||
"msg": "success",
|
||
"data": 123
|
||
}
|
||
```
|
||
|
||
### 失败
|
||
|
||
```json
|
||
{
|
||
"code": "-1",
|
||
"msg": "商机不存在",
|
||
"data": null
|
||
}
|
||
```
|
||
|
||
## 常见错误
|
||
|
||
- `内部接口鉴权失败`
|
||
- `商机不存在`
|
||
- `opportunityCode 不能为空`
|
||
- `项目阶段无效: xxx`
|
||
- `项目把握度无效: xxx`
|
||
|
||
## curl 示例
|
||
|
||
```bash
|
||
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": "外部系统回写成交结果"
|
||
}'
|
||
```
|