kris/datai
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
develop
datai/datai-scenes/datai-scene-salesforce/docs/api-docs/2026-02-02-006-api.md

428 lines
12 KiB
Markdown
Raw Permalink Normal View History

【feat】 初始化所有模块，提交partner模块初始实现
2026-02-02 16:12:25 +08:00
# API 文档 - 高级功能
## 元数据
- 需求编号：001-06
- 创建时间：2026-02-02
- 创建人：AI Assistant
- 版本号：v1.0.0
- 关联需求：[高级功能](../requirements/sub/2026-01-28-001-06-高级功能.md)
## API 概述
高级功能 API 提供了对 Salesforce 高级操作的支持，包括线索转换、清空回收站、流程提交、获取用户信息、获取服务器时间戳等。这些 API 可以帮助开发人员实现复杂的业务场景，如销售流程管理、数据清理、审批流程等。
## 接口列表
### 1. 转换线索
#### 接口说明
将线索转换为账户、联系人和商机。支持指定现有账户和联系人进行关联，支持覆盖线索来源选项，支持不创建商机选项，支持发送通知邮件选项。
- **接口名称**：ConvertLead
- **请求方式**：POST
- **请求路径**：`/partner/advanced/convert-lead`
- **权限要求**：`@PreAuthorize("@ss.hasPermi('partner:advanced:convertLead')")`
#### 请求参数
| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| leadId | String | 是 | 线索 ID，格式为 18 位 Salesforce ID |
| convertedStatus | String | 是 | 转换状态，如 "Qualified" |
| accountId | String | 否 | 账户 ID，指定要关联的现有账户 |
| contactId | String | 否 | 联系人 ID，指定要关联的现有联系人 |
| opportunityId | String | 否 | 商机 ID，指定要关联的现有商机 |
| overwriteLeadSource | Boolean | 否 | 是否覆盖线索来源，默认为 false |
| doNotCreateOpportunity | Boolean | 否 | 是否不创建商机，默认为 false |
| sendNotificationEmail | Boolean | 否 | 是否发送通知邮件，默认为 false |
#### 请求示例
```json
{
"leadId": "00Qxx0000001Gw2EAE",
"convertedStatus": "Qualified",
"accountId": "001xx0000001Gw2EAA",
"contactId": "003xx0000001Gw2EAA",
"opportunityId": "006xx0000001Gw2EAA",
"overwriteLeadSource": true,
"doNotCreateOpportunity": false,
"sendNotificationEmail": true
}
```
#### 响应参数
| 参数名 | 类型 | 说明 |
|--------|------|------|
| code | Integer | 状态码（200 成功，其他失败） |
| msg | String | 提示信息 |
| data | Object | 响应数据 |
| data.accountId | String | 转换后的账户 ID |
| data.contactId | String | 转换后的联系人 ID |
| data.opportunityId | String | 转换后的商机 ID |
| data.leadId | String | 原线索 ID |
| data.success | Boolean | 是否成功 |
| data.errors | Array | 错误信息列表 |
| data.errors[].message | String | 错误消息 |
| data.errors[].statusCode | String | 错误状态码 |
#### 成功示例
```json
{
"code": 200,
"msg": "线索转换成功",
"data": {
"accountId": "001xx0000001Gw2EAA",
"contactId": "003xx0000001Gw2EAA",
"opportunityId": "006xx0000001Gw2EAA",
"leadId": "00Qxx0000001Gw2EAE",
"success": true,
"errors": []
}
}
```
#### 失败示例
```json
{
"code": 200,
"msg": "线索转换失败",
"data": {
"accountId": null,
"contactId": null,
"opportunityId": null,
"leadId": "00Qxx0000001Gw2EAE",
"success": false,
"errors": [
{
"message": "Invalid lead status",
"statusCode": "INVALID_LEAD_STATUS"
}
]
}
}
```
---
### 2. 清空回收站
#### 接口说明
永久删除回收站中的记录。支持批量操作，最多 200 个记录。返回每个记录的删除结果，支持部分失败情况。
- **接口名称**：EmptyRecycleBin
- **请求方式**：POST
- **请求路径**：`/partner/advanced/empty-recycle-bin`
- **权限要求**：`@PreAuthorize("@ss.hasPermi('partner:advanced:emptyRecycleBin')")`
#### 请求参数
| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| ids | Array<String> | 是 | 记录 ID 列表，最多 200 个，每个 ID 格式为 18 位 Salesforce ID |
#### 请求示例
```json
{
"ids": [
"001xx0000001Gw2EAA",
"001xx0000001Gw3EAA",
"001xx0000001Gw4EAA"
]
}
```
#### 响应参数
| 参数名 | 类型 | 说明 |
|--------|------|------|
| code | Integer | 状态码（200 成功，其他失败） |
| msg | String | 提示信息 |
| data | Object | 响应数据 |
| data.results | Array | 结果列表 |
| data.results[].id | String | 记录 ID |
| data.results[].success | Boolean | 是否成功 |
| data.results[].errors | Array | 错误信息列表 |
| data.results[].errors[].message | String | 错误消息 |
| data.results[].errors[].statusCode | String | 错误状态码 |
| data.success | Boolean | 是否全部成功（部分失败时为 false） |
| data.errors | Array | 整体错误信息列表 |
#### 成功示例
```json
{
"code": 200,
"msg": "清空回收站成功",
"data": {
"results": [
{
"id": "001xx0000001Gw2EAA",
"success": true,
"errors": []
},
{
"id": "001xx0000001Gw3EAA",
"success": true,
"errors": []
},
{
"id": "001xx0000001Gw4EAA",
"success": true,
"errors": []
}
],
"success": true,
"errors": []
}
}
```
#### 部分失败示例
```json
{
"code": 200,
"msg": "清空回收站部分失败",
"data": {
"results": [
{
"id": "001xx0000001Gw2EAA",
"success": true,
"errors": []
},
{
"id": "001xx0000001Gw3EAA",
"success": false,
"errors": [
{
"message": "Record not found in recycle bin",
"statusCode": "ENTITY_IS_NOT_IN_RECYCLE_BIN"
}
]
}
],
"success": false,
"errors": []
}
}
```
---
### 3. 流程提交
#### 接口说明
提交记录到审批流程，触发审批流程或其他自动化流程。支持添加审批评论。
- **接口名称**：ProcessSubmitRequest
- **请求方式**：POST
- **请求路径**：`/partner/advanced/process-submit-request`
- **权限要求**：`@PreAuthorize("@ss.hasPermi('partner:advanced:processSubmit')")`
#### 请求参数
| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| objectId | String | 是 | 对象 ID，格式为 18 位 Salesforce ID |
| comments | String | 否 | 审批评论，可选 |
#### 请求示例
```json
{
"objectId": "001xx0000001Gw2EAA",
"comments": "请审批此记录"
}
```
#### 响应参数
| 参数名 | 类型 | 说明 |
|--------|------|------|
| code | Integer | 状态码（200 成功，其他失败） |
| msg | String | 提示信息 |
| data | Object | 响应数据 |
| data.processInstanceId | String | 流程实例 ID |
| data.success | Boolean | 是否成功 |
| data.errors | Array | 错误信息列表 |
| data.errors[].message | String | 错误消息 |
| data.errors[].statusCode | String | 错误状态码 |
#### 成功示例
```json
{
"code": 200,
"msg": "流程提交成功",
"data": {
"processInstanceId": "04gxx0000001Gw2EAA",
"success": true,
"errors": []
}
}
```
#### 失败示例
```json
{
"code": 200,
"msg": "流程提交失败",
"data": {
"processInstanceId": null,
"success": false,
"errors": [
{
"message": "Process not found",
"statusCode": "INVALID_OPERATION"
}
]
}
}
```
---
### 4. 获取用户信息
#### 接口说明
获取当前登录用户的详细信息。**注意：此接口复用认证和会话管理子需求的实现。**
- **接口名称**：GetUserInfo
- **请求方式**：GET
- **请求路径**：`/partner/advanced/user-info`
- **权限要求**：`@PreAuthorize("@ss.hasPermi('partner:advanced:userInfo')")`
#### 请求参数
无
#### 响应参数
| 参数名 | 类型 | 说明 |
|--------|------|------|
| code | Integer | 状态码（200 成功，其他失败） |
| msg | String | 提示信息 |
| data | Object | 响应数据 |
| data.userId | String | 用户 ID |
| data.userName | String | 用户名 |
| data.userFullName | String | 用户全名 |
| data.userEmail | String | 用户邮箱 |
| data.organizationId | String | 组织 ID |
| data.organizationName | String | 组织名称 |
| data.userLanguage | String | 用户语言 |
| data.userTimeZone | String | 用户时区 |
| data.currencySymbol | String | 货币符号 |
| data.success | Boolean | 是否成功 |
| data.errors | Array | 错误信息列表 |
#### 成功示例
```json
{
"code": 200,
"msg": "获取用户信息成功",
"data": {
"userId": "005xx0000001Gw2EAA",
"userName": "john.doe@example.com",
"userFullName": "John Doe",
"userEmail": "john.doe@example.com",
"organizationId": "00Dxx0000001Gw2EAA",
"organizationName": "Your Organization",
"userLanguage": "en_US",
"userTimeZone": "America/Los_Angeles",
"currencySymbol": "$",
"success": true,
"errors": []
}
}
```
---
### 5. 获取服务器时间戳
#### 接口说明
获取 Salesforce 服务器的当前时间戳，返回 ISO 8601 格式的时间戳和时区信息。
- **接口名称**：GetServerTimestamp
- **请求方式**：GET
- **请求路径**：`/partner/advanced/server-timestamp`
- **权限要求**：`@PreAuthorize("@ss.hasPermi('partner:advanced:serverTimestamp')")`
#### 请求参数
无
#### 响应参数
| 参数名 | 类型 | 说明 |
|--------|------|------|
| code | Integer | 状态码（200 成功，其他失败） |
| msg | String | 提示信息 |
| data | Object | 响应数据 |
| data.timestamp | String | 服务器时间戳，ISO 8601 格式（yyyy-MM-dd'T'HH:mm:ss.SSS'Z'） |
| data.timeZone | String | 服务器时区 |
| data.success | Boolean | 是否成功 |
| data.errors | Array | 错误信息列表 |
#### 成功示例
```json
{
"code": 200,
"msg": "获取服务器时间戳成功",
"data": {
"timestamp": "2026-02-02T10:30:00.000Z",
"timeZone": "America/Los_Angeles",
"success": true,
"errors": []
}
}
```
## 错误码
| 错误码 | 错误消息 | 说明 |
|--------|----------|------|
| CANNOT_UPDATE_CONVERTED_LEAD | 无法更新已转换的线索 | 线索已被转换，无法再次转换 |
| INVALID_LEAD_ID | 无效的线索 ID | 线索 ID 格式不正确或线索不存在 |
| INVALID_ACCOUNT_ID | 无效的账户 ID | 账户 ID 格式不正确或账户不存在 |
| INVALID_CONTACT_ID | 无效的联系人 ID | 联系人 ID 格式不正确或联系人不存在 |
| INVALID_OPPORTUNITY_ID | 无效的商机 ID | 商机 ID 格式不正确或商机不存在 |
| INVALID_CONVERTED_STATUS | 无效的转换状态 | 转换状态不存在或无效 |
| INVALID_ID | 无效的记录 ID | 记录 ID 格式不正确或记录不存在 |
| ENTITY_IS_DELETED | 记录已删除 | 记录已被删除 |
| ENTITY_IS_NOT_IN_RECYCLE_BIN | 记录不在回收站中 | 记录不在回收站中，无法清空 |
| INVALID_OPERATION | 无效操作 | 该操作不支持或无效 |
| INSUFFICIENT_ACCESS | 权限不足 | 当前用户没有执行该操作的权限 |
| OPERATION_FAILED | 操作失败 | 操作执行失败 |
| PROCESS_SUBMISSION_FAILED | 流程提交失败 | 流程提交失败 |
| INVALID_OBJECT_ID | 无效的对象 ID | 对象 ID 格式不正确或对象不存在 |
## 注意事项
1. **线索转换**：
- 线索转换后，原线索将被标记为已转换，无法再次转换
- 如果未指定 accountId、contactId、opportunityId，系统将自动创建新记录
- overwriteLeadSource 为 true 时，将覆盖线索的来源字段
- doNotCreateOpportunity 为 true 时，将不创建商机
2. **清空回收站**：
- 只能删除已在回收站中的记录
- 删除后记录将永久删除，无法恢复
- 最多支持 200 个记录同时删除
- 支持部分失败情况，返回每个记录的删除结果
3. **流程提交**：
- 用于触发审批流程或其他自动化流程
- 返回流程实例 ID，可用于查询流程状态
- 评论参数可选
4. **获取用户信息**：
- 复用认证和会话管理子需求的实现
- 返回当前登录用户的详细信息
5. **获取服务器时间戳**：
- 返回 ISO 8601 格式的时间戳
- 时区为 Salesforce 组织的时区
- 用于同步本地时间与服务器时间
## 相关文档
- [需求文档](../requirements/sub/2026-01-28-001-06-高级功能.md)
- [设计文档](../design/2026-02-02-006-高级功能-设计.md)
- [决策记录](../decisions/2026-02-02-006-ADR-高级功能技术选型.md)
- [变更日志](../changelog/2026-02-02-006-changelog.md)
- [复盘文档](../retros/2026-02-02-006-retro.md)
Reference in New Issue Copy Permalink