Zoho crm Logo

相关记录数据

Zoho CRM 中的一条记录可以拥有相关数据,例如备注、附件、产品、交易和联系人。使用 关联记录 API(Related Records API),你可以获取与特定模块记录相关的所有关联记录。

获取相关记录

目的

获取相关列表记录。

端点

  • GET /{module_api_name}/{record_id}/{related_list_api_name}
  • {module_api_name} :要从中获取相关记录的模块 API 名称。例如,线索(Leads)、Account、联系人(Contacts) 等。 
  • {record_id}:指定模块中记录的唯一 ID。
  • {related_list_api_name} :要检索的相关列表的 API 名称。例如,Notes、Attachments、Emails 等。相关列表元数据 API 响应中的 href 属性提供了获取相关记录的精确端点。

请求详情

请求 URL

{api-domain}/crm/{version}/{module_api_name}/{record_id}/{related_list_api_name}

支持的关联

支持所有模块及其相关记录。使用相关列表元数据 API获取某个模块可用的相关列表。相关列表元数据 API 的响应中的 href 属性提供了用于获取相关记录的精确端点。

标题

Authorization: Zoho-oauthtoken d92d4xxxxxxxxxxxxx15f52
If-Modified-Since: 使用此标头获取最近修改的记录列表。示例:2019-07-25T15:26:49+05:30

范围

scope=ZohoCRM.modules.ALL
(或)
scope=ZohoCRM.modules.{module_API_name}.{operation_type}

可能的模块名称

线索、账户、联系人、交易、活动、任务、服务单、事件、通话、解决方案、产品、供应商、价格表、报价、销售订单、采购订单、发票、自定义、预约、预约改期历史和服务。

可能的操作类型

ALL - 完全访问相关记录
READ - 读取相关记录

参数

  • 字段字符串,必填

    指定要在响应中接收其详细信息的字段的 API 名称。使用 GET - 字段元数据 API 来检索模块中可用字段的列表。

  • page整数,可选

    用于从相应的页面获取记录列表。page 的默认值为 1。
    可能的取值:仅限正整数。

  • per_page整数,可选

    获取每页可用的记录列表。默认值和最大可能值为200。
    可选值:仅限正整数值。

  • page_token字符串,进行分页以获取超过 2000 条记录时必填

    在不使用 page_token 的情况下,你可以使用 page 参数来获取最多 2000 条记录。若要获取超过 2000 条记录,必须在请求中包含 page_token 参数。此参数取值自第一次调用“获取关联记录”(Get Related Records)接口返回结果中的 next_page_token 键。请注意,该 token 值是与用户绑定的。如果你使用了其他用户的 token,系统会报错。
    请注意,不能同时在请求中使用此参数和 page 参数。

  • ids字符串,可选

    根据记录的唯一 ID 获取特定记录。使用 GET - Records API 来获取模块中有效的记录 ID。
    可能的取值:记录的有效唯一 ID。示例:4150868000001944196

  • sort_order字符串,可选

    用于将可用的记录列表按升序或降序排序。

    可能的取值: 

    • desc (默认)- 降序。
    • asc - 升序
  • sort_by字符串,可选

    根据字段 id、Created_Time 和 Modified_Time 对记录进行排序。默认值为 id。请注意,不能将此参数与 cvid 参数一起使用。

  • converted字符串,可选

    获取已转换记录的列表。 
    可能的取值: 

    • false(默认)- 仅获取未转换的记录
    • true - 仅获取已转换的记录
    • both - 获取所有记录。

注意

  • page 和 per_page 参数用于根据记录在 CRM 中的位置来获取记录。假设用户需要获取 400 条记录。单次 API 调用可获取的最大记录数为 200 条。因此,超过第 200 条位置的记录无法一次性获取。通过使用 page(1 和 2) 和 per_page(200) 参数,用户可以通过 2 次 API 调用获取全部 400 条记录。
  • 如果请求的相关列表在布局中不存在或被隐藏,系统将返回 INVALID_DATA 响应。

示例请求

Copied```bash
curl "https://www.zohoapis.com/crm/v8/Leads/4876876000000376008/Notes?fields=Owner,Parent_Id"
-X GET
-H "Authorization: Zoho-oauthtoken 1000.8cb99dxxxxxxxxxxxxx9be93.9b8xxxxxxxxxxxxxxxf"
```
Copiedresponse = invokeurl
[
	url: "https://www.zohoapis.com/crm/v8/Leads/4876876000000376008/Notes?fields=Owner,Parent_Id"
	type: GET
	connection:"crm_oauth_connection"
];
info response;

响应 JSON 键

  • 所有者JSON 对象

    表示记录所有者的姓名、ID 和电子邮件。

  • Modified_Timestring

    关联记录上次被修改的日期和时间。

  • Created_Timestring

    相关记录创建的日期和时间。

  • $editableboolean

    表示用户是否可以编辑当前关联记录。

    可能的取值:

    • true: 用户可以编辑当前关联记录。
    • false: 用户不能编辑当前关联记录。
  • Modified_ByJSON 对象

    包含最后修改相关记录的用户的姓名、ID 和电子邮件。

  • idstring

    表示相关记录的唯一ID。

  • Created_ByJSON 对象

    表示创建相关记录的用户的姓名、ID 和电子邮件。

注意

  • 上面列出的键适用于所有相关记录。除了上述键之外,响应中还会返回与相关记录特定的键。
  • 对于包含敏感健康数据的字段,只有在合规设置中禁用通过 API 限制数据访问选项时,才会返回其值。如果启用了该选项,则 HIPAA 合规字段的值将为 null。有关更多详细信息,请参阅HIPAA 合规性。

示例回复

Copied{
    "data": [
        {
            "Owner": {
                "name": "Patricia Boyle",
                "id": "4876876000000327001",
                "email": "patricia.boyle@zohocorp.com"
            },
            "Parent_Id": {
                "name": "Brian Dylan",
                "id": "4876876000000376008"
            },
            "id": "4876876000001017003"
        }
    ],
    "info": {
        "per_page": 200,
        "next_page_token": null,
        "count": 1,
        "page": 1,
        "previous_page_token": null,
        "page_token_expiry": null,
        "more_records": false
    }
}

与 Activities_Chronological_View 相关列表的响应 JSON

Activities_Chronological_View 相关列表按时间顺序排列,提供记录的未完成活动(电话、任务和会议)的详细信息。

在 API 响应中,$module 键用于标识每条相关记录的模块类型(电话、任务或会议),并且所有请求的字段都会包含在响应中。

按时间顺序获取未完成活动的示例请求

Copied```bash
curl "https://www.zohoapis.com/crm/v8/Leads/Leads/554023000003136003/Activities_Chronological_View?fields=Call_Start_Time"
-X GET
-H "Authorization: Zoho-oauthtoken 1000.8cb99dxxxxxxxxxxxxx9be93.9b8xxxxxxxxxxxxxxxf"
```

示例回答

Copied{
    "data": [
        {
            "Call_Start_Time": "2023-06-25T20:00:00-11:00",
            "id": "554023000003136019",
            "$module": "通话"
        }
    ],
    "info": {
        "per_page": 200,
        "next_page_token": null,
        "count": 1,
        "page": 1,
        "previous_page_token": null,
        "more_records": false
    }
}

与 Activities_Chronological_View_History 相关列表的响应JSON

Activities_Chronological_View_History 相关列表按时间顺序为您提供该记录的已关闭活动(电话、任务、会议)的详细信息。

在 API 响应中,$module 键用于标识每条相关记录的模块类型(电话、任务或会议),并且所有请求的字段都会包含在响应中。

可能的错误

  • INVALID_MODULEHTTP 400

    提供的模块名称似乎无效
    解决方案: 您指定了无效的模块名称,或者没有选项卡权限,或者该模块已从可用模块中移除。请指定一个有效的模块 API 名称。

  • NOT_SUPPORTED HTTP 400

    给定的模块在 API 中不受支持
    解决方法:诸如 Documents 和 Projects 等模块在当前 API 中不受支持。(一旦这些模块获得支持,此错误将不再显示)。请指定一个有效的模块 API 名称。

  • INVALID_URL_PATTERNHTTP 404

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

  • OAUTH_SCOPE_MISMATCHHTTP 401

    未授权
    解决方法:客户端没有 ZohoCRM.modules.{module_name}.READ 作用域。请创建具有有效作用域的新客户端。请参考上文的作用域部分。

  • NO_PERMISSIONHTTP 403

    无权读取相关记录
    解决方法:用户没有读取相关记录数据的权限。请联系系统管理员。

  • INTERNAL_ERRORHTTP 500

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

  • INVALID_REQUEST_METHODHTTP 400

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

  • AUTHORIZATION_FAILEDHTTP 400

    用户没有足够的权限读取相关记录数据
    解决方案:用户没有读取相关记录数据的权限。请联系系统管理员。

  • REQUIRED_PARAM_MISSINGHTTP 400

    缺少一个预期的参数
    解决方法:请指定必填参数。有关更多详细信息,请参阅上面的参数部分。

按时间顺序获取已关闭活动的示例请求

Copied```bash
curl "https://www.zohoapis.com/crm/v8/Leads/554023000003136003/Activities_Chronological_View_History?fields=Status,Call_Start_Time,Owner,Status,Subject"
-X GET
-H "Authorization: Zoho-oauthtoken 1000.8cb99dxxxxxxxxxxxxx9be93.9b8xxxxxxxxxxxxxxxf"
```

示例回复

Copied{
    "data": [
        {
            "Status": "已完成",
            "id": "554023000003140004",
            "$module": "任务",
            "Subject": "跟进"
        }
    ],
    "info": {
        "per_page": 200,
        "next_page_token": null,
        "count": 1,
        "page": 1,
        "previous_page_token": null,
        "more_records": false
    }
}