插入或更新(upsert)

目的

插入或更新一条记录。如果记录不存在，系统将以新记录的形式插入该记录。如果记录已经存在，则系统根据重复检查更新记录。

请求URL

https://www.zohoapis.com.cn/crm/v2/{module_api_name}/upsert

module_api_name - 模块的API名称

在获取记录列表中支持的模块在这里也支持。

请求方法

POST

范围

scope=ZohoCRM.modules.all
(或)
scope=ZohoCRM.modules.{module_name}.{operation_type}

可能的模块名称可能的操作类型
线索，客户，联系人，商机，市场活动，服务支持，解决方案，产品，供货商，价格表，报价单，销售订单，采购订单，发货单，自定义模块和备注ALL - 完全访问记录
WRITE - 编辑模块中的记录
CREATE - 在模块中创建记录
备注：

除了输入中的“data”JSON数组，包含duplicate_check_fields作为字段API名称的JSON数组。您只能用系统定义的重复检查字段 以及您为该模块配置的用于执行重复检查的惟一字段。

线索模块的示例：

"duplicate_check_fields": [
"Email",
"Phone",
"Fax"
]

在这里，"Email"为系统定义的重复检查字段，而"Phone" 和 "Fax"是为线索模块配置的惟一字段。

如果不指定duplicate_check_fields，默认情况下使用系统定义的重复检查字段，然后是唯一字段。

可能的错误

HTTP状态错误码消息原因
400INVALID_MODULEThe module name given seems to be invalid无效的模块名称或没有模块权限，或者模块可能已从已组织的模块中删除
400INVALID_MODULEThe given module is not supported in API当前API不支持文档和项目等模块。(一旦支持了这些模块，就不会显示此错误。)

备注：

  • 如果字段值长度 过为该字段定义的最大长度，系统将抛出一个错误。

  • 如果在函数中使用API，并且字段值长度超过限制，则该函数将从API接收错误响应。例如：如果“文本字段”的最大长度定义为10，那么在API中给它的值不能是“12345678901”，因为它有11个字符。

  • 对于每个基于惟一字段的插入记录API调用，都会检查重复项。

  • 每次API调用最多可以插入/更新100条记录。

  • 在输入中提供字段API名称以及要填充的相应值。

  • trigger输入可以是workflow，approval，或blueprint。如果没有提到触发器，将执行与API相关的工作流、审批和蓝图。输入触发器值为[]将不执行工作流。

  • 包含子表单明细的记录可以使用记录API插入到CRM中。

  • 参考响应结构了解有关JSON键、值及其描述的详细信息。您还可以使用每个模块的示例响应作为输入，在相应模块中插入、更新或维护记录。

系统定义的重复检查字段

  • 以下是不同模块的默认重复检查字段。
    线索 - 邮箱， 客户 - 客户名称，联系人 - 邮箱，商机 - 商机名称，市场活动 - 市场活动名称，服务支持 - 标题，解决方案 - 解决方案标题，产品 - 产品名称，供货商 - 供货商名称，价格表 - 价格表名称，报价单 - 标题，销售订单 - 标题，采购订单 - 标题，发货单 - 标题，自定义模块 - 名称

示例属性

属性示例
单行"Single_Line_1": "这是一个单行",
多行"Multi_Line_1": "这是第一行 \n 这是第二行"，
邮箱"Email_1"："p.boyle@zylker.com"，
电话"Phone_1": "9900000000",
选择列表"Picklist_1" ： "In Progress"，
多选列表"Multi-Select_Picklist"： [
"{Option_1}",
"{Option_2}",
"{Option_3}"
],
日期"Date_1": "2017-08-16",
日期/时间"Date_Time"："2017-08-16T14:32:23+05:30"，
数字"Number_1": 575,
货币"Currency_1": 250000,
小数"Decimal_1": 250000.50,
百分比""Percent_1": 25,
长整型"Long_Integer_1": "250000000000000",
复选框"Checkbox_1": false,
URLURL_1": "https://www.zoho.com.cn/crm",
查找"Lookup" : {
"name" : "James"
"id" : "425248000000104001"
},
记录所有者"Owner": {
"name" : "Patricia"
"id": "425248000000104003"
},
布局"Layout": {
"name" : "Custom Layout 1"
"id": "425248000000404433"
},
CurlJavaPHPPythonDelugeCsharp

示例请求

In the request, "@upsertlead.json" contains the sample input data.


				curl "https://www.zohoapis.com.cn/crm/v2/Leads/upsert"
-H "Authorization: Zoho-oauthtoken 1000.8cb99dxxxxxxxxxxxxx9be93.9b8xxxxxxxxxxxxxxxf"
-d "@upsertlead.json"
-X POST

示例输入


				{
    "data": [
       {
            "Company": "Zylker",
            "Last_Name": "Daly",
            "First_Name": "Paul",
            "Subform_1": [
               {
                    "$approval": {
                        "delegate": false,
                        "approve": false,
                        "reject": false,
                        "resubmit": false
                    },
                    "Owner": {
                        "name": "Chakra",
                        "id": "2883756000000133013"
                    },
                    "$currency_symbol": "$",
                    "Quantity": 1500,
                    "Name": "3",
                    "Name_of_the_product": "Bandages",
                    "Vendor_Email": "d.collins@ebspharma.com",
                    "Price": 15,
                    "id": "2883756000000458386"
                }
            ],
            "Email": "p.daly@zylker.com",
            "State": "Texas"
        },
       {
            "Company": "Villa Margarita",
            "Last_Name": "Dolan",
            "First_Name": "Brian",
            "Email": "brian@villa.com",
            "State": "Texas"
        }
    ],
    "trigger": [
        "approval"
    ]
}

示例响应


				{
    "data": [
       {
            "message": "record updated",
            "details": {
                "created_by": {
                    "id": "4108880000086001",
                    "name": "Patricia Boyle"
                },
                "id": "410888000000478065",
                "modified_by": {
                    "id": "4108880000086001",
                    "name": "Patricia Boyle"
                },
                "modified_time": "2016-04-28T17:59:21+05:30",
                "created_time": "2016-04-28T17:59:21+05:30"
            },
            "status": "success",
            "duplicate_field": "Email",
            "action": "update",
            "code": "SUCCESS"
        },
       {
            "message": "record updated",
            "details": {
                "created_by": {
                    "id": "4108880000086001",
                    "name": "Patricia Boyle"
                },
                "id": "4108880000478066",
                "modified_by": {
                    "id": "4108880000086001",
                    "name": "Patricia Boyle"
                },
                "modified_time": "2016-04-28T17:59:21+05:30",
                "created_time": "2016-04-28T17:59:21+05:30"
            },
            "status": "success",
            "duplicate_field": "Email",
            "action": "update",
            "code": "SUCCESS"
        }
    ]
}

示例请求


				List records = new ArrayList<>();
ZCRMRecord record1 = new ZCRMRecord("Leads"); // 模块API名称
record1.setFieldValue("Company", "Zylker");
record1.setFieldValue("First_name", "Daly");
record1.setFieldValue("Last_Name", "Paul");
record1.setFieldValue("Email", "p.daly@zylker.com");
record1.setFieldValue("State", "Texas");
ZCRMRecord record2 = new ZCRMRecord("Leads"); //模块API名称
record2.setFieldValue("Company", "ekhrj");
record2.setFieldValue("First_name", "John");
record2.setFieldValue("Last_Name", "smith");
record2.setFieldValue("Email", "john.a@ekhrj.com");
record2.setFieldValue("State", "Texas");
records.add(record1);
records.add(record2);
ZCRMModule module = ZCRMModule.getInstance("Leads"); //模块API名称
BulkAPIResponse response = module.upsertRecords(records);
List<ZCRMRecord> upsertedRecords = (List<ZCRMRecord>) response.getData();
List<BulkAPIResponse.EntityResponse> entityResponses = response.getEntityResponses();// 检查请求的状态
String rec1Status = entityResponses.get(0).getStatus();//检查记录1的状态
String rec2Status = entityResponses.get(1).getStatus();//检查记录2的状态

示例输入


				{
    "data": [
       {
            "Company": "Zylker",
            "Last_Name": "Daly",
            "First_Name": "Paul",
            "Subform_1": [
               {
                    "$approval": {
                        "delegate": false,
                        "approve": false,
                        "reject": false,
                        "resubmit": false
                    },
                    "Owner": {
                        "name": "Chakra",
                        "id": "2883756000000133013"
                    },
                    "$currency_symbol": "$",
                    "Quantity": 1500,
                    "Name": "3",
                    "Name_of_the_product": "Bandages",
                    "Vendor_Email": "d.collins@ebspharma.com",
                    "Price": 15,
                    "id": "2883756000000458386"
                }
            ],
            "Email": "p.daly@zylker.com",
            "State": "Texas"
        },
       {
            "Company": "Villa Margarita",
            "Last_Name": "Dolan",
            "First_Name": "Brian",
            "Email": "brian@villa.com",
            "State": "Texas"
        }
    ],
    "trigger": [
        "approval"
    ]
}

示例响应


				{
    "data": [
       {
            "message": "record updated",
            "details": {
                "created_by": {
                    "id": "4108880000086001",
                    "name": "Patricia Boyle"
                },
                "id": "410888000000478065",
                "modified_by": {
                    "id": "4108880000086001",
                    "name": "Patricia Boyle"
                },
                "modified_time": "2016-04-28T17:59:21+05:30",
                "created_time": "2016-04-28T17:59:21+05:30"
            },
            "status": "success",
            "duplicate_field": "Email",
            "action": "update",
            "code": "SUCCESS"
        },
       {
            "message": "record updated",
            "details": {
                "created_by": {
                    "id": "4108880000086001",
                    "name": "Patricia Boyle"
                },
                "id": "4108880000478066",
                "modified_by": {
                    "id": "4108880000086001",
                    "name": "Patricia Boyle"
                },
                "modified_time": "2016-04-28T17:59:21+05:30",
                "created_time": "2016-04-28T17:59:21+05:30"
            },
            "status": "success",
            "duplicate_field": "Email",
            "action": "update",
            "code": "SUCCESS"
        }
    ]
}

示例请求


				$zcrmModuleIns = ZCRMModule::getInstance("Contacts");
$bulkAPIResponse=$zcrmModuleIns->upsertRecords($recordsArray); // $recordsArray - 包含upsert所需数据的ZCRMRecord实例数组。
$entityResponses = $bulkAPIResponse->getEntityResponses();
foreach($entityResponses as $entityResponse)
{
if("success"==$entityResponse->getStatus())
{
echo "Status:".$entityResponse->getStatus();
echo "Message:".$entityResponse->getMessage();
echo "Code:".$entityResponse->getCode();
$upsertData=$entityResponse->getUpsertDetails();
echo "UPSERT_ACTION:".$upsertData[“action”];
echo "UPSERT_DUPLICATE_FIELD:".$upsertData[“duplicate_field”];
$createdRecordInstance=$entityResponse->getData();
echo "EntityID:".$createdRecordInstance->getEntityId();
echo "moduleAPIName:".$createdRecordInstance->getModuleAPIName();
….
}
}

示例输入


				{
    "data": [
       {
            "Company": "Zylker",
            "Last_Name": "Daly",
            "First_Name": "Paul",
            "Subform_1": [
               {
                    "$approval": {
                        "delegate": false,
                        "approve": false,
                        "reject": false,
                        "resubmit": false
                    },
                    "Owner": {
                        "name": "Chakra",
                        "id": "2883756000000133013"
                    },
                    "$currency_symbol": "$",
                    "Quantity": 1500,
                    "Name": "3",
                    "Name_of_the_product": "Bandages",
                    "Vendor_Email": "d.collins@ebspharma.com",
                    "Price": 15,
                    "id": "2883756000000458386"
                }
            ],
            "Email": "p.daly@zylker.com",
            "State": "Texas"
        },
       {
            "Company": "Villa Margarita",
            "Last_Name": "Dolan",
            "First_Name": "Brian",
            "Email": "brian@villa.com",
            "State": "Texas"
        }
    ],
    "trigger": [
        "approval"
    ]
}

示例响应


				{
    "data": [
       {
            "message": "record updated",
            "details": {
                "created_by": {
                    "id": "4108880000086001",
                    "name": "Patricia Boyle"
                },
                "id": "410888000000478065",
                "modified_by": {
                    "id": "4108880000086001",
                    "name": "Patricia Boyle"
                },
                "modified_time": "2016-04-28T17:59:21+05:30",
                "created_time": "2016-04-28T17:59:21+05:30"
            },
            "status": "success",
            "duplicate_field": "Email",
            "action": "update",
            "code": "SUCCESS"
        },
       {
            "message": "record updated",
            "details": {
                "created_by": {
                    "id": "4108880000086001",
                    "name": "Patricia Boyle"
                },
                "id": "4108880000478066",
                "modified_by": {
                    "id": "4108880000086001",
                    "name": "Patricia Boyle"
                },
                "modified_time": "2016-04-28T17:59:21+05:30",
                "created_time": "2016-04-28T17:59:21+05:30"
            },
            "status": "success",
            "duplicate_field": "Email",
            "action": "update",
            "code": "SUCCESS"
        }
    ]
}

示例请求


				def upsert_records(self):
    try:
        record_ins_list=list()
        for i in range(0,2):
            record=ZCRMRecord.get_instance('Invoices') #module API Name
            record.set_field_value('Subject', 'Invoice'+str(i))
            record.set_field_value('Account_Name', 'IIIT')
            user=ZCRMUser.get_instance(440872000000175001,'Python Automation User1')
            record.set_field_value('Owner',user
            line_item=ZCRMInventoryLineItem.get_instance(ZCRMRecord.get_instance("Products",440872000000224005))
            line_item.discount=10
            line_item.list_price=8
            line_item.description='Product Description'
            line_item.quantity=100
            line_item.tax_amount=2.5
            taxIns=ZCRMTax.get_instance("Vat")
            taxIns.percentage=5
            line_item.line_tax.append(taxIns)
            record.add_line_item(line_item)
            record_ins_list.append(record)
        record=ZCRMRecord.get_instance('Invoices',440872000000248818)
        record.set_field_value('Subject', 'Invoice1.1')
        line_item=ZCRMInventoryLineItem.get_instance(ZCRMRecord.get_instance("Products",440872000000224005))
        line_item.discount=10
        line_item.list_price=8
        line_item.description='Product Description'
        line_item.quantity=100
        line_item.tax_amount=2.5
        taxIns=ZCRMTax.get_instance("Vat")
        taxIns.percentage=5
        line_item.line_tax.append(taxIns)
        record.add_line_item(line_item)
        record_ins_list.append(record)
        resp=ZCRMModule.get_instance('Invoices').upsert_records(record_ins_list)
        print resp.status_code
        entity_responses=resp.bulk_entity_response
        for entity_response in entity_responses:
            print entity_response.details
            print entity_response.status
            print entity_response.message
            print entity_response.code
            print entity_response.data.entity_id
            print entity_response.data.created_by.id
            print entity_response.data.created_time
            print entity_response.data.modified_by.id
            print "\n\n"
    except ZCRMException as ex:
        print ex.status_code
        print ex.error_message
        print ex.error_code
        print ex.error_details
        print ex.error_content

示例输入


				{
    "data": [
       {
            "Company": "Zylker",
            "Last_Name": "Daly",
            "First_Name": "Paul",
            "Subform_1": [
               {
                    "$approval": {
                        "delegate": false,
                        "approve": false,
                        "reject": false,
                        "resubmit": false
                    },
                    "Owner": {
                        "name": "Chakra",
                        "id": "2883756000000133013"
                    },
                    "$currency_symbol": "$",
                    "Quantity": 1500,
                    "Name": "3",
                    "Name_of_the_product": "Bandages",
                    "Vendor_Email": "d.collins@ebspharma.com",
                    "Price": 15,
                    "id": "2883756000000458386"
                }
            ],
            "Email": "p.daly@zylker.com",
            "State": "Texas"
        },
       {
            "Company": "Villa Margarita",
            "Last_Name": "Dolan",
            "First_Name": "Brian",
            "Email": "brian@villa.com",
            "State": "Texas"
        }
    ],
    "trigger": [
        "approval"
    ]
}

示例响应


				{
    "data": [
       {
            "message": "record updated",
            "details": {
                "created_by": {
                    "id": "4108880000086001",
                    "name": "Patricia Boyle"
                },
                "id": "410888000000478065",
                "modified_by": {
                    "id": "4108880000086001",
                    "name": "Patricia Boyle"
                },
                "modified_time": "2016-04-28T17:59:21+05:30",
                "created_time": "2016-04-28T17:59:21+05:30"
            },
            "status": "success",
            "duplicate_field": "Email",
            "action": "update",
            "code": "SUCCESS"
        },
       {
            "message": "record updated",
            "details": {
                "created_by": {
                    "id": "4108880000086001",
                    "name": "Patricia Boyle"
                },
                "id": "4108880000478066",
                "modified_by": {
                    "id": "4108880000086001",
                    "name": "Patricia Boyle"
                },
                "modified_time": "2016-04-28T17:59:21+05:30",
                "created_time": "2016-04-28T17:59:21+05:30"
            },
            "status": "success",
            "duplicate_field": "Email",
            "action": "update",
            "code": "SUCCESS"
        }
    ]
}

示例请求


				语法：
zoho.crm.upsert(<module String>,<dataMap Map>,<optionalDataMap Map>,<connectionName String>,<userAccess Boolean>);
mandatory : module,dataMap

示例请求：
resp = zoho.crm.upsert("Leads", {"Last_Name":"Patricia upsert UF2", "UF":"p.boyle@zylker.com", "Email":"d.grogan@zylker.com"}, {"duplicate_check_fields":["UF" , "Email"]});

示例输入


				{
    "data": [
       {
            "Company": "Zylker",
            "Last_Name": "Daly",
            "First_Name": "Paul",
            "Subform_1": [
               {
                    "$approval": {
                        "delegate": false,
                        "approve": false,
                        "reject": false,
                        "resubmit": false
                    },
                    "Owner": {
                        "name": "Chakra",
                        "id": "2883756000000133013"
                    },
                    "$currency_symbol": "$",
                    "Quantity": 1500,
                    "Name": "3",
                    "Name_of_the_product": "Bandages",
                    "Vendor_Email": "d.collins@ebspharma.com",
                    "Price": 15,
                    "id": "2883756000000458386"
                }
            ],
            "Email": "p.daly@zylker.com",
            "State": "Texas"
        },
       {
            "Company": "Villa Margarita",
            "Last_Name": "Dolan",
            "First_Name": "Brian",
            "Email": "brian@villa.com",
            "State": "Texas"
        }
    ],
    "trigger": [
        "approval"
    ]
}

示例响应


				{
    "data": [
       {
            "message": "record updated",
            "details": {
                "created_by": {
                    "id": "4108880000086001",
                    "name": "Patricia Boyle"
                },
                "id": "410888000000478065",
                "modified_by": {
                    "id": "4108880000086001",
                    "name": "Patricia Boyle"
                },
                "modified_time": "2016-04-28T17:59:21+05:30",
                "created_time": "2016-04-28T17:59:21+05:30"
            },
            "status": "success",
            "duplicate_field": "Email",
            "action": "update",
            "code": "SUCCESS"
        },
       {
            "message": "record updated",
            "details": {
                "created_by": {
                    "id": "4108880000086001",
                    "name": "Patricia Boyle"
                },
                "id": "4108880000478066",
                "modified_by": {
                    "id": "4108880000086001",
                    "name": "Patricia Boyle"
                },
                "modified_time": "2016-04-28T17:59:21+05:30",
                "created_time": "2016-04-28T17:59:21+05:30"
            },
            "status": "success",
            "duplicate_field": "Email",
            "action": "update",
            "code": "SUCCESS"
        }
    ]
}

示例请求


				List<ZCRMRecord> records = new List<ZCRMRecord>();
ZCRMRecord record1 = new ZCRMRecord("Leads"); //模块API名称
record1.SetFieldValue("Company", "Zylker");
record1.SetFieldValue("First_name", "Daly");
record1.SetFieldValue("Last_Name", "Paul");
record1.SetFieldValue("Email", "p.daly@zylker.com");
record1.SetFieldValue("State", "Texas");
ZCRMRecord record2 = new ZCRMRecord("Leads"); //模块API名称
record2.SetFieldValue("Company", "ekhrj");
record2.SetFieldValue("First_name", "John");
record2.SetFieldValue("Last_Name", "smith");
record2.SetFieldValue("Email", "john.a@ekhrj.com");
record2.SetFieldValue("State", "Texas");
records.Add(record1);
records.Add(record2);
ZCRMModule moduleIns = ZCRMModule.GetInstance("Leads"); //模块API名称
BulkAPIResponse<ZCRMRecord> response = moduleIns.UpsertRecords(records); //records - 包含upsert所需数据的ZCRMRecord实例列表。
List<ZCRMRecord> upsertedRecords = response.BulkData; //upsertedRecords - ZCRMRecord实例的列表
List<EntityResponse> entityResponses = response.BulkEntitiesResponse; //entityResponses - EntityResponses实例的列表

示例输入


				{
    "data": [
       {
            "Company": "Zylker",
            "Last_Name": "Daly",
            "First_Name": "Paul",
            "Subform_1": [
               {
                    "$approval": {
                        "delegate": false,
                        "approve": false,
                        "reject": false,
                        "resubmit": false
                    },
                    "Owner": {
                        "name": "Chakra",
                        "id": "2883756000000133013"
                    },
                    "$currency_symbol": "$",
                    "Quantity": 1500,
                    "Name": "3",
                    "Name_of_the_product": "Bandages",
                    "Vendor_Email": "d.collins@ebspharma.com",
                    "Price": 15,
                    "id": "2883756000000458386"
                }
            ],
            "Email": "p.daly@zylker.com",
            "State": "Texas"
        },
       {
            "Company": "Villa Margarita",
            "Last_Name": "Dolan",
            "First_Name": "Brian",
            "Email": "brian@villa.com",
            "State": "Texas"
        }
    ],
    "trigger": [
        "approval"
    ]
}

示例响应


				{
    "data": [
       {
            "message": "record updated",
            "details": {
                "created_by": {
                    "id": "4108880000086001",
                    "name": "Patricia Boyle"
                },
                "id": "410888000000478065",
                "modified_by": {
                    "id": "4108880000086001",
                    "name": "Patricia Boyle"
                },
                "modified_time": "2016-04-28T17:59:21+05:30",
                "created_time": "2016-04-28T17:59:21+05:30"
            },
            "status": "success",
            "duplicate_field": "Email",
            "action": "update",
            "code": "SUCCESS"
        },
       {
            "message": "record updated",
            "details": {
                "created_by": {
                    "id": "4108880000086001",
                    "name": "Patricia Boyle"
                },
                "id": "4108880000478066",
                "modified_by": {
                    "id": "4108880000086001",
                    "name": "Patricia Boyle"
                },
                "modified_time": "2016-04-28T17:59:21+05:30",
                "created_time": "2016-04-28T17:59:21+05:30"
            },
            "status": "success",
            "duplicate_field": "Email",
            "action": "update",
            "code": "SUCCESS"
        }
    ]
}