API 文档 — 结构式搜索

鉴权说明

所有 /api/* 接口（/api/mol2img 和 /api/mol2svg 除外）均需在请求头中携带：

http

Authorization: Bearer <API Key>

🔒 ApiKey 安全警告（必读）：API Key 是服务器端凭证，严禁出现在任何前端代码、页面源码或客户端可访问的位置（包括 JS 文件、HTML 注释、URL 参数等）。一旦泄露，任何人均可无限制调用接口，导致配额耗尽或数据被篡改。
正确做法：将 API Key 仅保存在服务端（环境变量或密钥管理系统），由你的后端代理层携带后再转发请求。前端代码中只持有 AppKey（用于编辑器授权域名校验，不是检索鉴权凭证，两者作用不同）。

错误码

code	HTTP 状态	含义
200	200 OK	请求成功
400	400 Bad Request	参数错误 / 鉴权失败 / 授权过期
403	403 Forbidden	授权到期或租户数超出许可上限
422	422 Unprocessable Entity	请求体 JSON 格式错误
500	500 Server Error	服务器内部错误

化合物管理

POST /api/structure/save 保存化合物

API Key

批量新增或更新化合物记录。以 pkid 为唯一键，重复时执行 UPSERT。

smile 字段是子结构 / 精确 / 相似度 / SMARTS 搜索的前提。无 SMILES 的化合物仅支持字段搜索。

请求字段（items 数组元素）

字段	类型	必填	说明
`pkid`	string	必填	记录唯一标识
`smile`	string	可选	SMILES 字符串（用于结构搜索）
`mdl`	string	可选	MDL 号
`catalogNo`	string	可选	货号
`cas`	string	可选	CAS 号，格式 `XXXXXXX-XX-X`
`cnName`	string	可选	中文名
`enName`	string	可选	英文名
`url`	string	可选	产品链接
`inchiKey`	string	可选	InChIKey（不提供时由服务端从 SMILES 自动计算）
`pubchemId`	string	可选	PubChem CID
`others`	object	可选	自定义扩展字段（JSON 对象，可用于 `othermust` 过滤）

请求示例

json

{
  "items": [
    {
      "pkid": "mol-001",
      "catalogNo": "CRI008168",
      "smile": "Cl.O=C(O)[C@@H]1CNC[C@H]1C(F)(F)F",
      "cas": "12345-67-8",
      "cnName": "化合物A",
      "enName": "Compound A",
      "inchiKey": "WRWPZFUIFXLHEJ-VKKIDBQXSA-N",
      "others": { "formula": "C6H9ClF3NO2", "molWeight": "219.589" }
    }
  ]
}

json — 响应

{ "success": true, "code": 200, "message": "成功", "errors": [] }

POST /api/structure/delete 删除化合物

API Key

按 pkid 批量删除化合物记录。

json — 请求

{ "pkids": ["mol-001", "mol-002"] }

json — 响应

{ "success": true, "code": 200, "message": "成功", "result": { "deleted": 2 } }

搜索接口

统一入口 POST /api/search，通过 searchType 区分类型。通用参数：page（页码，默认 1）、psize（每页条数，默认 20）、othermust（others 字段精确过滤）。

通用响应字段：hits（命中总数）、records（结果列表，含 pkid、smile、fzl 分子量、fzs 分子式、mdl、others）。

POST /api/search 子结构搜索 — sub

API Key

查找包含查询 SMILES 所描述子结构的所有分子。

字段	类型	必填	说明
`searchType`	string	必填	固定值 `"sub"`
`smile`	string	必填	查询子结构的 SMILES

json

{ "searchType": "sub", "smile": "C1CCCCC1", "page": 1, "psize": 10 }

json — 响应结构

{
  "code": 200, "success": true,
  "hits": 1, "page": 1, "psize": 10, "total_page": 1,
  "records": [
    {
      "pkid": "mol-001",
      "catalogno": "CRI008168",
      "smile": "Cl.O=C(O)[C@@H]1CNC[C@H]1C(F)(F)F",
      "fzl": 219.5893714427948,
      "fzs": "C6 H9 Cl F3 N O2",
      "others": { "formula": "C6H9ClF3NO2", "molWeight": "219.589" }
    }
  ]
}

POST /api/search 精确搜索 — exact

API Key

查找与查询 SMILES 完全相同的分子，含完整立体化学信息。

json

{ "searchType": "exact", "smile": "C1CCC2CCCCC2C1", "page": 1, "psize": 10 }

POST /api/search 相似度搜索 — similarity

API Key

基于 Morgan 指纹（半径 2）的 Tanimoto 相似度搜索，返回相似度 ≥ 阈值的所有分子。

字段	类型	必填	说明
`searchType`	string	必填	固定值 `"similarity"`
`smile`	string	必填	查询分子的 SMILES
`similarity`	float	可选	Tanimoto 阈值，默认 `0.8`，范围 `0.0 ~ 1.0`

json

{ "searchType": "similarity", "smile": "C1CCC2CCCCC2C1", "similarity": 0.5, "page": 1, "psize": 10 }

POST /api/search 自定义字段搜索 — custom

API Key

按数据字段搜索，不进行结构匹配。kwd 为模糊匹配（ILIKE '%kwd%'），匹配货号 / 中英文名 / CAS / InChIKey / pkid；其余字段为精确匹配。

字段	类型	说明
`kwd`	string	全文关键词，模糊匹配多个字段（catalogno / cnname / enname / cas / inchikey / pkid）
`catalogNo`	string	精确匹配货号
`cas`	string	精确匹配 CAS 号
`inchiKey`	string	精确匹配 InChIKey
`pkid`	string	精确匹配 pkid
`pubchemId`	string	精确匹配 PubChem ID
`othermust`	object	`others` 字段精确过滤（JSON 子集匹配）

json — 关键词搜索

{ "searchType": "custom", "kwd": "CRI", "page": 1, "psize": 20 }

json — 精确货号

{ "searchType": "custom", "catalogNo": "CRI007114", "page": 1, "psize": 10 }

POST /api/search JSON 条件搜索 — query

API Key

使用 JSON 对象指定多字段精确过滤条件（AND 关系）。字段名使用数据库列名（小写）。

json

{ "searchType": "query", "query": { "catalogno": "CRI008168" }, "page": 1, "psize": 10 }

工具接口

GET /api/smileinfo/{smile} SMILES 信息查询

API Key

根据 SMILES 计算分子量、分子式、InChIKey 和 MDL Molfile。{smile} 需 URL-encode 后传入路径。

bash

GET /api/smileinfo/C1CCNC1
Authorization: Bearer <API Key>

json — 响应

{
  "code": 200,
  "success": true,
  "data": {
    "inchikey": "NNBZCPXTIHJBJL-UHFFFAOYSA-N",
    "fzl": 85.1472,
    "fzs": "C5 H11 N",
    "mol": "\n  Molfile...\nM  END\n"
  }
}

响应字段	说明
`inchikey`	InChIKey 标准标识符
`fzl`	分子量（float，Da）
`fzs`	分子式（如 `"C5 H11 N"`）
`mol`	MDL Molfile V2000 字符串

POST /api/molinfo MOL 信息查询

API Key

传入 MDL Molfile 字符串，返回分子量、分子式、InChIKey 和 SMILES。

请求体

字段	类型	必填	说明
`molfile`	string	必填	MDL Molfile（V2000/V3000）字符串

json

POST /api/molinfo
Authorization: Bearer <API Key>
Content-Type: application/json

{ "molfile": "\n  Molfile...\nM  END\n" }

json — 响应

{
  "code": 200,
  "success": true,
  "data": {
    "fzl": 85.1472,
    "fzs": "C5 H11 N",
    "inchikey": "NNBZCPXTIHJBJL-UHFFFAOYSA-N",
    "smile": "C1CCNC1"
  }
}

响应字段	说明
`fzl`	分子量（float，Da）
`fzs`	分子式（如 `"C5 H11 N"`）
`inchikey`	InChIKey 标准标识符
`smile`	规范化 SMILES 字符串

GET /api/mol2img/{smile} 分子结构图片渲染

无需鉴权

将 SMILES 渲染为 PNG 结构图，直接返回图片二进制。{smile} 需 URL-encode。可直接嵌入 <img src="...">。

html — 嵌入示例

<img src="http://<host>:8001/api/mol2img/C1CCNC1?width=400&height=400"
     width="400" height="400" alt="molecule structure" />

参数	类型	默认	说明
`{smile}`	path	—	URL-encode 后的 SMILES 字符串
`width`	query / int	300	输出图片宽度（像素）
`height`	query / int	300	输出图片高度（像素）

响应	说明
`Content-Type`	`image/png`
错误	`{"code": 400, "message": "..."}`

GET /api/mol2svg/{smile} 分子结构图片渲染 SVG

无需鉴权

将 SMILES 渲染为 SVG 矢量结构图，直接返回 SVG 文本。{smile} 需 URL-encode。SVG 可无损缩放，适合嵌入网页或高清打印。

html — 嵌入示例

<img src="http://<host>:8001/api/mol2svg/C1CCNC1"
     width="300" height="300" alt="molecule structure" />

响应	说明
`Content-Type`	`image/svg+xml`
尺寸	300 × 300 逻辑像素，白色背景，可缩放
错误	`{"code": 400, "message": "..."}`

REST API 文档

鉴权说明

错误码

化合物管理

搜索接口

工具接口