Zoho crm Logo

使用外部 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"
        }
    ]
}