使用外部 ID 更新记录
目的
通过外部字段更新模块中的现有记录。
请求详情
请求 URL
https://www.zohoapis.com/crm/{version}/{module_api_name}/{external_field_value}
支持的模块
潜在客户,Account,联系人,交易,活动,任务,案例,事件,通话,解决方案,产品,Vendors,价目表,报价单,Sales Orders,采购Orders,Invoices,自定义,预约,服务和活动
可能的操作类型
标题
授权:Zoho-oauthtoken d92d4xxxxxxxxxxxxx15f52
X-EXTERNAL:{module_API_name}.{external_field_API_name}
范围
scope=ZohoCRM.modules.all
(或)
scope=ZohoCRM.modules.{module_name}.{operation_type}
可能的模块名称
线索、账户、联系人、交易、活动、任务、案例、日程、电话、解决方案、产品、供应商、价格簿、报价单、销售订单、采购订单、发票、自定义、预约、服务和备注
可能的操作类型
ALL - 完全访问该记录
WRITE - Edit模块中的记录
Update - Update模块中的记录
端点
- PUT /{module_API_name}/{external_value}
Update一条记录
让我们以在联系人模块中更新记录为例。你无需在Zoho CRM中传递联系人的记录ID,可以在该模块中传递外部字段的值来Update记录。
样本请求
Copiedcurl "https://www.zohoapis.com/crm/v8/Contacts/extcont1234"
-X PUT
-H "Authorization: Zoho-oauthtoken 1000.8cb99dxxxxxxxxxxxxx9be93.9b8xxxxxxxxxxxxxxxf"
-H "X-EXTERNAL: Contacts.External_Contact_ID, Contacts.Account_Name.External_Account_ID"
-d "@sample.json"示例输入
Copied{
"data": [
{
"Last_Name": "Smith"
}
]
}示例回复
Copied{
"data": [
{
"code": "SUCCESS",
"details": {
"Modified_Time": "2025-06-13T16:25:15+05:30",
"Modified_By": {
"name": "Patricia Boyle",
"id": "6660682000000501001"
},
"Created_Time": "2025-02-26T14:37:14+05:30",
"id": "6660682000000516033",
"Created_By": {
"name": "Patricia Boyle",
"id": "6660682000000501001"
},
"External_Contact_Id": "extcont1234"
},
"message": "record updated",
"status": "success"
}
]
}Update 一条记录
在此示例中,Contacts 是基础模块,并包含一个 Account 查找字段 Account_Name。要在 Contacts 模块中Update一条记录,您必须在 Account 模块中指定外部字段的 API Name 及其值,同时还需要在 Contacts 模块中指定外部字段的 API Name 及其值。
示例请求
Copiedcurl "https://www.zohoapis.com/crm/v8/Contacts"
-X PUT
-H "Authorization: Zoho-oauthtoken 1000.8cb99dxxxxxxxxxxxxx9be93.9b8xxxxxxxxxxxxxxxf"
-H "X-EXTERNAL: Contacts.External_Contact_ID, Contacts.Account_Name.External_Account_ID"
-d "@sample.json"示例输入
Copied{
"data": [
{
"External_Contact_ID": "extcontact1",
"Account_Name": {
"External_Account_ID": "extaccount1"
}
}
]
}示例响应
Copied{
"data": [
{
"code": "SUCCESS",
"details": {
"Modified_Time": "2019-12-19T19:09:48+05:30",
"Modified_By": {
"name": "Patricia Boyle",
"id": "111111000000044700"
},
"Created_Time": "2019-12-04T00:08:05+05:30",
"External_Contact_ID": "extcontact1",
"id": "111111000000101004",
"Created_By": {
"name": "Patricia Boyle",
"id": "111111000000044700"
}
},
"message": "record updated",
"status": "success"
}
]
}Update带有外部字段的库存模块记录(位于明细行中)
在此示例中,报价单为基础模块。要UpdateProduct_Details 部分中的详细信息,请在product和bookJSON对象中指定外部字段的 API 名称和对应的值。
样品请求
Copiedcurl "https://www.zohoapis.com/crm/v8/Quotes/quote1"
-X PUT
-H "Authorization: Zoho-oauthtoken 1000.8cb99dxxxxxxxxxxxxx9be93.9b8xxxxxxxxxxxxxxxf"
-H "X-EXTERNAL: Quotes.Product_Details.product.External_Product_ID, Quotes.Product_Details.book.External_Price_book_ID"
-d "@sample.json"示例输入
Copied{
"data": [
{
"Product_Details": [
{
"id": "111111000000133071"
},
{
"product": {
"External_Product_ID": "12345678900"
},
"book": {
"External_Pricebook_ID": "pricebook2"
},
"quantity": 20
}
]
}
]
}示例回复
Copied{
"data": [
{
"code": "SUCCESS",
"details": {
"Modified_Time": "2019-12-20T12:29:49+05:30",
"Modified_By": {
"name": "Patricia Boyle",
"id": "111111000000044700"
},
"Created_Time": "2019-12-12T23:32:49+05:30",
"External_Quote_ID": "quote1",
"id": "111111000000133069",
"Created_By": {
"name": "Patricia Boyle",
"id": "111111000000044700"
}
},
"message": "record updated",
"status": "success"
}
]
}Update 通过关联模块中的外部字段更新子表单查找记录
在子表单的查找字段JSON对象中,指定外部字段的API名称及其值。
可能的错误
- INVALID_DATAHTTP 400
外部字段的值无效。
解决方法:请指定正确的外部值。 - INVALID_DATAHTTP 400
外部字段的值对于查找字段无效。
解决方法:请指定正确的外部值。 - INVALID_DATAHTTP 400
对于Inventory模块,如果未指定外部字段的 header,系统期望输入中包含产品 ID。
解决方法: 当在请求中使用外部字段时,请包含正确的外部 header。 - NOT_ALLOWEDHTTP 400
您不能在请求中使用外部字段自身的主键来更新该外部字段。例如,如果 extcontact1 是外部字段 External_Contact_ID 的值,那么您不能使用它自身来更新外部字段的值(CRM/v6/Contacts/extcontact1)。
解决方法: 请使用其他外部字段或 CRM 的主键来更新外部字段。 - AUTHORIZATION_FAILEDHTTP 400
您没有足够的权限更新相关记录。
解决方法:请联系您的系统管理员。 - OAUTH_SCOPE_MISMATCHHTTP 401
您用于进行此 API 调用的访问令牌不具有所需的权限范围。
解决方法:请根据权限范围部分中提到的范围,生成一个新的访问令牌。 - NO_PERMISSIONHTTP 403
您没有权限更新相关记录。
解决方法:请联系您的系统管理员。 - INVALID_URL_PATTERNHTTP 404
请求的URL不正确。
解决方法:请指定有效的请求URL。请参阅请求URL部分以获取正确的URL。 - INTERNAL_ERRORHTTP 500
服务器出现了意外且未处理的异常。
解决方法:请联系支持团队:support@zohocrm.com。
示例请求
Copiedcurl "https://www.zohoapis.com/crm/v8/Contacts/extcontact2"
-X PUT
-H "Authorization: Zoho-oauthtoken 1000.8cb99dxxxxxxxxxxxxx9be93.9b8xxxxxxxxxxxxxxxf"
-H "X-EXTERNAL: Contacts.External_Contact_ID,Contacts.Subform_External.Deal_Lookup.External_Deal_ID"
-d "@sample.json"示例输入
Copied{
"data": [
{
"Subform_External": [
{
"Deal_Lookup": {
"External_Deal_ID": "userdeal1"
}
}
]
}
]
}示例回复
Copied{
"data": [
{
"code": "SUCCESS",
"details": {
"Modified_Time": "2019-12-20T12:30:59+05:30",
"Modified_By": {
"name": "Patricia Boyle",
"id": "111111000000044700"
},
"Created_Time": "2019-12-13T22:07:07+05:30",
"External_Contact_ID": "extcontact2",
"id": "111111000000138036",
"Created_By": {
"name": "Patricia Boyle",
"id": "111111000000044700"
}
},
"message": "record updated",
"status": "success"
}
]
}