Zoho crm Logo

更新自定义字段

目的

要在您的Zoho CRM账户中更新自定义字段。

端点

  • PATCH /settings/fields?module={module_API_name}
  • PATCH /settings/fields/{field_ID}?module={module_API_name}

请求详情

请求 URL

要更新多个字段:

{api-domain}/crm/{version}/settings/fields

要更新单个字段:

{api-domain}/crm/{version}/settings/fields/{field_ID}

标题

授权:Zoho-oauthtoken d92d4xxxxxxxxxxxxx15f52

范围

ZohoCRM.settings.fields.UPDATE  (或)
ZohoCRM.settings.fields.ALL  (或)
ZohoCRM.settings.ALL

更新单个字段的示例请求

Copiedcurl "https://www.zohoapis.com/crm/v8/settings/fields/111112000000067259?module=Leads"
-X PATCH
-d "input.json"
-H "Authorization: Zoho-oauthtoken 1000.8cb99dxxxxxxxxxxxxx9be93.9b8xxxxxxxxxxxxxxxf"

参数

  • module字符串,必填

    指定您要更新自定义字段的模块。使用 GET - 模块 API 获取模块的 API 名称和 ID。

    支持的模块:线索、联系人、Account、市场活动、工单、Invoices、商机、价格手册、产品、Purchase Orders、报价单、SalesOrders、解决方案、Vendors、通话、任务、日程、Users、DealHistory、报价Items、OrderItems、采购Items、InvoiceItems、拜访、服务、预约和自定义。

注意

  • 所有在 创建自定义字段 API 帮助文档中说明的字段类型和用例,都支持 Update自定义字段 API。
  • 使用 GET - 字段元数据 API 检索字段 ID。
  • 系统定义字段的字段标签无法Update。
  • 每次调用最多只能Update 五 个字段。
  • 无法将一个字段类型转换为另一种类型。
  • 外部属性无法Update。
  • 在 文本区域数据类型中:
    • 长度值无法Update。
    • 类型值无法Update为其他类型,例如不能将 small 更新为 rich_text。
      示例:"textarea" : { "type": "small" }
  • 字段的API 名称只能在界面中修改。
  • 如果特定模块允许 HIPAA 字段,且隐私设置已启用,则 HIPAA 属性可Update。

将示例输入更新为“文本”数据类型

Copied{
    "fields": [
        {
            "length": 200, //updating the value of length
            "unique": {
                "case_sensitive": false,
                "_disable": null //marking the field is not a unique key.
            }
        }
    ]
}

示例回复

Copied{
    "fields": [
        {
            "code": "SUCCESS",
            "details": {
                "id": "111112000000067259"
            },
            "message": "field updated",
            "status": "success"
        }
    ]
}

输入 JSON 

示例请求以更新多个字段

Copiedcurl "https://www.zohoapis.com/crm/v8/settings/fields?module=Leads"
-X PUT
-d "input.json"
-H "Authorization: Zoho-oauthtoken 1000.8cb99dxxxxxxxxxxxxx9be93.9b8xxxxxxxxxxxxxxxf"

用于更新多个字段的示例输入

Copied{
    "fields": [
        {
            "id": "111112000000069633",  //Field Type: Lookup
            "lookup": {
                "query_details": {
                    "criteria": {
                        "field": {
                            "api_name": "Email"
                        },
                        "comparator": "ends_with",
                        "value": "@zohocorp.com"
                    }
                }
            }
        },
        {
            "id": "111112000000070141", //Field Type: Currency
            "currency": {
                "rounding_option": "normal",
                "precision": 2
            }
        },
        {
            "id": "111111000000166083", //Field Type : User Lookup
            "sharing_properties": {
                "share_preference_enabled": true,
                "share_permission": "full-access"
            }
        }
    ]
}

输入 JSON 键

 

更新下拉列表字段("datatype" : "picklist")

以下键是更新下拉列表字段选项时必填的。

  • pick_list_valuesJSON 数组,必填

    表示下拉列表字段的值或选项。

    • display_value字符串,必填

      下拉列表的唯一显示值,将显示在 CRM 用户界面中。

注意

  • 在更新选项列表字段中的选项时,display_value 字段是必填项。
  • 使用选项列表的 actual_value 或 唯一ID 来Update其显示值。
  • 如需从选项列表中移除某个选项,请使用 Update自定义布局 API。请参阅将选项列表选项标记为未使用的示例输入部分。

示例请求以更新“选项列表”数据类型

Copiedcurl "https://www.zohoapis.com/crm/v8/settings/fields/111112000000067259?module=Leads"
-X PATCH
-d "input.json"
-H "Authorization: Zoho-oauthtoken 1000.8cb99dxxxxxxxxxxxxx9be93.9b8xxxxxxxxxxxxxxxf"

向选项列表字段添加新选项的示例输入

Copied{
    "fields": [
        {
            "pick_list_values": [
                {
                    "display_value": "North_East",
                    "actual_value": "IN_North_East",
                } //Adding options to an existing picklist         
            ]
        }
    ]
}

用于更新现有选项列表数据的示例输入

Copied{
    "fields": [
        {
            "profiles": [
               
                {
                    "id": "5725767000000026011",
                    "permission_type": "read_write" //updating the permission_type
                }
            ],
           "pick_list_values": [
                {
                     "display_value": "East Zone East Zone", // updating the display value
                    "actual_value": "IN_EastZone",
                    "id": "5725767000003489002"
                }
            ]
        }
    ]
}

更新汇总摘要("datatype" : "rollup_summary")字段

注意

  • 在 rollup_summary.expression 中,只能修改 criteria 字段。

用于更新 "rollup_summary" 数据类型的示例请求

Copiedcurl "https://www.zohoapis.com/crm/v8/settings/fields/3602353000000575124?module=Leads"
-X PATCH
-d "input.json"
-H "Authorization: Zoho-oauthtoken 1000.8cb99dxxxxxxxxxxxxx9be93.9b8xxxxxxxxxxxxxxxf"

示例输入

Copied{
    "fields": [
        {
            "field_label": "Total Invoice Amount",
            "data_type": "rollup_summary",
            "rollup_summary": {
                "return_type": "currency",
                "expression": {
                    "function_parameters": [
                        {
                            "api_name": "Grand_Total"
                        }
                    ],
                    "criteria": {
                        "group_operator": "AND",
                        "group": [
                            {
                                "comparator": "equal",
                                "field": {
                                    "api_name": "Billing_Country"
                                },
                                "value": "United States"
                            },
                            {
                                "comparator": "equal",
                                "field": {
                                    "api_name": "Billing_State"
                                },
                                "value": "Massachusetts"
                            } //Adding new condition
                        ]
                    },
                    "function": "SUM"
                },
                "based_on_module": {
                    "api_name": "Invoices"
                },
                "related_list": {
                    "api_name": "Invoices"
                }
            }
        }
    ]
}

更新动态公式("datatype" : "formula")字段

更新“formula”数据类型的示例请求

Copiedcurl "https://www.zohoapis.com/crm/v8/settings/fields/3602353000000570393?module=Deals"
-X PATCH
-d "input.json"
-H "Authorization: Zoho-oauthtoken 1000.8cb99dxxxxxxxxxxxxx9be93.9b8xxxxxxxxxxxxxxxf"

示例输入

Copied{
    "fields": [
        {
            "json_type": "double",
            "field_label": "Deal Age",
            "display_label": "Age of the deal",
            "length": 16,
            "api_name": "Deal_age",
            "data_type": "formula",
            "id": "3602353000000570393",
            "formula": {
                "expression": "Datecomp(${modified_time},Now())",
                "return_type": "double",
                "dynamic": true,
                "stop_compute_conditionally": false
            },
            "decimal_place": 2
        }
    ]
}

输入 JOSN

 

将选项列表转换为全局选项列表

  • 字段JSON 数组,必填

    包含选项列表字段和全局选项列表字段的详细信息。

    • id字符串,必填

      表示您要转换为全局选值字段的选值字段唯一ID。

    • pick_list_valuesJSON 数组,可选

      包含下拉列表字段值与全局下拉列表字段值之间的映射详细信息。

      • id字符串,必填

        表示下拉列表字段中一个值的ID。使用 GET - 字段元数据 API 获取模块中所有下拉列表字段("data_type": "picklist")。

      • _global_picklist_valueJSON 对象,可选

        表示全局下拉列表字段中该值的ID。使用 GET - 获取全局下拉列表 API 获取所有全局下拉列表字段及其值。

    • global_picklistJSON 对象,必填

      使用 GET - 获取全局选项集 API 来检索您的组织中所有可用的全局选项字段。

注意

  • 您可以将选项列表字段中的值映射到全局选项列表字段中的值。默认情况下,如果您未进行映射,选项列表字段中的所有值将被全局选项列表字段的值替换。
  • 任何包含现有选项列表值的记录或配置也将被全局选项列表字段的值替换。

示例请求:将选项列表字段转换为全局选项列表字段

Copiedcurl "https://www.zohoapis.com/crm/v8/settings/fields?module=Leads"
-X PATCH
-d "input.json"
-H "Authorization: Zoho-oauthtoken 1000.8cb99dxxxxxxxxxxxxx9be93.9b8xxxxxxxxxxxxxxxf"

示例输入

Copied{
    "fields": [
        {
            "id": "2276164000002053013", //picklist ID
            "pick_list_values": [
                {
                    "id": "2276164000002053012", //local picklist value's ID
                    "_global_picklist_value": {
                        "id": "2276164000002053039" //global picklist value's ID
                    }
                },
                {
                    "id": "2276164000002053014", 
                    "_global_picklist_value": {
                        "id": "2276164000002053041"
                    }
                }
            ],
            "global_picklist": {
                "api_name": "Market",
                "id": "2276164000002053035"
            }
        }
    ]
}

输入 JOSN

 

将全局选项集字段转换为普通选项集字段

  • id字符串,必填

    表示全局选项集字段的唯一 ID。请使用 GET - 全局选项集 API获取全局选项集字段 ID。

  • global_picklistJSON 对象,必填

    表示将全局选项集字段转换为普通选项集字段。

将全局选项集字段转换为选项集字段的示例请求

Copiedcurl "https://www.zohoapis.com/crm/v8/settings/fields?module=Leads"
-X PATCH
-d "input.json"
-H "Authorization: Zoho-oauthtoken 1000.8cb99dxxxxxxxxxxxxx9be93.9b8xxxxxxxxxxxxxxxf"

示例输入

Copied{
    "fields": [
        {
            "id": "5725767000006269064", //unique ID of the Global picklist field
            "global_picklist": null
        }
    ]
}

示例回复

Copied{
    "fields": [
        {
            "code": "SUCCESS",
            "details": {
                "id": "5725767000006269064"
            },
            "message": "field updated",
            "status": "success"
        }
    ]
}

输入 JSON

 

启用或禁用选项列表字段的历史记录跟踪
  • history_tracking_enabled布尔值,必填

    你可以为现有选项列表在模块中启用或禁用历史记录追踪。使用此键可以启用或禁用选项列表字段的历史记录追踪。

  • history_trackingJSON 对象,可选

    包含用于跟踪选项列表字段历史记录的配置信息。

    • related_list_name字符串,可选

      指定相关列表的名称,在记录详情视图中以相关列表的形式显示选项字段的历史。如果未指定,系统将根据字段标签自动生成。related_list_name 的值最多可包含25 个字符,且不能包含特殊字符。

    • duration_configuration字符串,可选

      指定用于追踪历史记录的时间单位(例如:天或时间)。

      可能的值:

      • days (默认)- 按天追踪历史记录。
      • time - 按时间追踪历史记录。
        • 注意: 在指定时间值之前,请通过联系 support@zohocrm.com 启用贵组织的时长自定义功能。
    • followed_fieldsJSON 数组, 可选

      指定要与主选项字段一起跟踪的其他字段,以便全面跟踪相关字段的变更。数组中的每个对象必须包含被跟踪字段的API名称或唯一ID。请参考 GET - 字段元数据 API 获取模块中字段的 API 名称和 ID。 

      例如,如果销售团队通过跟踪 Property Status(物业状态) 选项字段来监控物业在每个阶段停留的时间,他们可以将 分配用户(User Assigned) 添加到 followed_fields 中,以便跟踪每个阶段处理该物业的用户。

注意

  • 在关注字段中,
    • 您最多可以选择10个字段,其中每个模块最多只能将5个自定义字段设置为关注字段,交易模块除外。
    • 交易模块,
      • 默认情况下,交易模块会跟踪阶段选项字段的阶段历史。
      • 您可以将更多关注字段作为列添加到现有的阶段历史中。
      • 您还可以更改相关列表名称,并最多添加六个额外的关注字段。您最多可以选择六个字段,其中最多五个为自定义字段。
    • 加密字段无法被选为关注字段。

用于请求禁用下拉选择字段的历史跟踪的示例

Copiedcurl "https://www.zohoapis.com/crm/v8/settings/fields/5725767000005821005?module=Leads"
-X PATCH
-d "input.json"
-H "Authorization: Zoho-oauthtoken 1000.8cb99dxxxxxxxxxxxxx9be93.9b8xxxxxxxxxxxxxxxf"

禁用选项字段历史跟踪的示例输入

Copied{
    "fields": [
        {
            "history_tracking_enabled": false //mandatory field
        }
    ]
}

用于更新启用历史跟踪的选项列表中现有值的示例输入

Copied{
    "fields": [
        {
            "history_tracking_enabled": true, 
            "history_tracking": {
                 "related_list_name": "Region Tracker", //updating the related list name
                "duration_configuration": "time", //updating the value from "days" to. "time"
                "followed_fields": [
                    {
                        "api_name": "Owner", //removing the owner field from the "followed fields" key 
                        "_delete" : null
                    },
                    {
                        "api_name": "Company", //adding the Company field to the "followed fields" key 
                        "id": "5725767000000002591"
                    }
                ]
            }
        }
    ]
}

可能的错误

  • INVALID_DATAHTTP 400
    • 提供的ID似乎无效 
      解决办法:请指定一个有效的字段ID。
    • 在字段标签中发现了特殊字符 
      解决办法:字段标签不支持特殊字符。
    • 无效的公式表达式 
      解决办法:请指定一个有效的公式表达式。
  • NOT_ALLOWEDHTTP 400
    • 查找模块无法更新 
      解决方法:一旦查找模块与字段关联后,就无法再进行更新。
    • 公式字段不支持更新返回类型 
      解决方法:公式字段不支持更新其返回类型。
    • 不允许设置为私有 
      解决方法:请启用隐私设置并更新私有值。
    • 不允许唯一情况
      解决方法:您尝试更新的字段不支持唯一键。
  • RESERVED_KEYWORD_NOT_ALLOWEDHTTP 400

    API名称中不允许使用系统保留关键字
    解决方法:请为API名称指定一个非系统保留的关键字。

  • DUPLICATE_DATAHTTP 400
    • 字段标签重复
      解决方案:该字段标签似乎与其他字段的标签重复。请指定唯一的字段标签。
    • 选项列表中存在重复的显示值
      解决方案:一个或多个选项列表值存在相同内容。请指定唯一的显示值。
    • 创建字段时发现重复的API名称
      解决方案:请为字段指定唯一的API名称。
    • 已发现重复的数据
      解决方案:请指定唯一的值以更新该字段。
    • "reference_value" 键的数据类型无效
      解决方案:“reference_value” 键的数据类型应为 “string”。
  • MANDATORY_NOT_FOUNDHTTP 400

    未找到必填字段
    解决方法:请指定需要更新的必填字段。参见创建自定义字段 API,了解必填字段。

  • 缺少必需的参数RAMHTTP 400

    缺少必需的参数RAM。
    解决方法: 请指定modules参数RAM及其对应的值。

  • LIMIT_EXCEEDEDHTTP 400

    在交易模块的阶段下拉字段中添加的选项过多
    解决方法:您最多可以在交易模块的阶段下拉字段中添加220个选项。

  • DEPENDENT_MISMATCHHTTP 400
    • 提供的长度值似乎无效。
      解决方法:长度属性中填写的值似乎无效。
    • 相关字段无效或缺失
      解决方法:请指定有效的相关字段及其对应的有效值。

    请参阅 创建自定义字段 API 以了解相关字段。

  • INVALID_REQUEST_METHODHTTP 400

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

  • OAUTH_SCOPE_MISMATCHHTTP 401

    未经授权
    解决方法:客户端没有更新自定义字段的有效权限。请创建一个具有所需权限的新令牌。请参考权限部分获取确切的权限。

  • Authentication_失败HTTP 401

    Authentication失败
    解决方法:在 API 调用的请求头中传递访问令牌。

  • INVALID_URL_PATTERNHTTP 404

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

  • INTERNAL_ERRORHTTP 500

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

示例回复

Copied{
    "fields": [
        {
            "code": "SUCCESS",
            "details": {
                "id": "5725767000005821005"
            },
            "message": "field updated",
            "status": "success"
        }
    ]
}