datai/datai-scenes/datai-scene-salesforce/docs/api-docs/2026-01-30-002-api.md

API 文档

元数据

• 需求编号：001
• 子需求编号：001-02
• 创建时间：2026-01-30
• 创建人：AI Assistant
• 版本号：v1.0.0

API 概述

本 API 文档描述了 Salesforce Partner API 的 CRUD 操作接口，包括 Create（创建）、Retrieve（查询）、Update（更新）、Delete（删除）、Upsert（更新或插入）、Merge（合并）六个核心操作。所有接口都支持单条记录和批量记录操作（最多 200 条），并提供完整的参数验证、异常处理、权限控制和 Swagger 文档。

核心功能

• 创建记录（Create）：创建新的 Salesforce 记录，支持单条记录和批量记录创建
• 查询记录（Retrieve）：查询 Salesforce 记录，支持单条记录和批量记录查询
• 更新记录（Update）：更新现有的 Salesforce 记录，支持单条记录和批量记录更新
• 删除记录（Delete）：删除 Salesforce 记录，支持单条记录和批量记录删除
• 更新或插入记录（Upsert）：更新或插入 Salesforce 记录，支持单条记录和批量记录 Upsert
• 合并记录（Merge）：合并三条 Salesforce 记录

技术栈

• 框架：Spring Boot 3.x、Spring Security 6.x、若依框架
• API 规范：RESTful API
• 文档工具：Swagger/OpenAPI
• 权限控制：Spring Security（@PreAuthorize）
• 参数验证：Spring Boot Validation
• 异常处理：datai-salesforce-common 模块异常体系

认证方式

所有接口都需要用户认证，使用 Spring Security 的 @PreAuthorize("@ss.hasLogin()") 注解进行权限控制。用户必须登录后才能访问这些接口。

基础 URL

http://localhost:8080/partner/crud

响应格式

所有接口使用统一的响应格式：

{
  "code": 200,
  "msg": "操作成功",
  "data": {}
}

参数名	类型	说明
code	Integer	状态码（200 成功，其他失败）
msg	String	提示信息
data	Object	返回数据

接口列表

接口 1：创建记录

功能描述

创建新的 Salesforce 记录，支持单条记录和批量记录创建（最多 200 条）。

请求方式

POST

请求路径

/partner/crud/create

请求参数

单条记录创建：

参数名	类型	必填	说明
objectType	String	是	对象类型（如 "Account"、"Contact"）
fields	Map<String, Object>	是	字段值（如 {"Name": "Test Account", "BillingCity": "San Francisco"}）
records	List<Map<String, Object>>	否	批量创建记录列表（如果提供，则忽略 objectType 和 fields）

批量记录创建：

参数名	类型	必填	说明
records	List<Map<String, Object>>	是	批量创建记录列表（最多 200 条）

请求示例

单条记录创建：

{
  "objectType": "Account",
  "fields": {
    "Name": "Test Account",
    "BillingCity": "San Francisco",
    "BillingState": "CA",
    "AnnualRevenue": 1000000.00
  }
}

批量记录创建：

{
  "records": [
    {
      "Name": "Account 1",
      "BillingCity": "San Francisco"
    },
    {
      "Name": "Account 2",
      "BillingCity": "New York"
    },
    {
      "Name": "Account 3",
      "BillingCity": "Los Angeles"
    }
  ]
}

响应参数

单条记录创建：

参数名	类型	说明
id	String	记录 ID
success	Boolean	是否成功
errors	List	错误信息列表
created	Boolean	是否创建

批量记录创建：

参数名	类型	说明
-	List	记录操作结果列表

响应示例

成功示例（单条记录）：

{
  "code": 200,
  "msg": "创建成功",
  "data": {
    "id": "001xx000003DHb2AAG",
    "success": true,
    "errors": [],
    "created": true
  }
}

成功示例（批量记录）：

{
  "code": 200,
  "msg": "批量创建成功",
  "data": [
    {
      "id": "001xx000003DHb2AAG",
      "success": true,
      "errors": [],
      "created": true
    },
    {
      "id": "001xx000003DHb3AAH",
      "success": true,
      "errors": [],
      "created": true
    },
    {
      "id": "001xx000003DHb4AAI",
      "success": true,
      "errors": [],
      "created": true
    }
  ]
}

失败示例：

{
  "code": 500,
  "msg": "创建记录失败: INVALID_FIELD: No such column 'InvalidField' on sobject of type Account",
  "data": null
}

错误码

错误码	说明
500	创建记录失败
INVALID_FIELD	字段不存在或无效
INVALID_ID	ID 无效
MALFORMED_QUERY	查询语法错误
INVALID_OPERATION	操作无效
DUPLICATE_VALUE	值重复
ENTITY_IS_DELETED	记录已删除
INSUFFICIENT_ACCESS	权限不足
INVALID_CROSS_REFERENCE_KEY	跨引用键无效

---

接口 2：查询记录

功能描述

查询 Salesforce 记录，支持单条记录和批量记录查询（最多 200 条）。

请求方式

GET

请求路径

/partner/crud/retrieve

请求参数

单条记录查询：

参数名	类型	必填	说明
objectType	String	是	对象类型（如 "Account"、"Contact"）
id	String	是	记录 ID
fieldNames	String	否	字段名称列表（逗号分隔，如 "Name,BillingCity,BillingState"）

批量记录查询：

参数名	类型	必填	说明
objectType	String	是	对象类型（如 "Account"、"Contact"）
ids	String	是	记录 ID 列表（逗号分隔，最多 200 条）
fieldNames	String	否	字段名称列表（逗号分隔，如 "Name,BillingCity,BillingState"）

请求示例

单条记录查询：

GET /partner/crud/retrieve?objectType=Account&id=001xx000003DHb2AAG&fieldNames=Name,BillingCity,BillingState

批量记录查询：

GET /partner/crud/retrieve?objectType=Account&ids=001xx000003DHb2AAG,001xx000003DHb3AAH,001xx000003DHb4AAI&fieldNames=Name,BillingCity,BillingState

响应参数

单条记录查询：

参数名	类型	说明
objectType	String	对象类型
id	String	记录 ID
fields	Map<String, Object>	字段值
success	Boolean	是否成功
errors	List	错误信息列表

批量记录查询：

参数名	类型	说明
-	List	查询结果列表

响应示例

成功示例（单条记录）：

{
  "code": 200,
  "msg": "查询成功",
  "data": {
    "objectType": "Account",
    "id": "001xx000003DHb2AAG",
    "fields": {
      "Name": "Test Account",
      "BillingCity": "San Francisco",
      "BillingState": "CA"
    },
    "success": true,
    "errors": []
  }
}

成功示例（批量记录）：

{
  "code": 200,
  "msg": "查询成功",
  "data": [
    {
      "objectType": "Account",
      "id": "001xx000003DHb2AAG",
      "fields": {
        "Name": "Account 1",
        "BillingCity": "San Francisco",
        "BillingState": "CA"
      },
      "success": true,
      "errors": []
    },
    {
      "objectType": "Account",
      "id": "001xx000003DHb3AAH",
      "fields": {
        "Name": "Account 2",
        "BillingCity": "New York",
        "BillingState": "NY"
      },
      "success": true,
      "errors": []
    },
    {
      "objectType": "Account",
      "id": "001xx000003DHb4AAI",
      "fields": {
        "Name": "Account 3",
        "BillingCity": "Los Angeles",
        "BillingState": "CA"
      },
      "success": true,
      "errors": []
    }
  ]
}

失败示例：

{
  "code": 500,
  "msg": "查询记录失败: INVALID_ID: Invalid ID: 001xx000003DHb2AAG",
  "data": null
}

错误码

错误码	说明
500	查询记录失败
INVALID_ID	ID 无效
INVALID_FIELD	字段不存在或无效
ENTITY_IS_DELETED	记录已删除
INSUFFICIENT_ACCESS	权限不足

---

接口 3：更新记录

功能描述

更新现有的 Salesforce 记录，支持单条记录和批量记录更新（最多 200 条）。

请求方式

PUT

请求路径

/partner/crud/update

请求参数

单条记录更新：

参数名	类型	必填	说明
objectType	String	是	对象类型（如 "Account"、"Contact"）
id	String	是	记录 ID
fields	Map<String, Object>	是	字段值（如 {"BillingCity": "New York"}）
records	List	否	批量更新记录列表（如果提供，则忽略 objectType、id 和 fields）

批量记录更新：

参数名	类型	必填	说明
records	List	是	批量更新记录列表（最多 200 条）

UpdateRecordItem：

参数名	类型	必填	说明
id	String	是	记录 ID
fields	Map<String, Object>	是	字段值

请求示例

单条记录更新：

{
  "objectType": "Account",
  "id": "001xx000003DHb2AAG",
  "fields": {
    "BillingCity": "New York",
    "BillingState": "NY",
    "AnnualRevenue": 2000000.00
  }
}

批量记录更新：

{
  "records": [
    {
      "id": "001xx000003DHb2AAG",
      "fields": {
        "BillingCity": "New York",
        "BillingState": "NY"
      }
    },
    {
      "id": "001xx000003DHb3AAH",
      "fields": {
        "BillingCity": "Los Angeles",
        "BillingState": "CA"
      }
    },
    {
      "id": "001xx000003DHb4AAI",
      "fields": {
        "BillingCity": "Chicago",
        "BillingState": "IL"
      }
    }
  ]
}

响应参数

单条记录更新：

参数名	类型	说明
id	String	记录 ID
success	Boolean	是否成功
errors	List	错误信息列表

批量记录更新：

参数名	类型	说明
-	List	记录操作结果列表

响应示例

成功示例（单条记录）：

{
  "code": 200,
  "msg": "更新成功",
  "data": {
    "id": "001xx000003DHb2AAG",
    "success": true,
    "errors": []
  }
}

成功示例（批量记录）：

{
  "code": 200,
  "msg": "批量更新成功",
  "data": [
    {
      "id": "001xx000003DHb2AAG",
      "success": true,
      "errors": []
    },
    {
      "id": "001xx000003DHb3AAH",
      "success": true,
      "errors": []
    },
    {
      "id": "001xx000003DHb4AAI",
      "success": true,
      "errors": []
    }
  ]
}

失败示例：

{
  "code": 500,
  "msg": "更新记录失败: INVALID_ID: Invalid ID: 001xx000003DHb2AAG",
  "data": null
}

错误码

错误码	说明
500	更新记录失败
INVALID_ID	ID 无效
INVALID_FIELD	字段不存在或无效
ENTITY_IS_DELETED	记录已删除
INSUFFICIENT_ACCESS	权限不足

---

接口 4：删除记录

功能描述

删除 Salesforce 记录，支持单条记录和批量记录删除（最多 200 条）。

请求方式

DELETE

请求路径

/partner/crud/delete

请求参数

单条记录删除：

参数名	类型	必填	说明
objectType	String	是	对象类型（如 "Account"、"Contact"）
id	String	是	记录 ID
ids	String	否	记录 ID 列表（逗号分隔，最多 200 条）

批量记录删除：

参数名	类型	必填	说明
objectType	String	是	对象类型（如 "Account"、"Contact"）
ids	String	是	记录 ID 列表（逗号分隔，最多 200 条）

请求示例

单条记录删除：

DELETE /partner/crud/delete?objectType=Account&id=001xx000003DHb2AAG

批量记录删除：

DELETE /partner/crud/delete?objectType=Account&ids=001xx000003DHb2AAG,001xx000003DHb3AAH,001xx000003DHb4AAI

响应参数

单条记录删除：

参数名	类型	说明
id	String	记录 ID
success	Boolean	是否成功
errors	List	错误信息列表

批量记录删除：

参数名	类型	说明
-	List	记录操作结果列表

响应示例

成功示例（单条记录）：

{
  "code": 200,
  "msg": "删除成功",
  "data": {
    "id": "001xx000003DHb2AAG",
    "success": true,
    "errors": []
  }
}

成功示例（批量记录）：

{
  "code": 200,
  "msg": "批量删除成功",
  "data": [
    {
      "id": "001xx000003DHb2AAG",
      "success": true,
      "errors": []
    },
    {
      "id": "001xx000003DHb3AAH",
      "success": true,
      "errors": []
    },
    {
      "id": "001xx000003DHb4AAI",
      "success": true,
      "errors": []
    }
  ]
}

失败示例：

{
  "code": 500,
  "msg": "删除记录失败: INVALID_ID: Invalid ID: 001xx000003DHb2AAG",
  "data": null
}

错误码

错误码	说明
500	删除记录失败
INVALID_ID	ID 无效
ENTITY_IS_DELETED	记录已删除
ENTITY_IS_LOCKED_FOR_DELETION	记录被锁定，无法删除
INSUFFICIENT_ACCESS	权限不足

---

接口 5：更新或插入记录

功能描述

更新或插入 Salesforce 记录，支持单条记录和批量记录 Upsert（最多 200 条）。如果记录存在则更新，如果不存在则创建。

请求方式

POST

请求路径

/partner/crud/upsert

请求参数

单条记录 Upsert：

参数名	类型	必填	说明
objectType	String	是	对象类型（如 "Account"、"Contact"）
externalIdField	String	是	外部 ID 字段名称（如 "ExternalId__c"）
fields	Map<String, Object>	是	字段值（必须包含外部 ID 字段的值）
records	List<Map<String, Object>>	否	批量 Upsert 记录列表（如果提供，则忽略 objectType、externalIdField 和 fields）

批量记录 Upsert：

参数名	类型	必填	说明
objectType	String	是	对象类型（如 "Account"、"Contact"）
externalIdField	String	是	外部 ID 字段名称（如 "ExternalId__c"）
records	List<Map<String, Object>>	是	批量 Upsert 记录列表（最多 200 条，每条记录必须包含外部 ID 字段的值）

请求示例

单条记录 Upsert：

{
  "objectType": "Account",
  "externalIdField": "ExternalId__c",
  "fields": {
    "ExternalId__c": "EXT001",
    "Name": "Test Account",
    "BillingCity": "San Francisco"
  }
}

批量记录 Upsert：

{
  "objectType": "Account",
  "externalIdField": "ExternalId__c",
  "records": [
    {
      "ExternalId__c": "EXT001",
      "Name": "Account 1",
      "BillingCity": "San Francisco"
    },
    {
      "ExternalId__c": "EXT002",
      "Name": "Account 2",
      "BillingCity": "New York"
    },
    {
      "ExternalId__c": "EXT003",
      "Name": "Account 3",
      "BillingCity": "Los Angeles"
    }
  ]
}

响应参数

单条记录 Upsert：

参数名	类型	说明
id	String	记录 ID
success	Boolean	是否成功
errors	List	错误信息列表
created	Boolean	是否创建

批量记录 Upsert：

参数名	类型	说明
-	List	记录操作结果列表

响应示例

成功示例（单条记录，创建）：

{
  "code": 200,
  "msg": "Upsert 成功",
  "data": {
    "id": "001xx000003DHb2AAG",
    "success": true,
    "errors": [],
    "created": true
  }
}

成功示例（单条记录，更新）：

{
  "code": 200,
  "msg": "Upsert 成功",
  "data": {
    "id": "001xx000003DHb2AAG",
    "success": true,
    "errors": [],
    "created": false
  }
}

成功示例（批量记录）：

{
  "code": 200,
  "msg": "批量 Upsert 成功",
  "data": [
    {
      "id": "001xx000003DHb2AAG",
      "success": true,
      "errors": [],
      "created": true
    },
    {
      "id": "001xx000003DHb3AAH",
      "success": true,
      "errors": [],
      "created": false
    },
    {
      "id": "001xx000003DHb4AAI",
      "success": true,
      "errors": [],
      "created": true
    }
  ]
}

失败示例：

{
  "code": 500,
  "msg": "Upsert 记录失败: INVALID_FIELD: No such column 'ExternalId__c' on sobject of type Account",
  "data": null
}

错误码

错误码	说明
500	Upsert 记录失败
INVALID_FIELD	字段不存在或无效
INVALID_ID	ID 无效
ENTITY_IS_DELETED	记录已删除
INSUFFICIENT_ACCESS	权限不足
DUPLICATE_VALUE	值重复

---

接口 6：合并记录

功能描述

合并三条 Salesforce 记录，将两条记录合并到主记录中。

请求方式

POST

请求路径

/partner/crud/merge

请求参数

参数名	类型	必填	说明
objectType	String	是	对象类型（如 "Account"、"Contact"）
masterRecordId	String	是	主记录 ID
recordToMergeIds	List	是	待合并记录 ID 列表（最多 2 条）

请求示例

{
  "objectType": "Account",
  "masterRecordId": "001xx000003DHb2AAG",
  "recordToMergeIds": [
    "001xx000003DHb3AAH",
    "001xx000003DHb4AAI"
  ]
}

响应参数

参数名	类型	说明
id	String	记录 ID
success	Boolean	是否成功
errors	List	错误信息列表

响应示例

成功示例：

{
  "code": 200,
  "msg": "合并成功",
  "data": {
    "id": "001xx000003DHb2AAG",
    "success": true,
    "errors": []
  }
}

失败示例：

{
  "code": 500,
  "msg": "合并记录失败: INVALID_ID: Invalid ID: 001xx000003DHb2AAG",
  "data": null
}

错误码

错误码	说明
500	合并记录失败
INVALID_ID	ID 无效
ENTITY_IS_DELETED	记录已删除
INSUFFICIENT_ACCESS	权限不足
CANNOT_MERGE_RECORD	无法合并记录（如记录类型不同）

---

数据模型

RecordResultVo

记录操作结果。

字段名	类型	说明
id	String	记录 ID
success	Boolean	是否成功
errors	List	错误信息列表
created	Boolean	是否创建（仅 Upsert 操作）

RetrieveResultVo

查询结果。

字段名	类型	说明
objectType	String	对象类型
id	String	记录 ID
fields	Map<String, Object>	字段值
success	Boolean	是否成功
errors	List	错误信息列表

ErrorVo

错误信息。

字段名	类型	说明
statusCode	String	状态代码
message	String	错误消息
fields	List	相关字段列表

错误码

通用错误码

错误码	说明
200	操作成功
400	请求参数错误
401	未授权
403	权限不足
404	资源不存在
500	服务器内部错误

Salesforce 错误码

错误码	说明
INVALID_FIELD	字段不存在或无效
INVALID_ID	ID 无效
MALFORMED_QUERY	查询语法错误
INVALID_OPERATION	操作无效
DUPLICATE_VALUE	值重复
ENTITY_IS_DELETED	记录已删除
ENTITY_IS_LOCKED_FOR_DELETION	记录被锁定，无法删除
INSUFFICIENT_ACCESS	权限不足
INVALID_CROSS_REFERENCE_KEY	跨引用键无效
CANNOT_MERGE_RECORD	无法合并记录

相关文档

• 需求文档
• 设计文档
• 决策记录
• 提示词
• 变更日志
• 复盘文档
• 会话记录