Zoho crm Logo

插入或更新记录(上插)

目的

Upsert API 允许您根据重复检查字段的值插入新记录或更新已有记录。

工作原理:

  • 系统使用查重字段的值来检查重复记录。
  • 如果存在匹配的记录,则会进行更新。
  • 如果未找到匹配的记录,则插入一条新记录。

端点

  • POST /{module_api_name}/upsert

{module_api_name} : 要执行 upsert 操作的模块的 API 名称。

请求详情

请求 URL

{api-domain}/crm/{version}/{module_api_name}/upsert

支持的模块

潜在客户,Account,联系人,交易,活动,案例,解决方案,产品,Vendors,价格表,报价单,SalesOrders,采购Orders,Invoices,预约,预约改期历史,服务和自定义

标题

授权:Zoho-oauthtoken d92d4xxxxxxxxxxxxx15f52

If-Unmodified-Since:2024-01-15T15:26:49+05:30

范围

scope=ZohoCRM.modules.ALL
(或者)
scope=ZohoCRM.modules.{module_api_name}.{operation_type}

可能的模块名称

线索、客户、联系人、交易、活动、案例、解决方案、产品、供应商、价目表、报价、销售订单、采购订单、发票、预约、预约重排历史、服务以及自定义。

可能的操作类型

ALL - 完全访问该记录
WRITE - Edit模块中的记录
CREATE - 在模块中创建记录

样本请求

Copiedcurl "https://www.zohoapis.com/crm/v8/Leads/upsert"
-H "Authorization: Zoho-oauthtoken 1000.8cb99dxxxxxxxxxxxxx9be93.9b8xxxxxxxxxxxxxxxf"
-d "@upsertlead.json"
-X POST
Copied{
	LeadData = Map();
	LeadData.put("Last_Name", "Patricia");
	LeadData.put("Email", "patricia@zoho.com"); //unique field
	LeadData.put("Company", "Zoho");
	
	LeadDataList = List();
	LeadDataList.add(LeadData);
	
	paramsMap = Map();
	
	paramsMap.put("data", LeadDataList);

	
	response = invokeurl
	[
		url: "https://www.zohoapis.com/crm/v8/Leads/upsert"
		type: POST
		parameters: paramsMap.toString()
		connection: "zohocrm"
	];
	info response;
}

在请求中,"@upsertlead.json" 包含了示例输入数据。

输入JSON 

  • $skip_feature_executionJSON 数组, 可选

    默认情况下,如果模块配置了Cadence,则在通过API对记录执行upsert操作(Insert 或 Update 操作)时会自动执行Cadence。此键允许你在记录upsert期间跳过Cadences功能的执行。要跳过该记录的Cadences执行,请将"name"键的值指定为"cadences"。请确保在请求中此键与"data"键一起包含。

    • name字符串,必填

      表示功能名称。

      可能值: cadences

    • action字符串,必填

      表示根据哪个操作跳过此功能。系统会根据此操作跳过功能执行。支持的值:“Insert”和“Update”。例如,如果 "action": "Insert",则当通过upsert API插入记录时,系统将跳过该功能的执行。

注意

  • 在使用 Upsert API 时,系统会根据重复检查字段验证记录是否重复。重复检查字段分为两种类型:
    • 系统定义的重复检查字段
      • 这些是在每个模块中预定义的唯一字段。
      • 系统会自动检查这些字段,以防止重复条目。
      • 有关各模块详细信息,请参阅系统定义的重复检查字段部分。
    • 用户自定义唯一字段
      • 这些字段启用了“不允许重复值”选项。
      • Users可以定义自定义唯一字段以防止数据重复。
      • 了解更多关于如何启用将字段标记为唯一的信息。

当一条记录被插入或更新时,系统会首先检查这些字段中的重复项。如果存在匹配的记录,则会被更新;否则,将插入一条新记录。

  • 您可以在 API 请求中的 duplicate_check_fields 数组中设置系统验证重复记录的顺序。
    • 允许的字段:
      • 系统定义的重复检查字段。例如,Email用于线索。
      • 用户自定义的唯一字段。例如,电话和传真。

            示例:在线索模块中:

            "duplicate_check_fields": 
           [
            "Email",
            "电话",
             "传真"
           ]

       如果您没有指定 duplicate_check_fields,系统将按照以下默认顺序进行操作:

          一、系统定义的重复检查字段
          二、用户自定义唯一字段

  • 如果字段的取值长度超过该字段定义的最大长度,则会抛出“INVALID_DATA”错误。
  • 如果在函数中使用了 API 并且字段值的长度超出限制,那么该函数会从 API 收到一个错误响应。例如:如果“文本字段”的最大长度被定义为 10,那么在 API 中为其提供的值不能是“12345678901”,因为它有 11 个字符。
  • 每次 API 调用最多可以插入/更新 100 条记录。
  • 请参考我们的 Kaizen 文章:Upsert 记录 API 和 重复检查 Preferences API 与 Upsert API 对比,了解包含实时用例的更多详情。
  • 您必须仅在输入中使用字段 API Name。您可以通过以下方式获取字段 API Name:
    • 字段元数据 API(每个字段的键“api_Name”对应的值)。(或者)
    • 设置 > 开发者中心 > API 和 SDK > API Name > {模块}。在“筛选方式”下拉菜单中选择“字段”。
  • 触发器输入可以是工作流、审批或蓝图。如果未提及触发器,将会执行与 API 相关的工作流、审批和蓝图。输入触发器值为 [] 时,将不会执行工作流。
  • 带有子表单详细信息的记录也可以通过记录API插入或更新到CRM。要了解如何在记录中添加子表单信息,请参阅子表单API。如需获取有关子表单的详细信息,请参考我们的Kaizen文章:使用Zoho CRM API 操作子表单。
  • $append_values 键表示您是否希望将输入中指定的多选列表的值追加到现有值后。请在此 JSON 对象中,以多选列表的 API 名称为键,"true" 或 "false" 为值,作为键值对进行指定。值为 "true" 时会将输入中的值追加到多选列表中,值为 "false" 时会用输入中的值替换现有值。
  • 如果您希望

    • 在 API 级别的必填项检查中包含布局特定的必填字段
    • 仅在 API 级别处理中包含您在布局中定义的字段,并忽略其他字段

       

    ,则必须提供 布局 ID 字段。

系统定义的重复检查字段

以下是不同模块的默认重复检查字段。

模块系统定义的重复检查字段
线索Email
AccountAccount_Name
联系人Email
交易交易_Name
市场活动市场活动_Name
案件主题
解决方案解决方案标题
产品产品_Name
Vendors供应商_Name
价格手册价格手册_Name
报价主题
SalesOrders主题
采购Orders主题
Invoices主题
自定义模块Name

要了解 Zoho CRM 中每个模块的具体细节及其限制,请参阅 示例Attributes 部分,详见 Insert记录 API。

 

重复检查是如何工作的?

考虑一种情况,用户为某个模块配置了两个唯一字段 unique1 和 unique2(用户自定义唯一字段),而Email是系统定义的唯一字段。
下表解释了对于不同用户输入 duplicate_check_fields 数组时,如何进行重复检查。

用户输入到 "duplicate_check_fields" 数组查重模式
unique1unique1,unique2
unique2unique2,unique1
unique1,unique2unique1,unique2
EmailEmail,unique1,unique2
无输入该模块的系统定义查重字段,后跟唯一字段。即Email,unique1,unique2

如果您没有在数组中指定系统定义的重复检查字段,系统将忽略这些字段,并只检查用户自定义的唯一字段。

示例输入

Copied{
    "data": [
        {
            "Last_Name": "Lead_changed",
            "Email": "newcrmapi@zoho.com",
            "Company": "abc",
            "Lead_Status": "Contacted",
            "Foreign_Languages": [ //multi-select picklist
                "Korean"
            ],
            "$append_values": {
                "Foreign_Languages": false
            }
        },
        {
            "Last_Name": "New Lead",
            "First_Name": "CRM Lead",
            "Email": "newlead@zoho.com",
            "Lead_Status": "Attempted to Contact",
            "Mobile": "7685635434",
            "Foreign_Languages": [ //multi-select picklist
                "Korean",
                "Spanish"
            ],
            "$append_values": {
                "Foreign_Languages": true
            }
        }
    ],
    "skip_feature_execution": [
        {
            "name": "cadences",
            "action": "insert"
        }
    ],
    "duplicate_check_fields": [
        "Email",
        "Mobile"
    ],
    "trigger": [
        "workflow"
    ]

可能的错误

  • INVALID_MODULEHTTP 400

    所提供的模块名称似乎无效
    解决方法:您指定了一个无效的模块名称,或者没有选项卡权限,或者该模块已从可用模块中移除。请指定有效的模块 API 名称。

  • INVALID_MODULEHTTP 400

    所提供的模块在 API 中不受支持
    解决方法: 诸如文档和项目等模块在当前 API 中不受支持。(一旦这些模块被支持,该错误将不会显示。)请指定有效的模块 API 名称。

  • INVALID_DATAHTTP 400

    无效数据
    解决方法:指定的输入不正确。请指定有效的输入。

  • INVALID_URL_PATTERNHTTP 404

    请检查尝试访问的URL是否正确
    解决方法:指定的请求URL不正确。请指定有效的请求URL。请参考上面的请求URL部分。

  • OAUTH_SCOPE_MISMATCHHTTP 401

    未授权
    解决方法:客户端没有 ZohoCRM.modules.{module_name}.WRITE/ZohoCRM.modules.{module_name}.CREATE 权限范围。请使用有效的权限范围创建新的客户端。详见上面的权限范围部分。

  • NO_PERMISSIONHTTP 403

    无权限进行插入或更新操作
    解决方法: 用户没有插入或更新记录的权限。请联系您的系统管理员。

  • ALREADY_MODIFIEDHTTP 412

    记录的更新时间已经晚于 if-unmodified-since 时间 
    解决方法:该记录在指定的 If-Unmodified-Since 时间戳之后已被更新。请使用更新的 If-Unmodified-Since 请求头值重试。

  • DUPLICATE_DATAHTTP 400

    数据重复
    解决方法:您为一个或多个唯一字段指定了重复的值。响应中的 "details" 键提供了输入中包含重复值的字段的 API 名称。请为唯一字段指定唯一的值。

  • INTERNAL_ERRORHTTP 500

    服务器内部错误
    解决方法:服务器中出现了意外且未处理的异常。请联系支持团队。

  • INVALID_REQUEST_METHODHTTP 400

    HTTP 请求方法类型无效
    解决方案:您为访问 API URL 指定了无效的 HTTP 方法。请指定有效的请求方法。参考上面的端点部分。

  • AUTHORIZATION_FAILEDHTTP 400

    用户没有足够的权限来插入或更新记录。
    解决方法:该用户没有插入或更新记录详情的权限。请联系您的系统管理员。

  • MANDATORY_NOT_FOUNDHTTP 400

    未找到必填字段
    解决方法:您未在输入中指定一个或多个必填字段。请参考字段元数据 API了解必填字段。

示例回复

Copied{
    "data": [
        {
            "code": "SUCCESS",
            "duplicate_field": "Email",
            "action": "update",
            "details": {
                "Modified_Time": "2020-10-14T10:31:43+05:30",
                "Modified_By": {
                    "name": "Patricia Boyle",
                    "id": "4150868000000225013"
                },
                "Created_Time": "2019-09-11T16:21:15+05:30",
                "id": "4150868000000376008",
                "Created_By": {
                    "name": "Patricia Boyle",
                    "id": "4150868000000225013"
                }
            },
            "message": "record updated",
            "status": "success"
        },
        {
            "code": "SUCCESS",
            "duplicate_field": null,
            "action": "insert",
            "details": {
                "Modified_Time": "2020-10-14T10:31:43+05:30",
                "Modified_By": {
                    "name": "Patricia Boyle",
                    "id": "4150868000000225013"
                },
                "Created_Time": "2020-10-14T10:31:43+05:30",
                "id": "4150868000003194003",
                "Created_By": {
                    "name": "Patricia Boyle",
                    "id": "4150868000000225013"
                }
            },
            "message": "record added",
            "status": "success"
        }
    ]
}