Zoho crm Logo

合并记录 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应从同一记录中使用。
  • MANDATORY_NOT_FOUNDHTTP 400
    • 字段JSON数组中的API名称不能为空
      解决方法: 在合并JSON数组中指定有效的API名称。
    • 合并JSON数组中的API名称不能为空
      解决方法: 在字段JSON数组中指定有效的API名称。
    • 子记录的ID为空
      解决方法: 为子记录指定有效的ID。
  • INVALID_MODULEHTTP 400

    给定的模块名称似乎无效
    解决方法:请在URL中指定模块名称。请参阅本页开头的请求URL部分。

  • 不允许HTTP 400
    • 此记录ID不允许合并
      解决方案:您尝试合并的记录已被安排合并。请指定另一个有效的记录ID。
    • 记录不允许合并
      解决方案:该记录当前被锁定或处于审批/审核流程中。请解锁记录后再进行合并,或联系管理员。
    • 关闭日期将根据主记录自动填充
      解决方案:不要指定关闭日期字段。关闭日期将自动从主记录中获取。
    • 阶段字段将根据选择的管道自动填充
      解决方案:不要指定阶段字段。阶段值将从所选管道中自动获取。如果您指定子记录的管道,则阶段值将从相应的管道中获取。
    • 只有Open的交易可以合并
      解决方案:不要使用已关闭的交易。合并操作只会在Open的交易中进行。
    • 概率和预期收入字段将根据选择的阶段自动填充
      解决方案:不要指定预期收入和概率字段。这些字段的值将根据阶段自动获取。
  • DUPLICATE_DATAHTTP 400
    • 相同的ID已被指定用于合并
      解决方案: 您已为主记录和/或子记录指定了相同的记录ID。请指定不同的记录ID进行合并。
    • 字段已在合并中的其他记录中提到
      解决方案: 您已指定此字段。请仅在master_record_fields数组或其中一个data数组中指定每个字段一次。
  • DEPENDENT_FIELD_MISSINGHTTP 400
    • 主记录未指定 _data 数组
      解决方法:在 _data JSON 数组中指定文件或图像的唯一 ID。主记录中的 File_Upload 或 Image_Upload 字段缺少依赖的 "id" 字段。
    • 子记录未提及 _data 数组
      解决方法:在 _data JSON 数组中指定文件或图像的唯一 ID。子记录中的 File_Upload 或 Image_Upload 字段缺少依赖的 "id" 字段。
  • 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"
        }
    ]
}