使用外部 ID 插入记录
目的
使用外部ID向模块添加新实体。以下是一些场景:
端点
- POST /{module_api_name}
请求详情
请求URL
{api-domain}/crm/{version}/{module_api_name}
支持的模块
潜在客户,Account,联系人,交易,活动,任务,案例,事件,通话,解决方案,产品,Vendors,价格表,报价单,Sales Orders,采购Orders,Invoices,自定义,预约,服务和活动
标题
授权: Zoho-oauthtoken d92d4xxxxxxxxxxxxx15f52
X-EXTERNAL: {module_API_name}.{external_field_API_name}
范围
ZohoCRM.modules.all
(或)
ZohoCRM.modules.{module_name}.{operation_type}
可能的模块名称
潜在客户,Account,联系人,交易,活动,任务,案例,事件,通话,解决方案,产品,Vendors,价格手册,报价单,Sales_Orders,采购_Orders,Invoices,预约__s,服务__s 和自定义
可能的操作类型
全部 - 完全访问记录
写入 - Edit 模块中的记录
创建 - 在模块中创建记录
示例请求
Copiedcurl "https://www.zohoapis.com/crm/v8/{base_module_API_name}"
-X POST
-H "Authorization: Zoho-oauthtoken 1000.8cb99dxxxxxxxxxxxxx9be93.9b8xxxxxxxxxxxxxxxf"
-H "X-EXTERNAL: {module_API_name}.{external_field_API_name}"
-d "@sample.json"示例请求
Copiedcurl "https://www.zohoapis.com/crm/v8/Contacts"
-X POST
-H "Authorization: Zoho-oauthtoken 1000.8cb99dxxxxxxxxxxxxx9be93.9b8xxxxxxxxxxxxxxxf"
-H "X-EXTERNAL: Contacts.Account_Name.External_Account_ID"
-d "@sample.json"示例输入
Copied{
"data": [
{
"Last_Name": "ext contact 1",
"Account_Name": {
"External_Account_ID": "externalaccount1"
}
}
]
}示例响应
Copied{
"data": [
{
"code": "SUCCESS",
"details": {
"Modified_Time": "2020-10-22T01:35:09-11:00",
"Modified_By": {
"name": "Patricia Boyle",
"id": "554023000000235011"
},
"Created_Time": "2020-10-22T01:35:09-11:00",
"id": "554023000001627036",
"Created_By": {
"name": "Patricia Boyle",
"id": "554023000000235011"
}
},
"message": "record added",
"status": "success"
}
]
}示例请求
Copiedcurl "https://www.zohoapis.com/crm/v8/Quotes"
-X POST
-H "Authorization: Zoho-oauthtoken 1000.8cb99dxxxxxxxxxxxxx9be93.9b8xxxxxxxxxxxxxxxf"
-H "X-EXTERNAL:Quotes.Product_Details.Product_Name.External_Product_ID,Quotes.Product_Details.book.External_Price_book_ID"
-d "@sample.json"示例输入
Copied{
"data": [
{
"External_Quote_ID": "quote1",
"Subject": "Quote 1",
"Quoted_Items": [
{
"Product_Name": {
"External_Product_ID": "12345678900"
},
"book": {
"External_Price_book_ID": "pricebook1"
},
"quantity": 100
}
]
}
]
}示例响应
Copied{
"data": [
{
"code": "SUCCESS",
"details": {
"Modified_Time": "2019-12-12T23:35:47+05:30",
"Modified_By": {
"name": "Patricia Boyle",
"id": "554023000000235011"
},
"Created_Time": "2019-12-12T23:35:47+05:30",
"id": "111111000000133093",
"Created_By": {
"name": "Patricia Boyle",
"id": "554023000000235011"
}
},
"message": "record added",
"status": "success"
}
]
}示例请求
Copiedcurl "https://www.zohoapis.com/crm/v8/Contacts"
-X POST
-H "Authorization: Zoho-oauthtoken 1000.8cb99dxxxxxxxxxxxxx9be93.9b8xxxxxxxxxxxxxxxf"
-H "X-EXTERNAL: Contacts.Subform_External.Deal_Lookup.External_Deal_ID"
-d "@sample.json"示例输入
Copied{
"data": [
{
"Last_Name": "Contact with a Subform",
"Subform_External": [
{
"Deal_Lookup": {
"External_Deal_ID": "userdeal1"
}
}
]
}
]
}示例响应
Copied{
"data": [
{
"code": "SUCCESS",
"details": {
"Modified_Time": "2019-12-12T23:35:47+05:30",
"Modified_By": {
"name": "Patricia Boyle",
"id": "554023000000235011"
},
"Created_Time": "2019-12-12T23:35:47+05:30",
"id": "111111000000134014",
"Created_By": {
"name": "Patricia Boyle",
"id": "554023000000235011"
}
},
"message": "record added",
"status": "success"
}
]
}示例请求
Copiedcurl "https://www.zohoapis.com/crm/v8/Events"
-X POST
-H "Authorization: Zoho-oauthtoken 1000.8cb99dxxxxxxxxxxxxx9be93.9b8xxxxxxxxxxxxxxxf"
-H "X-EXTERNAL: Events.What_Id->Accounts.External_Account_ID"
-d "@sample.json"示例输入
Copied{
"data": [
{
"se_module": "Accounts",
"What_Id": {
"External_Account_ID": "useraccount1"
},
"Event_Title": "Event Kaizen",
"Start_DateTime": "2020-05-10T10:10:10+05:30",
"End_DateTime": "2020-05-10T11:10:10+05:30"
}
]
}示例响应
Copied{
"data": [
{
"code": "SUCCESS",
"details": {
"Modified_Time": "2019-12-12T23:35:47+05:30",
"Modified_By": {
"name": "Patricia Boyle",
"id": "554023000000235011"
},
"Created_Time": "2019-12-12T23:35:47+05:30",
"id": "111111000000137001",
"Created_By": {
"name": "Patricia Boyle",
"id": "554023000000235011"
}
},
"message": "record added",
"status": "success"
}
]
}Insert一个事件记录并通过外部字段关联 What_Id 和参与者
在这个例子中,External_Account_ID 和 External_Contact_ID 是Account和联系人模块中外部字段的 API 名称。事件模块中的 What_Id 以Account的名称作为其值。“participant” 是参与者数组中的一个 JSON 对象。我们将引用这些外部值并Insert一个事件。
注意
- 如果您在参与者JSON对象中指定了外部字段的值,并在联系人模块中指定了外部字段的记录ID,那么如果您仅在头部指定了参与者,系统只会考虑外部字段的值。
- What_Id查找可以映射到不同的模块,因此在X-External头部中指向What_Id查找的外部字段时,您应该使用“->模块Name.外部字段Name”而不是“.外部字段Name”。
- 此外,在X-External头部中指向任何多模块查找时,您应该使用“->模块Name.外部字段Name”。
可能的错误
- DUPLICATE_DATAHTTP 400
外部字段包含重复数据。
解决方法:输入唯一的数据到外部字段。 - INVALID_DATAHTTP 400
查找字段或价格书的外部ID不正确
解决方法:指定正确的外部ID。请参阅错误响应中的“详细信息”以了解哪个外部ID不正确。
示例请求
Copiedcurl "https://www.zohoapis.com/crm/v8/Events"
-X POST
-H "Authorization: Zoho-oauthtoken 1000.8cb99dxxxxxxxxxxxxx9be93.9b8xxxxxxxxxxxxxxxf"
-H "X-EXTERNAL: Events.What_Id->Accounts.External_Account_ID, Events.Participants.participant->Contacts.External_Contact_ID"
-d "@sample.json"示例输入
Copied{
"data": [
{
"External_Event_ID": "Event Kaizen 1",
"Last_Name": "Contact 1",
"Participants": [
{
"type": "contact",
"participant": {
"External_Contact_ID": "participant1"
}
}
],
"What_Id": {
"External_Account_ID": "useraccount1"
},
"$se_module": "Accounts",
"Event_Title": "Kaizen 1",
"Start_DateTime": "2020-05-10T10:10:10+05:30",
"End_DateTime": "2020-05-10T11:10:10+05:30"
}
]
}示例响应
Copied{
"data": [
{
"code": "SUCCESS",
"details": {
"Modified_Time": "2019-12-12T23:35:47+05:30",
"Modified_By": {
"name": "Patricia Boyle",
"id": "554023000000235011"
},
"Created_Time": "2019-12-12T23:35:47+05:30",
"id": "111111000000139016",
"Created_By": {
"name": "Patricia Boyle",
"id": "554023000000235011"
}
},
"message": "record added",
"status": "success"
}
]
}