帮助中心集成

为了: 管理员

查找带有中心密钥的案例

列出您中心的所有案件(无论已打开还是已关闭),按标签 ID 或标题搜索案件,并从您自己的软件中查找案件 ID。

在本文中7 个部分

开始之前

此页面介绍了枢纽键用于查找案例的调用方式。这些路径位于https://prd-api-app.caseactive.com/v1/<hub id>之下。

电话

称呼它的作用
GET /cases列出您所在中心当前处于开放或关闭状态的案件。
GET /cases/search通过标签ID或标题来搜索案例
GET /whoami读取您所在网络节点的设置信息,比如其支持的案例类型以及相关页面配置。
GET /roles列出您的主机上的各种角色
GET /stages列出您所在枢纽的各个阶段/环节
GET /schemas正在读取您设备中的案例信息以及用户自定义字段数据。

枢纽密钥充当了您所在中心系统的虚拟助手虚拟助手 一个自动化的团队成员,负责发布欢迎信息、签到信息和公司动态;其发布的帖子带有虚拟助理徽章。的角色。每个系统中都包含这个角色,因此这些调用会传递到中心的每一个案例中。下面是两个示例案例的说明。

枢纽密钥无法创建案例:POST /cases的响应结果为403 HostCreateCaseNotEnabledException。若需通过软件来创建案例,请使用管理密钥;详情请参阅如何使用管理密钥创建和更新案例部分说明。

案例列表

范围它的作用必需的默认
status对于未解决的案例,使用1;而对于已经解决的案件,则使用0。不1
limit每页可以容纳多少个案例?最多可达1000个。不20
start_key上一页中的startKey不首页
curl "https://prd-api-app.caseactive.com/v1/ca-7e6d5c4b3a2f10/cases?status=1" \
  -H "Authorization: Bearer YOUR_API_KEY"
{
  "data": {
    "items": [
      {
        "case_id": "cc-1a2b3c4d5e6f70",
        "case_ref_id": "ca-7e6d5c4b3a2f10::rear-end-2026",
        "title": "Jane Sample auto accident",
        "team": {
          "cu-7e6d5c4b3a2f10": "role::bots",
          "cu-4f1c2a9e8b7d60": "role::clients",
          "cu-9d8c7b6a5f4e30": "role::staff"
        }
      }
    ],
    "currentItemCount": 1,
    "selfLink": "https://prd-api-app.caseactive.com/v1/ca-7e6d5c4b3a2f10/cases?status=1"
  }
}
  • 案例是按照标签ID标签 ID 您给案例赋予的永久标签,例如 rear-end-2026,也显示为参考 ID,并在导入时使用。的顺序排列的,从Z到A依次排列,而不是按照日期排序。
  • case_ref_id是您所在枢纽的ID,由两个冒号组成,后面跟着案件的标签ID。
  • team将每个涉及的人员与他们的角色角色 一组权限,用于决定某人(例如员工或客户)可以查看和处理案件的哪些内容。关联起来,此时这些人员并没有拥有姓名。如果需要获取这些人员的姓名,请参考相关团队的资料;详情请参阅如何使用中心密钥读取和更新案件详细信息。
  • 虽然仍有更多页面需要处理,但该页面还保存着nextLink,即下一页的完整地址,以及startKey。可以调用nextLink,或者将startKey作为start_key发送出去,直到找到没有这些参数的页面为止。
  • 被删除的案例不会被计入总数,因此某页面上显示的案例数量可能少于limit个,但实际上仍有一些案例存在。请以nextLink作为判断依据,而不是实际的数量。
  • 在这个系统中,案件的标题和状态信息可能会出现几秒钟的延迟。

搜索案例

GET /cases/search可以匹配案例标签ID中的任何位置出现的单词,甚至可以从标题中的单词开头开始进行匹配,同时能够容忍一些小的拼写错误。不过,该功能无法搜索描述文本中的内容。

范围它的作用必需的默认
query需要寻找的词语。每种情况都发送*。是的—
status对于未解决的案例,使用1;而对于已经解决的案件,则使用0。不1
limit每页最多可以显示多少条结果,最多可达250条。不20
page结果的哪一页?从第1页开始查找吧。不1
sort_by一个数值域和一个方向,例如created_on:desc。它需要接收created_on、date_opened、last_activity、updated_on、users_ct和case_status这些参数。不最佳对决排在最前面
curl "https://prd-api-app.caseactive.com/v1/ca-7e6d5c4b3a2f10/cases/search?query=rear-end-2026" \
  -H "Authorization: Bearer YOUR_API_KEY"
{
  "data": {
    "found": 1,
    "page": 1,
    "hits": [
      {
        "document": {
          "case_id": "cc-1a2b3c4d5e6f70",
          "ref_id": "rear-end-2026",
          "title": "Jane Sample auto accident",
          "case_status": 1,
          "case_type": "general",
          "case_stage": "stage::20260927120000_8c1f0e2d3b4a59",
          "date_opened": 1772668800,
          "created_on": 1791043509,
          "last_activity": 1791050112,
          "users_ct": 3
        }
      }
    ],
    "selfLink": "https://prd-api-app.caseactive.com/v1/ca-7e6d5c4b3a2f10/cases/search?query=rear-end-2026"
  }
}
  • 每一次命中都…… document 持有该案件的ID、简单的标签ID、案件名称、状态等信息。 案件类型案件类型 用于处理特定案例的类别,例如“一般案例”,以便将自动化流程应用于正确的案例。, 阶段/步骤阶段 案件进展过程中的一个步骤,例如受理或发出索赔请求,公司会对其进行命名和描述,并在案件页面上显示该步骤。, 该文件包含多少个人信息,以及其日期,所有内容均以UTC时间的Unix秒为单位表示。
  • 有found个案例符合要求。可以使用page来浏览这些案例;没有使用nextLink的情况。
  • 在发生某种变化后,只需几秒钟即可对案件进行检索。

通过标签 ID 查找案例

无法通过标签ID进行精确搜索。请先执行搜索,然后选择那些document.ref_id与你的标签ID完全匹配的结果,因为搜索时会找到类似rear-end-2025的近似匹配项。如果需要进行更全面的搜索,可以使用status=1、status=0等参数来涵盖开放和封闭两种情况。

一旦您获得了案件的识别码,之后所有与该案件相关的呼叫都会使用这个识别码进行识别。详情请参阅使用中心密钥读取和更新案件信息部分。

你的中心设置

称呼它回答了什么
GET /whoami该密钥的用户ID、您的中心节点的名称、其支持的案例类型、可使用的功能模块,以及host_default_schemas——即相关的案例和用户字段页面。
GET /roles每个角色都包含虚拟助理的功能role::bots,这些功能包括role_id、name、description、color和reads_notes。无论该角色是否能够读取笔记信息,所有这些功能都适用。
GET /stages每一个阶段,从开始到结束,都包含stage_id、name、description和order这些元素。
GET /schemasdefault_schemas,您的中心节点页面以及用户自定义字段页面上,都列出了各个字段的键、标签和类型。

这些页面都没有什么特别的内容:它们能同时回答所有的问题。

如果电话被拒绝

地位message为什么
400SchemaFieldsException某个参数缺失或无效,例如 query 为空,或者 status 的值不是 0 或 1;还有 errors 的名称也出现了问题。
400InvalidStartKeyExceptionstart_key来自另一个列表。
400SearchParameterException搜索功能拒绝接受某些参数,例如文本字段中的sort_by,或者大于250的limit参数;而reason参数则用于指定其他内容。
403HostCreateCaseNotEnabledException一个中心节点试图创建一个案例。

关于错误 bodies 以及其他代码格式,请参考 处理 API 错误和状态代码 的相关说明。

相关文章

了解 API 的功能了解管理密钥和中心密钥各自的权限范围,为什么每个密钥都充当虚拟助手,以及完整的技术清单在哪里。集成使用中心密钥读取和更新案件详情阅读案件详情和团队信息,并更改管理员允许虚拟助理角色更改的详情,例如阶段或自定义字段。集成使用管理密钥创建和更新案例使用您自己的软件列出、创建、读取、更新和删除您中心的案例,包括其阶段和自定义字段。集成处理 API 错误和状态码阅读错误正文,了解 400、401、403、404、500 和 503 的含义,以及为什么您的密钥无法查看的项目会返回 404。集成