Zoho crm Logo

创建批量写作任务

目的

创建一个批量写入作业,以将记录导入到CRM中。

端点

  • POST /write

Request 详情

Request URL

{api-domain}/crm/bulk/{version}/write

标题

授权:Zoho-oauthtoken d92d4xxxxxxxxxxxxx15f52

范围

scope=ZohoCRM.bulk.CREATE
(或)
scope=ZohoCRM.bulk.ALL
(和)
scope=ZohoCRM.modules.ALL
(或)
scope=ZohoCRM.modules.{module_name}.{operation_type}

可能的模块名称

潜在客户,账户,联系人,交易,活动,案例,解决方案,产品,供应商,价格手册,任务,报价,销售订单,采购订单,发票,以及自定义

可能的操作类型

ALL - 对记录的完全访问
CREATE - 创建批量写入任务

样本请求

Request JSON

  • character_encoding字符串,可选

    表示上传文件的字符集。通常会自动检测,但如果指定,则将用于读取文件。

  • operation字符串,必填

    表示您想要在批量写入作业上执行的操作类型。

    值包括

    • insert - 用于在CRM中创建CSV新记录。
    • update - 用于更新CRM中的现有记录(此操作不允许创建新记录)。
    • upsert - 用于更新CRM中的现有记录,并创建新记录,如果它们尚不存在。
  • ignore_empty布尔值,可选

    True - 忽略列中的空值,并仅更新记录中没有空值的字段
    False或空 - 系统会使用给定文件列中的空值更新CRM中的记录。
    默认值是false。

  • callbackJSON 对象,可选

    一个有效的URL,允许HTTP POST方法。批量写入作业的详细信息在作业成功完成或失败时POST到此URL。示例 - "callback" : { "url": "HTTPs://sampledomain.com/getzohoresponse", "method": "POST" }。
    这个JSON对象接受两个键——url和method。

    • url(字符串) - 一个有效的URL,应允许HTTP POST方法。批量写入作业的详细信息在作业成功完成或失败时POST到此URL。
    • method(字符串) - 回调url的HTTP方法。支持的值是POST。
  • 资源JSON 数组,必须的

    一个JSON数组,包含您想要导入的模块的API名称,它们的字段映射,以及从上传API获取的相应文件ID。

    • type(字符串,必填) - 表示您想要导入的模块类型。其值为data。
    • 模块(JSON 对象,必填) - 你为批量写入任务选择的模块的API名称。
      对于子表单:当你想要批量写入子表单数据时,你必须在这里给出子表单的API名称。
    • file_id(字符串,必填) - 从文件上传API获取的file_id。
    • find_by(字符串,更新和upsert操作必须,插入操作可选) - 唯一字段或记录ID的API名称。系统使用此字段的值在CRM中查找现有记录。在插入操作中,如果提供了find_by,系统将从文件中跳过重复的记录。
    • field_mappings(JSON 数组,可选) - 当系统处理 CSV 文件时,第一行被视为标题行。每个标题名称都被视为字段API名称,列中的数据被填充到由API名称表示的相应字段中。此参数可帮助您跳过自动映射并定义自己的字段映射。

      注意:

      • 默认情况下,字段映射是自动处理的。如果你想定义自己的,你可以手动映射字段。
      • 如果你在输入中包含这个数组,CSV 中的数据将仅根据此数组中的索引值进行映射。
    • api_name(字符串,必填) - 您想要导入的Zoho模块对象中字段的API名称。请参考字段元数据API以获取模块中可用的字段列表。无效的字段API名称会抛出错误。
    • index(数字,可选) - 您想要映射到CRM字段的字段的列索引。当您指定一个不存在的索引值时,系统会抛出一个错误。
    • find_by(字符串,查找字段必填) - 模块中唯一字段的API名称,系统会根据此字段检查CRM中是否存在现有记录。您也可以使用id,系统定义的唯一字段的API名称,自定义唯一字段,查找字段,基于组织的外部ID,以及显示列/字段(基于字段显示的结果,当您搜索关联查找时列出。例如,当您在联系人中查找指向账户的查找时,账户名称就是显示列。)作为find_by字段。
    • default_value(JSON 对象,可选) - 如果某些记录在某列中没有值,你想用默认值替换它,可以使用此键。例如:{"value": "Trade Show"}。以下字段在 default_value 键中不受支持:多行,唯一字段,和显示字段。

    注意

    • 对于子表单

      field_mappings 数组必须有以下必需的对象,除了子表单的其他字段的详细信息。这是为了将子表单记录与相应的父记录进行映射。

       "api_name":"Parent_Id", "find_by":"id", "index":"the_index_in_the_csv"
    • 自定义布局

      要将批量数据映射到特定布局,您必须在"default_value" JSON 对象下指定自定义布局的唯一ID。每当指定布局时,"default_value"字段都是必填的。当您将记录批量插入模块的特定布局时,系统只验证该布局中定义的必填字段。在此操作期间,将忽略其他布局的必填字段。

      示例:
      "api_name": "Layout", "default_value": { "value": "{custom Layout ID}" }

      您可以从元数据布局API获取布局ID。

    • 要在特定布局中插入记录,您必须在CSV文件中指定自定义布局的名称。如果未指定/指定了错误的值,系统将在该模块中的默认布局中插入记录。此外,您必须在输入中的field_mappings键中指定相关详细信息。有关更多详细信息,请参考样本输入。
    • 对于日期和日期/时间等字段类型,有默认格式。例如,日期的默认格式是MM/dd/yyyy,日期/时间的默认格式是MM/dd/yyyy HH:mm:ss。如果你在CSV文件中以任何其他格式指定这些字段的值,你必须在输入中指定格式。请参考样本输入以获取更多详细信息。
    • 日期,日期-时间,数字字段(整数,小数,百分比,长整数),货币字段,这些都是支持的格式字段。点击这里了解允许的格式。
    • 默认情况下,日期和日期时间字段支持ISO格式。
    • 结果文件可在七天内访问。
    • 压缩的 CSV 文件格式在批量写入API中得到支持。

批量请求的样本输入

批量插入子表单数据的示例输入

Request JSON用于父子模块

父模块是主模块,而子表单、行项目、多选查找字段和多用户查找字段是父模块中的子项。您必须为父项和子项拥有单独的CSV文件。

  • character_encoding字符串,可选

    表示上传文件的字符集。通常会自动检测,但如果指定,则将用于读取文件。

  • operation字符串,必填

    表示您想要在批量写入作业上执行的操作类型。

    值包括

    • insert - 创建CSV记录作为CRM中的新记录。
    • update - 更新CRM中的现有记录(此操作不允许创建新记录)。
    • upsert - 更新CRM中的现有记录,并创建新记录(如果它们尚不存在)。
  • ignore_empty布尔值,可选

    True - 忽略列中的空值,并仅更新记录中没有空值的字段
    False或空 - 系统将在给定文件列中有空值的情况下更新CRM中的记录。
    默认值是false。

  • callbackJSON 对象,可选

    一个有效的URL,允许HTTP POST方法。批量写入作业的详细信息在作业成功完成或失败时POST到此URL。示例 - "callback" : { "url": "HTTPs://sampledomain.com/getzohoresponse", "method": "POST" }。
    这个JSON对象接受两个键——url和method。

    • url(字符串) - 一个有效的URL,应允许HTTP POST方法。批量写入作业的详细信息在作业成功完成或失败时POST到此URL。
    • method(字符串) - 回调url的HTTP方法。支持的值是POST。
  • 资源JSON 数组,必填

    一个包含您想要导入的父模块和子模块的API名称的JSON对象数组,它们的字段映射,以及从上传API获取的相应文件ID。请注意,此数组中的第一个对象必须包含父模块的详细信息。 请注意,当您想要将大量数据写入具有多选查找字段的父模块时,您的第一个CSV文件必须包含父模块的数据,第二个CSV文件必须包含链接模块的数据。

    • type(字符串,必填) - 表示您想要导入的模块类型。值为 data。
    • 模块(JSON 对象,必填) - 你为批量写入任务选择的模块的 API 名称。
      对于子表单或多用户查找,给出它们各自的 API 名称。对于多选查找,指定链接模块的 API 名称。
    • file_id(字符串,必填) - 从文件上传API获取的file_id。此ID必须在父模块和子模块中保持一致。
    • file_names(JSON 数组,必填) - 你上传的 CSV 文件的名称。这是为了将正确的 CSV 文件与正确的模块进行匹配。
    • find_by(字符串,更新和upsert操作必需,插入操作可选) - 唯一字段或记录ID的API名称。系统使用此字段的值在CRM中查找现有记录。在插入操作中,如果提供了find_by,系统将从文件中跳过重复的记录。
    • field_mappings(JSON数组,必填) - 当系统处理CSV文件时,第一行被视为标题行。每个标题名称都被视为字段API名称,列中的数据将填充到由API名称表示的相应字段中。此参数可帮助您跳过自动映射并定义自己的字段映射。 

      注意:

      • 默认情况下,字段映射是自动处理的。如果你想定义自己的,你可以手动映射字段。
      • 如果你在输入中包含这个数组,CSV中的数据将仅根据此数组中的索引值进行映射。
    • api_name(字符串,必填) - 您想要导入的Zoho模块对象中字段的API名称。请参考字段元数据API以获取模块中可用的字段列表。无效的字段API名称会抛出错误。
    • parent_column_index(数字,资源数组中的子对象必填) - 这个键有助于将正确的父记录与子记录进行映射。例如,假设你的父模块是Leads,并且它有一个子表单。父CSV包含500条记录的数据,子表单CSV包含500条子表单记录的数据。这些子表单记录每一条都属于一个特定的潜在客户。因此,要将正确的子记录与正确的父记录进行映射,你必须使用"parent_column_index"键。为了建立这种映射,父记录和子记录之间必须有一个共同的列。
      对于子表单和行项目,它必须是"Parent_Id"。
      对于多选查找和多用户查找,它必须是链接模块中父查找的API名称。 
      例如,如果你有一个父模块Leads,它有一个多选查找到Contacts,那么链接模块将是Leads vs Contacts。所以,你的父CSV将用于Leads,子CSV将用于链接模块。在这里,要将子记录与父记录进行映射,你必须为链接模块中父查找字段指定parent_column_index。
      请参阅注释部分以获取更多详细信息。
    • index(数字,可选) - 您想要映射到CRM字段的字段的列索引。当您指定一个不存在的索引值时,系统会抛出一个错误。
    • find_by(字符串,查找字段必填) - 模块中唯一字段的API名称,系统会根据此字段检查CRM中是否存在现有记录。您也可以使用id,系统定义的唯一字段的API名称,自定义唯一字段,查找字段,基于组织的外部ID,和显示列/字段(基于字段显示的结果,当您搜索关联查找时列出。例如,当您在联系人中查找指向账户的查找时,账户名称就是显示列。)作为find_by字段。当您包含parent_column_index时,此键不需要。
    • default_value(JSON 对象,可选) - 如果某些记录在某列中没有值,你想用默认值替换它,就使用这个键。例如:{"value": "Trade Show"}。以下字段在 default_value 键中不受支持:多行,唯一字段,和显示字段。

注释

  • "resource"数组中的第一个对象必须是父对象的详细信息。
  • 每个模块只能映射一个CSV文件。
  • 对于子表单和行项目,您可以映射任何系统定义和自定义字段。
  • 对于多选查找和多用户查找,您只能映射链接模块中的查找字段。

父子模块的示例输入

Response 结构

  • statusstring

    指定API调用的状态。示例 - "status": "success"。

  • messagestring

    指定作业的预定义评论。在发生任何错误时非常有用。

  • detailsJSON 对象

    包含批量写入作业的以下详细信息。

    • id(string) - 指定批量写入作业的唯一标识符(job_id)。示例 - "id": "111111000000541958"。
    • created_by(JSON 对象) - 指定启动批量写入作业的用户的ID和名称。示例 - "created_by": { "id": "111111000000035795", "name": "Patricia Boyle" }。

可能的错误

  • MANDATORY_FIELDS_NOT_MAPPED HTTP 400

    模块中的所有必填字段都未映射。
    解决方案:映射模块中的所有必填字段。

  • MANDATORY_NOT_FOUND HTTP 400

    请求体中未指定必需的键或值。例如:"message": "Required key find_by is not available".
    解决方案:在输入中包含所需的键。

  • INVALID_FIELD HTTP 400

    字段API名称无效。
    解决方案:指定字段的正确API名称。

  • INVALID_FORMAT HTTP 400

    您输入的日期格式错误。
    解决方案: 请以正确的格式输入日期。

  • INVALID_FILE_ID HTTP 400

    指定的文件ID无效。
    解决方案:指定在上传CSV文件时收到的正确文件ID。

  • HEADER_LIMIT_EXCEEDED HTTP 400

    映射的字段数量已超过最大限制200。
    解决方案:您只能映射最多200个字段。

  • COLUMN_INDEX_NOT_FOUND HTTP 400

    索引映射了负值。
    解决方案: "index"只能取正整数值。

  • MODULE_NOT_AVAILABLE HTTP 400

    指定的模块名称无效。
    解决方案:模块的API名称可能错误,或者此模块不支持批量写入作业。请参阅“可能的模块名称”部分,查看支持的模块列表。

  • INVALID_URL_PATTERNHTTP 404

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

  • OAUTH_SCOPE_MISMATCHHTTP 401

    未经授权
    解决方案:客户端没有ZohoCRM.bulk.CREATE。创建一个具有有效范围的新客户端。请参考上面的范围部分。

  • NO_PERMISSIONHTTP 403

    拒绝创建权限
    解决方案:用户没有创建批量写作任务的权限。请联系您的系统管理员。

  • INTERNAL_ERRORHTTP 500

    内部服务器错误
    解决方案:服务器中出现意外且未处理的异常。请联系支持团队。

  • INVALID_REQUEST_METHODHTTP 400

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

  • AUTHORIZATION_FAILEDHTTP 400

    用户没有足够的权限来创建。
    解决方案:用户没有创建批量写入作业的权限。请联系您的系统管理员。

样本回应