116 lines
3.6 KiB
Markdown
116 lines
3.6 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 |
|
|||
|
|
| `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` 外，至少还要传一个更新字段
|
|||
|
|
|
|||
|
|
## 请求示例
|
|||
|
|
|
|||
|
|
```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`
|
|||
|
|
- `项目把握度仅支持A、B、C`
|
|||
|
|
|
|||
|
|
## 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": "外部系统回写成交结果"
|
|||
|
|
}'
|
|||
|
|
```
|
|||
|
|
|