更新记录
目的
用于更新指定模块中的现有实体或记录。
端点
- 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"
}
]
}