datai/datai-scenes/datai-scene-salesforce/docs/api-docs/2026-02-02-006-api.md

API 文档 - 高级功能

元数据

• 需求编号：001-06
• 创建时间：2026-02-02
• 创建人：AI Assistant
• 版本号：v1.0.0
• 关联需求：高级功能

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

请求示例

{
  "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	错误状态码

成功示例

{
  "code": 200,
  "msg": "线索转换成功",
  "data": {
    "accountId": "001xx0000001Gw2EAA",
    "contactId": "003xx0000001Gw2EAA",
    "opportunityId": "006xx0000001Gw2EAA",
    "leadId": "00Qxx0000001Gw2EAE",
    "success": true,
    "errors": []
  }
}

失败示例

{
  "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	是	记录 ID 列表，最多 200 个，每个 ID 格式为 18 位 Salesforce ID

请求示例

{
  "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	整体错误信息列表

成功示例

{
  "code": 200,
  "msg": "清空回收站成功",
  "data": {
    "results": [
      {
        "id": "001xx0000001Gw2EAA",
        "success": true,
        "errors": []
      },
      {
        "id": "001xx0000001Gw3EAA",
        "success": true,
        "errors": []
      },
      {
        "id": "001xx0000001Gw4EAA",
        "success": true,
        "errors": []
      }
    ],
    "success": true,
    "errors": []
  }
}

部分失败示例

{
  "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	否	审批评论，可选

请求示例

{
  "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	错误状态码

成功示例

{
  "code": 200,
  "msg": "流程提交成功",
  "data": {
    "processInstanceId": "04gxx0000001Gw2EAA",
    "success": true,
    "errors": []
  }
}

失败示例

{
  "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	错误信息列表

成功示例

{
  "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	错误信息列表

成功示例

{
  "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 组织的时区
   • 用于同步本地时间与服务器时间

相关文档

• 需求文档
• 设计文档
• 决策记录
• 变更日志
• 复盘文档