Zoho crm Logo

更新记录

目的

用于更新指定模块中的现有实体或记录。

端点

  • PUT /{module_api_name}
  • PUT /{module_api_name}/{record_id}
  • {module_api_name} : 要更新其记录的模块的 API 名称。
  • {record_id} : 您要更新的记录的唯一标识符。

请求详情

请求 URL

要更新多个记录:
{api-domain}/crm/{version}/{module_api_name}

要更新特定记录:
{api-domain}/crm/{version}/{module_api_name}/{record_id}

支持的模块

潜在客户,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模块中的记录
Update - Update模块中的记录

示例请求

Copiedcurl "https://www.zohoapis.com/crm/v8/Deals"
-X PUT
-d "@updatedeal.json"
-H "Authorization: Zoho-oauthtoken 1000.8cb99dxxxxxxxxxxxxx9be93.9b8xxxxxxxxxxxxxxxf"
Copied{
	DealData = Map();
	DealData.put("id", "5725767000004594012");
	DealData.put("Deal_Name", "data");
	DealData.put("Company", "Zoho");
	
	DealDataList = List();
	DealDataList.add(DealData);
	
	paramsMap = Map();
	
	paramsMap.put("data", DealDataList);
	
	response = invokeurl
	[
		url: "https://www.zohoapis.com/crm/v8/Deals"
		type: PUT
		parameters: paramsMap.toString()
		connection: "zohocrm"
	];
	info response;
}

在请求中,"@updatelead.json" 包含示例输入。

请求 JSON 键

  • id字符串,必填

    指定要更新的记录的唯一ID。请参阅 获取记录 API 以获取记录的唯一ID。

  • $append_valuesJSON 对象, 可选 

    用于确定在更新记录时,在多选选项列表(multi-select picklist)中是追加值还是替换值。

    用法:

    • 将多选选项列表的API 名称作为键指定。
    • 将值设置为 "true" 以追加新值到现有值。
    • 将值设置为 "false" 以替换现有值为新值。

    请注意,只有输入中包含该键的记录才会追加或替换值。对于其他多选选项列表,现有值默认会被直接替换。

  • skip_feature_executionJSON 数组,可选 

    默认情况下,如果某个模块配置了 Cadence,当你通过 API 更新记录时,它会自动执行。此键允许你在记录更新时跳过 Cadences 功能的执行。 
    要跳过记录的 Cadences 执行,请将"name" 键的值指定为"cadences"。确保在请求中同时包含此键和"data"键。"name" 键支持的取值为"cadences"。

注意

  • 如果字段值长度超过该字段定义的最大长度,则会抛出“INVALID_DATA”错误。
  • 如果在函数中使用了 API,并且字段值超过了允许的长度,函数会从 API 收到错误响应。
    • 例如,如果文本字段的最大长度为 10,API 无法接受像 "12345678901" 这样的值,因为它有 11 个字符,超出了限制。
  • 每次 API 调用最多可以更新100条记录。
  • 每次更新记录的 API 调用都会根据唯一字段检查重复项。
  • 您必须在输入中仅使用字段 API Name。您可以通过以下途径获取字段 API Name:
    • 字段元数据 API(每个字段键值“api_Name”的值)。(或)
    • 设置 > 开发者中心 > API 和 SDK > API Name > {{Module}}。在“筛选方式”下拉菜单中选择“字段”。
  • 带有子表单详细信息的记录也可以通过记录API更新到CRM中。请参阅子表单API了解如何在记录中更新子表单信息。有关子表单的详细信息,请参考我们的Kaizen帖子:使用ZohoCRM API操作子表单。
  • 如果通过 DRE(函数)对某条记录进行更新 API 调用,并且由于工作流在同一记录的创建/更新时被触发,则仅工作流本身将不会被执行,无论触发参数配置如何。
  • 使用“_delete”键从多选查找、多用户查找和图片上传字段中删除数据。您必须在输入中传递在关联模块中创建的记录ID。详情请参考示例输入。
  • 所有被更新的记录默认会进入审核流程。
  • 在插入、更新或合并对应模块中的记录时,您也可以使用每个模块的示例响应作为输入。
  • 请参考 获取记录 API 以了解更多关于字段类型和限制的信息。
  • 您可以更新模块中插入记录操作所支持的所有字段。
  • 如果您想要:

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

    则必须提供布局 ID 字段。

  • 如果相关记录被锁定,则多选查找关联将受限,系统会抛出RECORD_LOCKED错误。
  • 在通话模块中,呼入或呼出通话的通话时长不能为零。

示例输入

Copied{
    "data": [
        {
            "id": "3652397000003852095",
            "Deal_Name": "v8 Update",
            "Stage": "Closed Won",
            "Pipeline": "Standard (Standard)",
            "Foreign_Languages": [ //multi-select picklist
                "Korean",
                "Spanish"
            ],
            "$append_values": {
                "Foreign_Languages": false
            },
            "Image_Upload": [
                {
                    "File_Id__s": "762337e6xx"
                }, //adding a new image
                {
                    "id": "57257631xx",
                    "_delete": null //deleting an existing image
                }
            ],
            "File_Upload": [
                {
                    "File_Id__s": "d89bb8210dea172e24100461c4f4d3fa54edc1840dbda12d6aba665cd68c7af418941cc860e3031123cf497cf2001b63"
                }, //adding a new file
                {
                    "id": "5725767000008463061",
                    "_delete": null //deleting an existing file
                }
            ],
            "Listings": [ //multi-select lookup
                {
                    "Interested_Listings": {
                        "id": "3652397000001988001" //adding a new listing to the multi-select lookup
                    }
                },
                {
                    "id": "431581000000697244", // record ID from the linking module to be removed
                    "_delete": null
                }
            ],
            "AssociatedUser": [ //multi-user lookup
                {
                    "User": {
                        "name": "J Smith",
                        "id": "3652397000000281001" // adding a user to the multi-user lookup
                    }
                },
                {
                    "id": "431581000000701821", //record ID from the linking module to be removed
                    "_delete": null
                }
            ]
        }
    ],
    "skip_feature_execution": [
        {
            "name": "cadences"
        }
    ]
}

可能的错误

  • INVALID_MODULEHTTP 400

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

  • INVALID_MODULEHTTP 400

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

  • INVALID_DATAHTTP 400

    所提供的 ID 似乎无效
    解决办法:您指定了错误的记录 ID。请指定有效的记录 ID。请参考 获取记录 API 获取有效的记录 ID。

  • DUPLICATE_LINKING_DATAHTTP 400

    重复关联
    解决方法:您尝试更新的记录已经与多选查找(MxN)字段中指定的相同记录存在关联。系统不允许重复关联。请先移除已关联的记录,然后再尝试关联新的记录。

  • MANDATORY_NOT_FOUNDHTTP 400

    未找到必填字段
    解决方法:您在请求中未指定要更新记录的唯一ID。请指定要更新记录的ID,参考获取记录 API获取有效的记录ID。

  • INVALID_URL_PATTERN HTTP 404

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

  • OAUTH_SCOPE_MISMATCHHTTP 401

    未授权
    解决方法:客户端没有 ZohoCRM.modules.{module_name}.UPDATE 的权限范围。请创建一个具有有效权限范围的新客户端。请参阅上方的权限范围部分。

  • NO_PERMISSION HTTP 403

    无权更新
    解决方法: 该用户没有更新记录数据的权限。请联系系统管理员。

  • ALREADY_MODIFIEDHTTP 412

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

  • INTERNAL_ERRORHTTP 500

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

  • INVALID_REQUEST_METHODHTTP 400

    HTTP请求方法类型无效
    解决方法: 你指定了一个无效的HTTP方法来访问API URL。请指定一个有效的请求方法。请参考上方的端点部分。

  • AUTHORIZATION_FAILEDHTTP 400

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

  • DUPLICATE_DATAHTTP 400

    重复数据
    解决方法:您为一个或多个唯一字段指定了重复的值。请参考字段元数据 API以了解唯一字段。

  • LIMIT_EXCEEDEDHTTP 400

    一个活动最多只能添加50名参与者。
    解决方法:您正在尝试为某个活动添加超过50名参与者。每个活动最多只能添加50名参与者。

  • RECORD_LOCKEDHTTP 400

    无法更新尚未被批准的记录
    解决方法: 请等待 Zia 图像或合并重复项的过程完成后再重试。

  • RECORD_LOCKEDHTTP 400

    您无法执行此操作,因为该记录已被锁定。
    解决方法: 请等待记录解锁后再进行操作。

  • NOT_APPROVEDHTTP 400

    无法更新尚未获得批准的记录
    解决方法:

    • 情况一:如果记录由于 Zia 图像验证被拒绝,可以上传新图片,或删除未通过的图片,然后重新提交记录进行 Zia 图像验证。
    • 情况二:如果记录正在进行 Zia 记录审批,在审核员批准或拒绝记录之前,系统不允许你更新该记录的图片。
  • RECORD_LOCKEDHTTP 400

    抱歉,由于该记录已被锁定,您无法执行此操作。
    解决方法: 如果相关记录处于锁定状态,则多选查找关联将受到限制。请确保相关记录未被锁定,然后重试。

  • DEPENDENT_MISMATCHHTTP 400

    通话时长不能为零。
    解决方法: 呼入或呼出电话的时长不能为零。请使用非零的Call_Duration值重试。

示例回复

Copied{
    "data": [
        {
            "code": "SUCCESS",
            "details": {
                "Modified_Time": "2021-05-02T11:17:33+05:30",
                "Modified_By": {
                    "name": "Patricia Boyle",
                    "id": "554023000000235011"
                },
                "Created_Time": "2021-05-02T11:17:33+05:30",
                "id": "554023000000527003",
                "Created_By": {
                    "name": "Patricia Boyle",
                    "id": "554023000000235011"
                }
            },
            "message": "record updated",
            "status": "success"
        }
    ]
}