为了: 管理员
查找带有中心密钥的案例
列出您中心的所有案件(无论已打开还是已关闭),按标签 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 /schemas | default_schemas,您的中心节点页面以及用户自定义字段页面上,都列出了各个字段的键、标签和类型。 |
这些页面都没有什么特别的内容:它们能同时回答所有的问题。
如果电话被拒绝
| 地位 | message | 为什么 |
|---|---|---|
| 400 | SchemaFieldsException | 某个参数缺失或无效,例如 query 为空,或者 status 的值不是 0 或 1;还有 errors 的名称也出现了问题。 |
| 400 | InvalidStartKeyException | start_key来自另一个列表。 |
| 400 | SearchParameterException | 搜索功能拒绝接受某些参数,例如文本字段中的sort_by,或者大于250的limit参数;而reason参数则用于指定其他内容。 |
| 403 | HostCreateCaseNotEnabledException | 一个中心节点试图创建一个案例。 |
关于错误 bodies 以及其他代码格式,请参考 处理 API 错误和状态代码 的相关说明。