970 lines
20 KiB
Markdown
970 lines
20 KiB
Markdown
# 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
|
||
```
|
||
|
||
### 响应格式
|
||
|
||
所有接口使用统一的响应格式：
|
||
|
||
```json
|
||
{
|
||
"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 条） |
|
||
|
||
#### 请求示例
|
||
|
||
**单条记录创建**：
|
||
|
||
```json
|
||
{
|
||
"objectType": "Account",
|
||
"fields": {
|
||
"Name": "Test Account",
|
||
"BillingCity": "San Francisco",
|
||
"BillingState": "CA",
|
||
"AnnualRevenue": 1000000.00
|
||
}
|
||
}
|
||
```
|
||
|
||
**批量记录创建**：
|
||
|
||
```json
|
||
{
|
||
"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<ErrorVo> | 错误信息列表 |
|
||
| created | Boolean | 是否创建 |
|
||
|
||
**批量记录创建**：
|
||
|
||
| 参数名 | 类型 | 说明 |
|
||
|--------|------|------|
|
||
| - | List<RecordResultVo> | 记录操作结果列表 |
|
||
|
||
#### 响应示例
|
||
|
||
**成功示例（单条记录）**：
|
||
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"msg": "创建成功",
|
||
"data": {
|
||
"id": "001xx000003DHb2AAG",
|
||
"success": true,
|
||
"errors": [],
|
||
"created": true
|
||
}
|
||
}
|
||
```
|
||
|
||
**成功示例（批量记录）**：
|
||
|
||
```json
|
||
{
|
||
"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
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
**失败示例**：
|
||
|
||
```json
|
||
{
|
||
"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<ErrorVo> | 错误信息列表 |
|
||
|
||
**批量记录查询**：
|
||
|
||
| 参数名 | 类型 | 说明 |
|
||
|--------|------|------|
|
||
| - | List<RetrieveResultVo> | 查询结果列表 |
|
||
|
||
#### 响应示例
|
||
|
||
**成功示例（单条记录）**：
|
||
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"msg": "查询成功",
|
||
"data": {
|
||
"objectType": "Account",
|
||
"id": "001xx000003DHb2AAG",
|
||
"fields": {
|
||
"Name": "Test Account",
|
||
"BillingCity": "San Francisco",
|
||
"BillingState": "CA"
|
||
},
|
||
"success": true,
|
||
"errors": []
|
||
}
|
||
}
|
||
```
|
||
|
||
**成功示例（批量记录）**：
|
||
|
||
```json
|
||
{
|
||
"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": []
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
**失败示例**：
|
||
|
||
```json
|
||
{
|
||
"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<UpdateRecordItem> | 否 | 批量更新记录列表（如果提供，则忽略 objectType、id 和 fields） |
|
||
|
||
**批量记录更新**：
|
||
|
||
| 参数名 | 类型 | 必填 | 说明 |
|
||
|--------|------|------|------|
|
||
| records | List<UpdateRecordItem> | 是 | 批量更新记录列表（最多 200 条） |
|
||
|
||
**UpdateRecordItem**：
|
||
|
||
| 参数名 | 类型 | 必填 | 说明 |
|
||
|--------|------|------|------|
|
||
| id | String | 是 | 记录 ID |
|
||
| fields | Map<String, Object> | 是 | 字段值 |
|
||
|
||
#### 请求示例
|
||
|
||
**单条记录更新**：
|
||
|
||
```json
|
||
{
|
||
"objectType": "Account",
|
||
"id": "001xx000003DHb2AAG",
|
||
"fields": {
|
||
"BillingCity": "New York",
|
||
"BillingState": "NY",
|
||
"AnnualRevenue": 2000000.00
|
||
}
|
||
}
|
||
```
|
||
|
||
**批量记录更新**：
|
||
|
||
```json
|
||
{
|
||
"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<ErrorVo> | 错误信息列表 |
|
||
|
||
**批量记录更新**：
|
||
|
||
| 参数名 | 类型 | 说明 |
|
||
|--------|------|------|
|
||
| - | List<RecordResultVo> | 记录操作结果列表 |
|
||
|
||
#### 响应示例
|
||
|
||
**成功示例（单条记录）**：
|
||
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"msg": "更新成功",
|
||
"data": {
|
||
"id": "001xx000003DHb2AAG",
|
||
"success": true,
|
||
"errors": []
|
||
}
|
||
}
|
||
```
|
||
|
||
**成功示例（批量记录）**：
|
||
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"msg": "批量更新成功",
|
||
"data": [
|
||
{
|
||
"id": "001xx000003DHb2AAG",
|
||
"success": true,
|
||
"errors": []
|
||
},
|
||
{
|
||
"id": "001xx000003DHb3AAH",
|
||
"success": true,
|
||
"errors": []
|
||
},
|
||
{
|
||
"id": "001xx000003DHb4AAI",
|
||
"success": true,
|
||
"errors": []
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
**失败示例**：
|
||
|
||
```json
|
||
{
|
||
"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<ErrorVo> | 错误信息列表 |
|
||
|
||
**批量记录删除**：
|
||
|
||
| 参数名 | 类型 | 说明 |
|
||
|--------|------|------|
|
||
| - | List<RecordResultVo> | 记录操作结果列表 |
|
||
|
||
#### 响应示例
|
||
|
||
**成功示例（单条记录）**：
|
||
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"msg": "删除成功",
|
||
"data": {
|
||
"id": "001xx000003DHb2AAG",
|
||
"success": true,
|
||
"errors": []
|
||
}
|
||
}
|
||
```
|
||
|
||
**成功示例（批量记录）**：
|
||
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"msg": "批量删除成功",
|
||
"data": [
|
||
{
|
||
"id": "001xx000003DHb2AAG",
|
||
"success": true,
|
||
"errors": []
|
||
},
|
||
{
|
||
"id": "001xx000003DHb3AAH",
|
||
"success": true,
|
||
"errors": []
|
||
},
|
||
{
|
||
"id": "001xx000003DHb4AAI",
|
||
"success": true,
|
||
"errors": []
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
**失败示例**：
|
||
|
||
```json
|
||
{
|
||
"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**：
|
||
|
||
```json
|
||
{
|
||
"objectType": "Account",
|
||
"externalIdField": "ExternalId__c",
|
||
"fields": {
|
||
"ExternalId__c": "EXT001",
|
||
"Name": "Test Account",
|
||
"BillingCity": "San Francisco"
|
||
}
|
||
}
|
||
```
|
||
|
||
**批量记录 Upsert**：
|
||
|
||
```json
|
||
{
|
||
"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<ErrorVo> | 错误信息列表 |
|
||
| created | Boolean | 是否创建 |
|
||
|
||
**批量记录 Upsert**：
|
||
|
||
| 参数名 | 类型 | 说明 |
|
||
|--------|------|------|
|
||
| - | List<RecordResultVo> | 记录操作结果列表 |
|
||
|
||
#### 响应示例
|
||
|
||
**成功示例（单条记录，创建）**：
|
||
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"msg": "Upsert 成功",
|
||
"data": {
|
||
"id": "001xx000003DHb2AAG",
|
||
"success": true,
|
||
"errors": [],
|
||
"created": true
|
||
}
|
||
}
|
||
```
|
||
|
||
**成功示例（单条记录，更新）**：
|
||
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"msg": "Upsert 成功",
|
||
"data": {
|
||
"id": "001xx000003DHb2AAG",
|
||
"success": true,
|
||
"errors": [],
|
||
"created": false
|
||
}
|
||
}
|
||
```
|
||
|
||
**成功示例（批量记录）**：
|
||
|
||
```json
|
||
{
|
||
"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
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
**失败示例**：
|
||
|
||
```json
|
||
{
|
||
"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<String> | 是 | 待合并记录 ID 列表（最多 2 条） |
|
||
|
||
#### 请求示例
|
||
|
||
```json
|
||
{
|
||
"objectType": "Account",
|
||
"masterRecordId": "001xx000003DHb2AAG",
|
||
"recordToMergeIds": [
|
||
"001xx000003DHb3AAH",
|
||
"001xx000003DHb4AAI"
|
||
]
|
||
}
|
||
```
|
||
|
||
#### 响应参数
|
||
|
||
| 参数名 | 类型 | 说明 |
|
||
|--------|------|------|
|
||
| id | String | 记录 ID |
|
||
| success | Boolean | 是否成功 |
|
||
| errors | List<ErrorVo> | 错误信息列表 |
|
||
|
||
#### 响应示例
|
||
|
||
**成功示例**：
|
||
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"msg": "合并成功",
|
||
"data": {
|
||
"id": "001xx000003DHb2AAG",
|
||
"success": true,
|
||
"errors": []
|
||
}
|
||
}
|
||
```
|
||
|
||
**失败示例**：
|
||
|
||
```json
|
||
{
|
||
"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<ErrorVo> | 错误信息列表 |
|
||
| created | Boolean | 是否创建（仅 Upsert 操作） |
|
||
|
||
### RetrieveResultVo
|
||
|
||
查询结果。
|
||
|
||
| 字段名 | 类型 | 说明 |
|
||
|--------|------|------|
|
||
| objectType | String | 对象类型 |
|
||
| id | String | 记录 ID |
|
||
| fields | Map<String, Object> | 字段值 |
|
||
| success | Boolean | 是否成功 |
|
||
| errors | List<ErrorVo> | 错误信息列表 |
|
||
|
||
### ErrorVo
|
||
|
||
错误信息。
|
||
|
||
| 字段名 | 类型 | 说明 |
|
||
|--------|------|------|
|
||
| statusCode | String | 状态代码 |
|
||
| message | String | 错误消息 |
|
||
| fields | List<String> | 相关字段列表 |
|
||
|
||
## 错误码
|
||
|
||
### 通用错误码
|
||
|
||
| 错误码 | 说明 |
|
||
|--------|------|
|
||
| 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 | 无法合并记录 |
|
||
|
||
## 相关文档
|
||
|
||
- [需求文档](../requirements/sub/2026-01-28-001-02-CRUD操作.md)
|
||
- [设计文档](../design/2026-01-30-002-CRUD操作-设计.md)
|
||
- [决策记录](../decisions/2026-01-30-002-ADR-CRUD操作技术选型.md)
|
||
- [提示词](../prompts/2026-01-30-002-prompt-CRUD操作.md)
|
||
- [变更日志](../changelog/2026-01-30-002-changelog.md)
|
||
- [复盘文档](../retros/2026-01-30-002-retro.md)
|
||
- [会话记录](../sessions/2026-01-28-001-session.md)
|