API 接入

API 供程序、脚本或自动化工具调用全文搜索。按次消耗点数，无需订阅会员。

接入准备

调用地址

POST https://api.flfgsc.cn/v1/search
GET  https://api.flfgsc.cn/v1/user/points

鉴权方式

在请求头中加入您的 API 密钥：

Authorization: Bearer flfgsc_xxxxxxxxxxxxxxxxx
Content-Type: application/json

API 密钥可在 App 的「API 使用」页面复制。重置密钥后，旧密钥会立即失效，已接入的工具需要同步更新。

搜索接口 `POST /v1/search`

关键词检索与语义检索混合，关键词精确命中优先，不足时自动补充语义相关条文。

请求参数

query：必填，搜索关键词。空格分隔多个词时按 OR 检索，如 合同解除合同终止解约；加 + 前缀表示该词必须出现（AND），如 +合同 +解除。
limit：可选，返回数量，范围 1 到 100，默认 50。
category：可选，搜索范围。可填「全部」「法律」「行政法规」「司法解释」「部门规章」「国家监察委员会」「中共中央」。
effective：可选，有效性筛选，默认「当前有效」。可填「当前有效」「包含失效」「YYYY-MM-DD有效」，如「2024-03-15有效」。
modification：可选，修正案筛选，默认「排除修正案」。可填「排除修正案」「包含修正案」「仅限修正案」。

调用示例

curl -X POST "https://api.flfgsc.cn/v1/search" \
  -H "Authorization: Bearer flfgsc_xxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "合同解除",
    "limit": 10,
    "category": "法律"
  }'

返回内容

{
  "results": [
    {
      "law": "中华人民共和国民法典（2020年）",
      "category": "法律",
      "clause": "第五百六十二条　当事人协商一致，可以解除合同。当事人可以约定一方解除合同的事由。解除合同的事由发生时，解除权人可以解除合同。",
      "url": "https://www.flfgsc.cn/law/.../clause_xxx"
    },
    {
      "law": "中华人民共和国民法典（2020年）",
      "category": "法律",
      "clause": "第五百六十三条　有下列情形之一的，当事人可以解除合同：\n（一）因不可抗力致使不能实现合同目的；\n（二）在履行期限届满前，当事人一方明确表示或者以自己的行为表明不履行主要债务；\n（三）当事人一方迟延履行主要债务，经催告后在合理期限内仍未履行；\n（四）当事人一方迟延履行债务或者有其他违约行为致使不能实现合同目的；\n（五）法律规定的其他情形。",
      "url": "https://www.flfgsc.cn/law/.../clause_yyy"
    }
  ],
  "points": {
    "cost": 1,
    "balance": 122
  }
}

results 按相关性排序，每条包含所属法律名称、分类、条款正文和页面地址。搜索完整成功后才会扣点；points.cost 是本次扣费点数，balance 是扣费后余额，不需要额外调用余额接口。

余额查询 `GET /v1/user/points`

余额查询不会消耗点数，只返回当前这一刻的点数数值：

curl "https://api.flfgsc.cn/v1/user/points" \
  -H "Authorization: Bearer flfgsc_xxxxxxxxxxxxxxxxx"

返回示例：

{
  "points": {
    "balance": 123
  }
}

常见错误

错误响应会同时返回机器可读的 code 和用户可读的 message，需要给出修正建议时会带 hint：

{
  "code": "INSUFFICIENT_POINTS",
  "message": "点数不足"
}

{
  "code": "INVALID_CATEGORY",
  "message": "搜索范围不支持",
  "hint": "category=xxx；只接受：全部、法律、行政法规、司法解释、部门规章、国家监察委员会、中共中央"
}

401 INVALID_API_KEY：密钥缺失或错误。
402 INSUFFICIENT_POINTS：点数不足。
429 RATE_LIMITED：请求过于频繁，请稍后重试。
400 EMPTY_QUERY：搜索内容为空。
400 INVALID_CATEGORY：搜索范围不支持。
400 INVALID_EFFECTIVE：有效性筛选不支持（只接受「当前有效」「包含失效」「YYYY-MM-DD有效」）。
400 INVALID_MODIFICATION：修正案筛选不支持（只接受「排除修正案」「包含修正案」「仅限修正案」）。

请妥善保管 API 密钥，不要放在公开仓库、网页前端代码或截图中。