合并记录 API
此 API 将最多三个重复记录合并为一个,并删除重复记录。您可以指定一个作为主记录,在合并后保留,另外两个作为子记录,将被删除。您可以指定子记录中的字段值用于合并后的记录,并保留主记录中其余字段的值。
要了解更多关于查找和合并功能的信息,请参阅我们的帮助文档。
目的
将最多三个重复记录合并为一个记录并删除重复记录。
端点
- POST /{module_api_name}/{master-record_ID}/actions/merge
请求详情
请求URL
{api-domain}/crm/{version}/{module_api_name}/{master-record_ID}/actions/merge
支持的模块
潜在客户、联系人、Account、销售机会、Vendors和自定义。
标题
授权: Zoho-oauthtoken d92d4xxxxxxxxxxxxx15f52
范围
ZohoCRM.modules.{module_name}.{operation_type}
可能的模块Name
线索、联系人、潜在客户、Account、Vendors和自定义。
可能的操作类型
写入 - Edit 模块中的记录。
全部 - 完全访问记录。
示例请求
Copiedcurl "https://www.zohoapis.com/crm/v8/Leads/2423488000000500064/actions/merge"
-X POST
-d @input.json
-H "Authorization: Zoho-oauthtoken 1000.8cb99dxxxxxxxxxxxxx9be93.9b8xxxxxxxxxxxxxxxf"
输入 JSON
- master_record_fields JSON array, optional
指定文件上传和图片上传字段的 API 名称,以在合并记录中保留它们。
- api_name string, mandatory
表示文件上传或图片上传字段的 API 名称。
- _data JSON array, optional
表示文件或附件的唯一 ID。此字段专门用于记录中的文件上传和图片上传字段。使用 GET Records API 来检索文件或附件的唯一 ID。
- id string, mandatory
附件的唯一 ID。
- data JSON array, mandatory
一个对象数组,指定子记录和您希望在合并记录中使用其值的字段。
id string, mandatory代表子记录的唯一ID。
- _fields JSON array, mandatory
指定子记录中您希望合并到主记录中的字段的API名称。
- api_name string, mandatory
代表您希望在合并中包含的子记录中字段的API名称。
笔记
- 如果未指定图像上传或文件上传,主记录中的所有图像/文件将被保留。
- 如果提供 '_data': null ,则该特定字段的所有图像/文件将被删除。
- 如果子记录在其任何相关列表中有超过1000条记录,则合并操作将被调度。这意味着它执行的是异步操作,您的请求响应不会立即可用。相反,您将在响应中收到一个唯一的job_id。您可以使用此job_id来检索合并操作的Status。有关详细信息,请参阅获取记录合并Status API。
- merge JSON 数组只能包含一个对象,而 data JSON 数组最多可以有两个子记录。超出这些限制将导致错误。
- 每个字段在master_record_fields和data数组中只能提到一次。
- 只有未完成的交易可以合并;已完成的交易将触发错误。
- 关闭日期、阶段、概率和预期收入字段将根据主记录自动填充,不应在请求中指定。
- 当前被锁定或处于审批/审核过程中的记录无法合并。
示例输入
Copied{
"merge": [
{
"master_record_fields": [
{
"api_name": "Company"
},
{
"api_name": "File_Upload",
"_data": [
{
"id": "2423488000000538058"
}
]
}
],
"data": [
{
"id": "2423488000000495876",
"_fields": [
{
"api_name": "Annual_Revenue"
},
{
"api_name": "Last_Name"
}
]
}
]
}
]
}可能的错误
- INVALID_DATAHTTP 400
- 主记录ID不可用
解决方案: 请指定一个有效的记录ID. - 合并JSON数组已达到其限制
解决方案: 合并JSON数组只能包含一个JSON对象。 - 数据JSON对象已达到其限制
解决方案: 数据JSON数组最多可以有两个值,对应两个子记录。 - 至少需要一个子记录ID进行合并
解决方案: 数据JSON数组不能为空。请指定有效数据。 - Reporting_To和Account_Name应属于同一记录
解决方案: Reporting_To和Account_Name应从同一记录中使用。
- 主记录ID不可用
- MANDATORY_NOT_FOUNDHTTP 400
- 字段JSON数组中的API名称不能为空
解决方法: 在合并JSON数组中指定有效的API名称。 - 合并JSON数组中的API名称不能为空
解决方法: 在字段JSON数组中指定有效的API名称。 - 子记录的ID为空
解决方法: 为子记录指定有效的ID。
- 字段JSON数组中的API名称不能为空
- INVALID_MODULEHTTP 400
给定的模块名称似乎无效
解决方法:请在URL中指定模块名称。请参阅本页开头的请求URL部分。 - 不允许HTTP 400
- 此记录ID不允许合并
解决方案:您尝试合并的记录已被安排合并。请指定另一个有效的记录ID。 - 记录不允许合并
解决方案:该记录当前被锁定或处于审批/审核流程中。请解锁记录后再进行合并,或联系管理员。 - 关闭日期将根据主记录自动填充
解决方案:不要指定关闭日期字段。关闭日期将自动从主记录中获取。 - 阶段字段将根据选择的管道自动填充
解决方案:不要指定阶段字段。阶段值将从所选管道中自动获取。如果您指定子记录的管道,则阶段值将从相应的管道中获取。 - 只有Open的交易可以合并
解决方案:不要使用已关闭的交易。合并操作只会在Open的交易中进行。 - 概率和预期收入字段将根据选择的阶段自动填充
解决方案:不要指定预期收入和概率字段。这些字段的值将根据阶段自动获取。
- 此记录ID不允许合并
- DUPLICATE_DATAHTTP 400
- 相同的ID已被指定用于合并
解决方案: 您已为主记录和/或子记录指定了相同的记录ID。请指定不同的记录ID进行合并。 - 字段已在合并中的其他记录中提到
解决方案: 您已指定此字段。请仅在master_record_fields数组或其中一个data数组中指定每个字段一次。
- 相同的ID已被指定用于合并
- DEPENDENT_FIELD_MISSINGHTTP 400
- 主记录未指定 _data 数组
解决方法:在 _data JSON 数组中指定文件或图像的唯一 ID。主记录中的 File_Upload 或 Image_Upload 字段缺少依赖的 "id" 字段。 - 子记录未提及 _data 数组
解决方法:在 _data JSON 数组中指定文件或图像的唯一 ID。子记录中的 File_Upload 或 Image_Upload 字段缺少依赖的 "id" 字段。
- 主记录未指定 _data 数组
- LIMIT_EXCEEDEDHTTP 400
给定文件的总数不能超过最大限制。
解决方法:请检查响应中的最大限制,例如,如果 "maximum_length": 1,这意味着允许附加图像或文件的最大长度为1。 - INVALID_REQUEST_METHODHTTP 400
请求方法不正确。
解决方法:使用 HTTP POST 方法来进行此 API 调用。任何其他请求方法都会导致此错误。 - INVALID_MODULEHTTP 400
给定的模块名称似乎无效
解决方法:您指定了一个无效的模块名称。
请指定一个有效的模块名称。 - OAUTH_SCOPE_MISMATCHHTTP 401
您用于进行此API调用的访问令牌不具有所需的范围。
解决方法:生成一个具有此API所需范围的新访问令牌。请参阅本页开头的范围部分以获取所需范围的列表。 - AUTHENTICATION_FAILUREHTTP 401
您未使用有效的访问令牌授权API调用。
解决方法:在请求头中包含有效的访问令牌以授权API调用。 - INVALID_URL_PATTERNHTTP 404
请求的URL不正确。
解决方法: 指定一个有效的请求URL。有关详细信息,请参阅本页开头的请求URL部分。 - INTERNAL_ERRORHTTP 500
服务器中出现意外且未处理的异常。
解决方法:请联系支持团队,邮箱:support@zohocrm.com。
示例响应
Copied{
"merge": [
{
"code": "SUCCESS",
"details": {
"id": "2423488000000500064"
},
"message": "The records have been merged successfully",
"status": "success"
}
]
}示例响应用于计划合并通话
Copied{
"merge": [
{
"code": "SCHEDULED",
"details": {
"job_id": "2423488000000513988"
},
"message": "The records have been scheduled for merge",
"status": "success"
}
]
}