Skip to main content

案例检索 API

查找类案,获取案例信息、高亮内容和分页结果

可按案情描述、案号或关键词检索裁判文书,支持语义检索。用量按搜索意图计量。调用前请完成接入认证。

适用场景

  • 类案比对:按案情描述查找裁判思路相近的案例,用于支撑主张。例如:「员工离职后使用原单位客户名单,法院一般怎么认定?」
  • 裁判要旨提取:定位法院对争议焦点的认定,提炼可引用的要旨。例如:「这批建设工程款纠纷里,法院对签证单效力的认定要点是什么?」
  • 诉讼策略参考:汇总同类案件的裁判倾向与关键证据组织方式。例如:「同类商标侵权案子,原告一般靠哪些证据赢?」
  • 文书引用准备:获取案例出处与原文段落,供文书引用。例如:「把这个案例的案号和裁判理由原文段落给我,要写进代理意见。」引用前请核对来源。
使用说明案例检索结果可辅助法律研究和文书准备。引用案例编号、裁判日期和原文段落前,请核对来源内容。

接入信息

使用下表中的完整请求地址发起调用。API Key 的创建与管理见接入认证。
配置项配置值
服务名称案例检索 API
正式环境基础地址https://farui.cn-beijing.aliyuncs.com
请求路径/open/v1/case/search
正式环境请求地址(完整 URL)https://farui.cn-beijing.aliyuncs.com/open/v1/case/search
请求方法POST
请求格式Content-Type: application/json
认证方式Authorization 填写个人 API Key 原文,同时携带当前 x-acs-date,详见下方请求头

请求

请求头

请求头填写说明
Authorization必填,填写 API Key 原文,省略 Bearer 前缀
x-acs-date必填,填写发起请求时的 UTC 时间,使用 ISO 8601 格式,精确到秒并以 Z 结尾,每次请求重新生成
x-acs-version必填,填写 2026-10-19
Content-TypeJSON 请求体使用 application/json

curl 请求示例

将个人 API Key 原文保存到环境变量 FARUI_API_KEY。服务基础地址见服务地址。x-acs-date 在每次执行命令时重新生成。 简易的请求示例
FARUI_API_BASE_URL='https://farui.cn-beijing.aliyuncs.com'

curl --request POST \
  --url "${FARUI_API_BASE_URL%/}/open/v1/case/search" \
  --header "Authorization: ${FARUI_API_KEY}" \
  --header "x-acs-date: $(date -u '+%Y-%m-%dT%H:%M:%SZ')" \
  --header 'x-acs-version: 2026-10-19' \
  --header 'Content-Type: application/json' \
  --data '{
  "query": "劳动争议",
  "searchId": "case-search-001",
  "pageParam": {
    "pageNumber": 1,
    "pageSize": 10
  }
}'
复杂的请求示例(过滤字段是and关系)
FARUI_API_BASE_URL='https://farui.cn-beijing.aliyuncs.com'

curl --request POST \
  --url "${FARUI_API_BASE_URL%/}/open/v1/case/search" \
  --header "Authorization: ${FARUI_API_KEY}" \
  --header "x-acs-date: $(date -u '+%Y-%m-%dT%H:%M:%SZ')" \
  --header 'x-acs-version: 2026-10-19' \
  --header 'Content-Type: application/json' \
  --data '{
    "query": "盗窃案例",
    "queryKeywords": [
        "盗窃",
        "抢劫"
    ],
    "sortKeyAndDirection": {
        "trialYearMonthDate": "desc"
    },
    "referLevel": "其它",
    "filterAndStatisticListVo": {
        "courtLevelStatisticVo": "高级人民法院",
        "documentType": [
            "判决书",
            "裁定书"
        ],
        "trialYear": "2024-2025",
        "trialLevel": [
            "一审"
        ],
        "areaCourtStatisticVo": [
            "北京市",
            "广东省高级人民法院"
        ]
    },
    "pageParam": {
        "pageNumber": 1,
        "pageSize": 10
    }
}'

请求参数

以下字段填写在 JSON 请求体中。
string
path
required
案情描述、案号或检索关键词,不能为空白。
string
path
检索意图标识。长度为 1–128 个字符,可使用 A–Z、a–z、0–9、.、_、: 和 -。
object
path
分页与排序参数。缺省时使用第 1 页、每页 10 条。
number
path
default:"1"
从 1 开始的页码。
number
path
default:"10"
每页条数,最大按 50 条处理。
object
path
可选排序字段与方向。
带分页的请求示例。只需传入 query 即可使用默认分页。
{
  "query": "劳动争议",
  "searchId": "case-search-001",
  "pageParam": {
    "pageNumber": 1,
    "pageSize": 10
  }
}

可选检索条件

字段类型说明示例
queryKeywordsstring[]检索关键词列表["盗窃","抢劫"]
sortKeyAndDirectionobject排序字段与方向{"trialYearMonthDate":"desc"}
referLevelstring案例参考级别,如指导、公报或普通"其他"、"参考"、"指导性"
filterAndStatisticListVoobject案例筛选与统计条件{"trialYear":"2024-2025","trialLevel":["一审"]}

filterAndStatisticListVo

字段类型说明示例
courtLevelStatisticVoString法院层级"高级人民法院"
documentTypestring[]文书类型["判决书","裁定书"]
trialYearString裁判年份"2024-2025"
trialLevelstring[]审判程序["一审"]
areaCourtStatisticVostring[]地域与法院["北京市","广州市中级人民法院"]
使用说明高级筛选和排序字段请使用服务返回的筛选结构中的取值。

响应

外层响应包含 code、success 和 data;失败时还包含 message。先检查 HTTP 状态,再按下表判断业务结果。
结果判断方式与处理
检索成功success=true,检索结果在 data.records 中
无匹配结果success=true、data.records=[] 且 data.total=0,表示检索成功但未命中,不属于接入失败
业务失败success=false,查看 code 和 message;data 为空对象,不能仅根据 HTTP 状态判断业务成功

响应示例

以下为结构示例,记录内容为合成示例数据:
{
  "code": 200,
  "success": true,
  "data": {
    "records": [
      {
        "caseInfo": {
          "caseId": "case-001",
          "caseNo": "(2026)京01民终001号",
          "caseTitle": "某劳动争议民事判决书",
          "trialCourt": "某市中级人民法院",
          "trialDate": "2026-01-01",
          "trialLevel": "二审",
          "caseType": "民事",
          "closeCaseCause": "劳动争议",
          "documentType": "判决书",
          "caseSummary": "案例摘要",
          "refereeGist": "裁判要旨"
        },
        "similarity": "0.90",
        "highLights": [
          {
            "field": "caseSummary",
            "content": "劳动争议相关高亮内容"
          }
        ],
        "mode": "default"
      }
    ],
    "total": 1,
    "pageNum": 1,
    "pageSize": 10,
    "currentCount": 1,
    "queryKeywords": ["劳动争议"],
    "caseLevel": "普通"
  }
}

响应字段

array
required
当前页案例列表,最多 50 条。
number
required
命中总条数。
number
required
本次响应的页码。
number
required
本次响应的每页条数。
number
当前页实际返回数量。
string[]
本次查询使用的关键词。
string
案例级别。
object
筛选条件与统计信息。

records 条目

object
案例基础信息,包含 caseId、caseNo、caseTitle、trialCourt、trialDate、trialLevel、caseType、closeCaseCause、documentType、caseSummary 和 refereeGist 等字段。
string
相似度分数。
object[]
高亮片段,每项包含 field 和 content。
string
结果展示模式。

翻页与重试

  • 建议从第一次请求起就在 JSON 正文中填写 searchId,以便在未收到响应时用同一标识重试。
  • 重试同一请求时沿用原标识和原参数。同一检索词翻页时可沿用原标识,新检索意图使用新标识。该标识用于关联检索意图,服务端仍可能重新检索。积分使用与用量核对见计费与用量。
  • 未提供标识时,服务端生成执行标识并通过 X-Farui-Execution-Id 返回。若响应丢失且没有原标识,重发可能被视为新检索并产生额外用量。

错误处理

先检查 HTTP 状态,再检查响应中的 success、code 和 message。认证、参数或业务错误的排查方法见错误与排障;重发前核对上方的翻页与重试说明。