Zoho crm Logo

记录时间轴

目的

要获取记录的时间轴。响应会提供记录的历史,包括对其任何字段和相关记录所做的所有更新。

端点

  • GET /{module_API_name}/{record_ID}/__timeline

请求详情

请求URL

{api-domain}/crm/{version}/{module_API_name}/{record_ID}/__timeline

支持的模块

潜在客户、联系人、账户、交易、任务、会议、电话、产品、服务、预约、采购订单、销售订单、报价、发票、备注、自定义

标题

授权:Zoho-oauthtoken d92d4xxxxxxxxxxxxx15f52

范围

scope=ZohoCRM.modules.{module_name}.ALL
(或)
scope=ZohoCRM.modules.{module_name}.READ

参数

  • per_page 整数,可选

    您想要每页获取的记录数。此参数仅可用于首页。对于后续页面,必须使用 “page_token” 参数。

  • page_token 字符串,必填

    在进行分页并检索了 200 条记录后,指定 "next_page_token" 或 "previous_page_token"。请注意,如果请求中提供了 "page_token",则不能再提供 "per_page" 参数。

  • include_timeline_type 字符串,可选

    用于在 "timeline" 对象中包含额外类型。通过此参数,可以获取与信号相关的 "signals" 数据,从而获得与信号有关的时间线条目。

  • 包含字符串,在指定 "include_timeline_type" 参数时为必填项

    如果您希望通过信号或其他方式查看记录更新的详细信息,请使用此参数。可能的取值有 extension 和 type。例如,如果记录是通过信号进行更新的,则响应中会包含扩展部分的详细信息,如电子邮件分析(email insights),而更新类型为信号(signals)。

  • include_inner_details 字符串, 可选

    如果您希望在响应的 "field_history" 对象中获取记录更新的额外详细信息,请使用此参数。可用值有 field_history.data_type, field_history.field_label, field_history.enable_colour_code, field_history.pick_list_values, done_by.type__s, done_by.profile。

    • field_history.data_type - 提供已更新字段的数据类型的详细信息。
    • field_history.field_label - 提供已更新字段标签的详细信息。
    • field_history.pick_list_values - 表示选项列表可用的值。
    • field_history.enable_colour_code - 表示该选项值是否启用了颜色编码。
    • done_by.profile - 提供更新该记录的用户资料的详细信息。
    • done_by.type__s - 提供修改该记录的用户类型信息,如门户用户或普通用户。
  • 过滤器 JSON 对象 (已编码),可选

    filters 参数用于根据特定条件过滤来自时间线 API 的响应。该参数包含三个组成部分,分别是 field(字段)、comparator(比较符)和 value(值),它们共同构成过滤时间线数据的条件。

    该字段的 api_name 键可能的取值为 - record.module.api_name、source、audited_time 和 done_by.id。

    • record.module.api_name:您可以使用此参数筛选记录的备注、附件、任务、电话、活动和邮件的时间轴详情。

      允许的比较符有 equal、in。允许的取值有 Notes(备注)、Attachments(附件)、Tasks(任务)、Calls(电话)、Events(活动)、Emails(邮件)。

      例如:

      筛选备注:

      {"field":{"api_name":"record.module.api_name"},"comparator":"equal","value":"Notes"}

      筛选备注和任务:

      {"field":{"api_name":"record.module.api_name"},"comparator":"in","value":["Notes","Tasks"]}

    • done_by.id:您可以按特定用户筛选时间线详情。支持的比较符有equal(等于)、in(属于)。允许的取值为用户ID。

      例如,按某个用户ID筛选时间线详情:

      {"field":{"api_name":"done_by.id"},"comparator":"in","value":["5843104000000424001"]}

    • audited_time:您可以根据审核时间筛选时间线数据。允许的比较符是 between(介于)。允许的取值为 ISO 8601 格式的时间。例如,要筛选两个日期之间的时间线详情:{"field":{"api_name":"audited_time"},"comparator":"between","value":["2023-10-25T00:00:00+12:00","2023-10-30T23:59:59+12:00"]}
    • source:您可以根据来源筛选时间线数据。允许的比较符有 equal,in。允许的取值包括:crm_api、mass_delete_via_crm_api、bulkapi、approval_process、assignment_rules、blueprint、mass_update_via_blueprint、orchestration、convert、massconvert、custom_function、macro、crm_ui、mass_update、mass_update_via_scheduler、mass_delete_via_clean_up、bulk_action、change_owner、mass_change_owner_via_scheduler、review_process、scoringrule、wizard、workflow。

      例如,要根据来源筛选时间线详情:

      {"field":{"api_name":"source"},"comparator":"equal","value":"crm_ui"}
      {"field":{"api_name":"source"},"comparator":"in","value":["crm_api","crm_ui"]}

    您可以使用group_operator和group来组合多个条件。

    {"group_operator":"AND","group":[{"field":{"api_name":"record.module.api_name"},"comparator":"in","value":["备注"]},{"field":{"api_name":"source"},"comparator":"in","value":["crm界面","crm接口"]}]}

    您还可以参考示例请求以了解结构。请注意,您必须对该参数的值进行编码。

    在示例请求中,filters={"comparator":"between","field":{"api_name":"audited_time"},"value":["2023-06-07T00:00:00+05:30","2023-06-07T12:59:59+05:30"]} 被编码为 filters=%7B%22comparator%22%3A%22between%22%2C%22field%22%3A%7B%22api_name%22%3A%22audited_time%22%7D%2C%22value%22%3A%5B%222023-06-07T00%3A00%3A00%2B05%3A30%22%2C%222023-06-07T12%3A59%3A59%2B05%3A30%22%5D%7D

    您可以在我们的URL 编码/解码工具中使用“编码 URL/解码 URL”选项对该值进行编码。

示例请求

Copiedcurl "https://www.zohoapis.com/crm/v8/Leads/554023000001122039/__timeline?sort_by=audited_time&include_inner_details=field_history.data_type, field_history.field_label, field_history.enable_colour_code, field_history.pick_list_values, done_by.type__s, done_by.profile&filters=%7B%22comparator%22%3A%22between%22%2C%22field%22%3A%7B%22api_name%22%3A%22audited_time%22%7D%2C%22value%22%3A%5B%222023-06-07T00%3A00%3A00%2B05%3A30%22%2C%222023-06-07T12%3A59%3A59%2B05%3A30%22%5D%7D"
-X GET
-H "Authorization: Zoho-oauthtoken 1000.8cb99dxxxxxxxxxxxxx9be93.9b8xxxxxxxxxxxxxxxf"

响应 JSON

  • done_by

    修改该记录的用户的详细信息,例如姓名、ID、该用户所属角色的名称和ID,以及用户类型。

  • related_record

    任务、电话或会议所属的父记录名称和ID。

  • automation_details

    表示该记录是通过自动化操作(如工作流)修改的。

  • 记录

    为父级记录创建的任务、呼叫或会议的名称和 ID。

  • audited_time

    记录被更新的日期和时间。

  • 操作

    在记录上发生的操作。一些可能的取值包括“已添加”、“已更新”、“所有者已分配”、“任务已分配”、“关联列表已添加”等。

  • id

    时间轴上该操作的唯一ID。

  • 来源

    表示记录是从哪里被更新的。可能的取值包括 "crm_ui"、"migration"、"mass_update"、"mass_addition_via_ui"、"crm_api"、"workflow" 等。

  • field_history

    包含以下详细信息。

    • api_name - 被修改字段的 API 名称。该字段默认会出现在响应中。
    • _value - 该字段的旧值和新值。该字段默认会出现在响应中。
    • 当你指定 include_inner_details 参数时,响应中会包含以下值:
      • enable_colour_code - 表示是否为选项列表字段启用了颜色编码。
      • data_type - 被修改字段的数据类型。
      • pick_list_values - 选项列表中各值的详细信息。

可能的错误

  • NO_CONTENTHTTP 204

    数据不可用或所应用的筛选条件下没有时间线。
    解决方法:请修改筛选条件后重试。

  • INVALID_DATAHTTP 400

    原因:

    • 您在“filters”参数中使用了不允许的比较符。
    • 您未对filters参数的值进行编码。
    • 请求URL中的记录ID无效。

    解决方法:

    • 请参考“参数”部分中的“filters”参数,查找允许的比较符和字段。
    • 请指定有效的记录ID。参考获取记录 API获取记录ID。
  • AMBIGUITY_DURING_PROCESSINGHTTP 400

    您同时指定了“per_page”和“page_token”参数。
    解决方法:导航时只能使用“page_token”参数。

  • OAUTH_SCOPE_MISMATCH HTTP 401

    您没有权限访问此API所需的Scope。
    解决方法:请根据“Scopes”部分提到的Scope新建Token并重试此API。

  • INTERNAL_SERVER_ERROR HTTP 500

    服务器出现未处理或意外异常。
    解决方法:请联系support@zohocrm.com寻求帮助。

示例响应

Copied{
    "__timeline": [
        {
            "done_by": {
                "profile": {
                    "name": "Administrator",
                    "id": "554023000000015972"
                },
                "name": "Patricia Boyle",
                "id": "554023000000235011",
                "type__s": "regular user"
            },
            "related_record": null,
            "automation_details": null,
            "record": {
                "module": {
                    "api_name": "Leads",
                    "id": "554023000000000125"
                },
                "name": "Patricia Boyle",
                "id": "554023000001122039"
            },
            "audited_time": "2023-06-07T19:32:21-11:00",
            "action": "tag_added",
            "id": "554023000003097009",
            "source": "mass_update",
            "field_history": [
                {
                    "api_name": "Tag",
                    "field_label": "Tag",
                    "enable_colour_code": false,
                    "data_type": "text",
                    "_value": {
                        "new": "Prime",
                        "old": "blank"
                    },
                    "id": "554023000000138025",
                    "pick_list_values": []
                }
            ]
        },
        {
            "done_by": {
                "profile": {
                    "name": "Administrator",
                    "id": "554023000000015972"
                },
                "name": "Patricia Boyle",
                "id": "554023000000235011",
                "type__s": "regular user"
            },
            "related_record": null,
            "automation_details": null,
            "record": {
                "module": {
                    "api_name": "Leads",
                    "id": "554023000000000125"
                },
                "name": "Patricia Boyle",
                "id": "554023000001122039"
            },
            "audited_time": "2023-06-07T18:58:36-11:00",
            "action": "updated",
            "id": "554023000003097006",
            "source": "crm_ui",
            "field_history": [
                {
                    "api_name": "Phone",
                    "field_label": "Phone",
                    "enable_colour_code": false,
                    "data_type": "phone",
                    "_value": {
                        "new": "1234567",
                        "old": null
                    },
                    "id": "554023000000000565",
                    "pick_list_values": []
                }
            ]
        },
        {
            "done_by": {
                "profile": {
                    "name": "Administrator",
                    "id": "554023000000015972"
                },
                "name": "Patricia Boyle",
                "id": "554023000000235011",
                "type__s": "regular user"
            },
            "related_record": null,
            "automation_details": null,
            "record": {
                "module": {
                    "api_name": "Leads",
                    "id": "554023000000000125"
                },
                "name": "Patricia Boyle",
                "id": "554023000001122039"
            },
            "audited_time": "2023-06-07T18:17:54-11:00",
            "action": "updated",
            "id": "554023000003095054",
            "source": "crm_ui",
            "field_history": [
                {
                    "api_name": "Last_Name",
                    "field_label": "Last Name",
                    "enable_colour_code": false,
                    "data_type": "text",
                    "_value": {
                        "new": "Boyle",
                        "old": "Smith"
                    },
                    "id": "554023000000000559",
                    "pick_list_values": []
                },
                {
                    "api_name": "First_Name",
                    "field_label": "First Name",
                    "enable_colour_code": false,
                    "data_type": "text",
                    "_value": {
                        "new": "Patricia",
                        "old": null
                    },
                    "id": "554023000000000557",
                    "pick_list_values": []
                },
                {
                    "api_name": "Full_Name",
                    "field_label": "Full Name",
                    "enable_colour_code": false,
                    "data_type": "text",
                    "_value": {
                        "new": "Patricia Boyle",
                        "old": "Smith"
                    },
                    "id": "554023000000000597",
                    "pick_list_values": []
                }
            ]
        },
        {
            "done_by": {
                "profile": {
                    "name": "Administrator",
                    "id": "554023000000015972"
                },
                "name": "Patricia Boyle",
                "id": "554023000000235011",
                "type__s": "regular user"
            },
            "related_record": null,
            "automation_details": null,
            "record": {
                "module": {
                    "api_name": "Leads",
                    "id": "554023000000000125"
                },
                "name": " Smith",
                "id": "554023000001122039"
            },
            "audited_time": "2023-06-07T18:17:19-11:00",
            "action": "updated",
            "id": "554023000003095048",
            "source": "crm_ui",
            "field_history": [
                {
                    "api_name": "Company",
                    "field_label": "Company",
                    "enable_colour_code": false,
                    "data_type": "text",
                    "_value": {
                        "new": "ABC",
                        "old": "Zylker"
                    },
                    "id": "554023000000000555",
                    "pick_list_values": []
                }
            ]
        },
        {
            "done_by": {
                "profile": {
                    "name": "Administrator",
                    "id": "554023000000015972"
                },
                "name": "Patricia Boyle",
                "id": "554023000000235011",
                "type__s": "regular user"
            },
            "related_record": null,
            "automation_details": null,
            "record": {
                "module": {
                    "api_name": "Leads",
                    "id": "554023000000000125"
                },
                "name": " Smith",
                "id": "554023000001122039"
            },
            "audited_time": "2023-06-07T18:12:11-11:00",
            "action": "updated",
            "id": "554023000003095038",
            "source": "crm_api",
            "field_history": [
                {
                    "api_name": "Lead_Source",
                    "field_label": "Lead Source",
                    "enable_colour_code": false,
                    "data_type": "picklist",
                    "_value": {
                        "new": "Cold Call",
                        "old": "Employee Referral"
                    },
                    "id": "554023000000000573",
                    "pick_list_values": [
                        {
                            "display_value": "-None-",
                            "sequence_number": 1,
                            "colour_code": null,
                            "actual_value": "-None-",
                            "id": "554023000000002313",
                            "type": "used"
                        },
                        {
                            "display_value": "Advertisement",
                            "sequence_number": 2,
                            "colour_code": null,
                            "actual_value": "Advertisement",
                            "id": "554023000000002315",
                            "type": "used"
                        },
                        {
                            "display_value": "Chat",
                            "sequence_number": 28,
                            "colour_code": null,
                            "actual_value": "Chat",
                            "id": "554023000000040001",
                            "type": "used"
                        },
                        {
                            "display_value": "Cold Call",
                            "sequence_number": 6,
                            "colour_code": null,
                            "actual_value": "Cold Call",
                            "id": "554023000000002317",
                            "type": "used"
                        },
                        {
                            "display_value": "Employee Referral",
                            "sequence_number": 8,
                            "colour_code": null,
                            "actual_value": "Employee Referral",
                            "id": "554023000000002319",
                            "type": "used"
                        },
                        {
                            "display_value": "External Referral",
                            "sequence_number": 9,
                            "colour_code": null,
                            "actual_value": "External Referral",
                            "id": "554023000000002321",
                            "type": "used"
                        },
                        {
                            "display_value": "Facebook",
                            "sequence_number": 15,
                            "colour_code": null,
                            "actual_value": "Facebook",
                            "id": "554023000001157033",
                            "type": "used"
                        },
                        {
                            "display_value": "Internal Seminar",
                            "sequence_number": 22,
                            "colour_code": null,
                            "actual_value": "Seminar-Internal",
                            "id": "554023000000172093",
                            "type": "used"
                        },
                        {
                            "display_value": "Online Store",
                            "sequence_number": 14,
                            "colour_code": null,
                            "actual_value": "OnlineStore",
                            "id": "554023000000172095",
                            "type": "used"
                        },
                        {
                            "display_value": "Partner",
                            "sequence_number": 18,
                            "colour_code": null,
                            "actual_value": "Partner",
                            "id": "554023000000002323",
                            "type": "used"
                        },
                        {
                            "display_value": "Public Relations",
                            "sequence_number": 19,
                            "colour_code": null,
                            "actual_value": "Public Relations",
                            "id": "554023000000002325",
                            "type": "used"
                        },
                        {
                            "display_value": "Sales Email Alias",
                            "sequence_number": 20,
                            "colour_code": null,
                            "actual_value": "Sales Mail Alias",
                            "id": "554023000000172089",
                            "type": "used"
                        },
                        {
                            "display_value": "Seminar Partner",
                            "sequence_number": 21,
                            "colour_code": null,
                            "actual_value": "Seminar Partner",
                            "id": "554023000000172091",
                            "type": "used"
                        },
                        {
                            "display_value": "Trade Show",
                            "sequence_number": 25,
                            "colour_code": null,
                            "actual_value": "Trade Show",
                            "id": "554023000000002327",
                            "type": "used"
                        },
                        {
                            "display_value": "Twitter",
                            "sequence_number": 16,
                            "colour_code": null,
                            "actual_value": "Twitter",
                            "id": "554023000001157037",
                            "type": "used"
                        },
                        {
                            "display_value": "Web Download",
                            "sequence_number": 26,
                            "colour_code": null,
                            "actual_value": "Web Download",
                            "id": "554023000000172085",
                            "type": "used"
                        },
                        {
                            "display_value": "Web Research",
                            "sequence_number": 27,
                            "colour_code": null,
                            "actual_value": "Web Research",
                            "id": "554023000000172087",
                            "type": "used"
                        }
                    ]
                }
            ]
        },
        {
            "done_by": {
                "profile": {
                    "name": "Administrator",
                    "id": "554023000000015972"
                },
                "name": "Patricia Boyle",
                "id": "554023000000235011",
                "type__s": "regular user"
            },
            "related_record": {
                "module": {
                    "api_name": "Leads",
                    "id": "554023000000000125"
                },
                "name": "Smith",
                "id": "554023000001122039"
            },
            "automation_details": null,
            "record": {
                "module": {
                    "api_name": "Tasks",
                    "id": "554023000000000143"
                },
                "name": "test task",
                "id": "554023000003095019"
            },
            "audited_time": "2023-06-07T18:10:47-11:00",
            "action": "added",
            "id": "554023000003095029",
            "source": "crm_ui",
            "field_history": null
        },
        {
            "done_by": {
                "profile": {
                    "name": "Administrator",
                    "id": "554023000000015972"
                },
                "name": "Patricia Boyle",
                "id": "554023000000235011",
                "type__s": "regular user"
            },
            "related_record": {
                "module": {
                    "api_name": "Leads",
                    "id": "554023000000000125"
                },
                "name": "Smith",
                "id": "554023000001122039"
            },
            "automation_details": null,
            "record": {
                "module": {
                    "api_name": "Notes",
                    "id": "554023000000000147"
                },
                "name": "This is a test note",
                "id": "554023000003096003"
            },
            "audited_time": "2023-06-07T18:10:29-11:00",
            "action": "added",
            "id": "554023000003096001",
            "source": "crm_ui",
            "field_history": null
        },
        {
            "done_by": {
                "profile": {
                    "name": "Administrator",
                    "id": "554023000000015972"
                },
                "name": "Patricia Boyle",
                "id": "554023000000235011",
                "type__s": "regular user"
            },
            "related_record": null,
            "automation_details": null,
            "record": {
                "module": {
                    "api_name": "Leads",
                    "id": "554023000000000125"
                },
                "name": " Smith",
                "id": "554023000001122039"
            },
            "audited_time": "2023-06-07T18:09:49-11:00",
            "action": "updated",
            "id": "554023000003095017",
            "source": "crm_ui",
            "field_history": [
                {
                    "api_name": "Lead_Source",
                    "field_label": "Lead Source",
                    "enable_colour_code": false,
                    "data_type": "picklist",
                    "_value": {
                        "new": "Employee Referral",
                        "old": null
                    },
                    "id": "554023000000000573",
                    "pick_list_values": [
                        {
                            "display_value": "-None-",
                            "sequence_number": 1,
                            "colour_code": null,
                            "actual_value": "-None-",
                            "id": "554023000000002313",
                            "type": "used"
                        },
                        {
                            "display_value": "Advertisement",
                            "sequence_number": 2,
                            "colour_code": null,
                            "actual_value": "Advertisement",
                            "id": "554023000000002315",
                            "type": "used"
                        },
                        {
                            "display_value": "Chat",
                            "sequence_number": 28,
                            "colour_code": null,
                            "actual_value": "Chat",
                            "id": "554023000000040001",
                            "type": "used"
                        },
                        {
                            "display_value": "Cold Call",
                            "sequence_number": 6,
                            "colour_code": null,
                            "actual_value": "Cold Call",
                            "id": "554023000000002317",
                            "type": "used"
                        },
                        {
                            "display_value": "Employee Referral",
                            "sequence_number": 8,
                            "colour_code": null,
                            "actual_value": "Employee Referral",
                            "id": "554023000000002319",
                            "type": "used"
                        },
                        {
                            "display_value": "External Referral",
                            "sequence_number": 9,
                            "colour_code": null,
                            "actual_value": "External Referral",
                            "id": "554023000000002321",
                            "type": "used"
                        },
                        {
                            "display_value": "Facebook",
                            "sequence_number": 15,
                            "colour_code": null,
                            "actual_value": "Facebook",
                            "id": "554023000001157033",
                            "type": "used"
                        },
                        {
                            "display_value": "Internal Seminar",
                            "sequence_number": 22,
                            "colour_code": null,
                            "actual_value": "Seminar-Internal",
                            "id": "554023000000172093",
                            "type": "used"
                        },
                        {
                            "display_value": "Online Store",
                            "sequence_number": 14,
                            "colour_code": null,
                            "actual_value": "OnlineStore",
                            "id": "554023000000172095",
                            "type": "used"
                        },
                        {
                            "display_value": "Partner",
                            "sequence_number": 18,
                            "colour_code": null,
                            "actual_value": "Partner",
                            "id": "554023000000002323",
                            "type": "used"
                        },
                        {
                            "display_value": "Public Relations",
                            "sequence_number": 19,
                            "colour_code": null,
                            "actual_value": "Public Relations",
                            "id": "554023000000002325",
                            "type": "used"
                        },
                        {
                            "display_value": "Sales Email Alias",
                            "sequence_number": 20,
                            "colour_code": null,
                            "actual_value": "Sales Mail Alias",
                            "id": "554023000000172089",
                            "type": "used"
                        },
                        {
                            "display_value": "Seminar Partner",
                            "sequence_number": 21,
                            "colour_code": null,
                            "actual_value": "Seminar Partner",
                            "id": "554023000000172091",
                            "type": "used"
                        },
                        {
                            "display_value": "Trade Show",
                            "sequence_number": 25,
                            "colour_code": null,
                            "actual_value": "Trade Show",
                            "id": "554023000000002327",
                            "type": "used"
                        },
                        {
                            "display_value": "Twitter",
                            "sequence_number": 16,
                            "colour_code": null,
                            "actual_value": "Twitter",
                            "id": "554023000001157037",
                            "type": "used"
                        },
                        {
                            "display_value": "Web Download",
                            "sequence_number": 26,
                            "colour_code": null,
                            "actual_value": "Web Download",
                            "id": "554023000000172085",
                            "type": "used"
                        },
                        {
                            "display_value": "Web Research",
                            "sequence_number": 27,
                            "colour_code": null,
                            "actual_value": "Web Research",
                            "id": "554023000000172087",
                            "type": "used"
                        }
                    ]
                }
            ]
        }
    ],
    "info": {
        "per_page": 200,
        "next_page_token": null,
        "count": 10,
        "page": 1,
        "previous_page_token": null,
        "more_records": false
    }
}