开放API文档_恒丰万达药物杂质对照品

概览

本站产品数据通过统一 RESTful 接口对外开放。基础地址：https://www.hdbiochemical.com/api/v1。鉴权方式：请求头 X-API-Key: 您的Key（后台「同步中心」签发）。

KEY标注的接口需要 API Key；其余为开放只读接口。

GET

产品查询（开放）

接口	说明
`GET /api/v1/products`	产品列表（分页/增量/筛选），支持 `page`、`page_size`（≤200）、`updated_after`（增量拉取）、`category`、`in_stock`
`GET /api/v1/products/{货号或CAS}`	单品详情
`GET /api/v1/products/search?q=关键词`	关键词搜索（名称/货号/CAS/同义词/分子式/标签）
`GET /api/v1/export?format=json\|csv\|chemicalbook`	全量导出（含结构式图片地址）

POST

推送产品（新增+更新）KEY

POST /api/v1/sync/push（推荐，ERP对接入口）或 POST /api/v1/products。Body 为 {"products":[...]} 或产品数组。已存在的产品（按货号匹配，无货号按CAS匹配）仅覆盖本次提供的字段，不清空其他字段；不存在则新增。响应返回 created/updated/invalid/codes。

POST /api/v1/sync/push
X-API-Key: hd_xxxx
Content-Type: application/json

{
  "products": [
    {
      "code": "R005001",          // 货号（无则用CAS自动生成EXT-码）
      "name_cn": "利伐沙班杂质1",   // 中文名（必填）
      "name_en": "Rivaroxaban Impurity 1",
      "cas": "1429334-00-8",
      "formula": "C16H19N3O5",
      "mw": 333.34,
      "synonyms": "利伐沙班EP杂质B",
      "category": "杂质对照品",
      "series": "利伐沙班",
      "status": "in_stock",
      "stock": 10,                 // 有库存数则自动判定现货
      "structure_url": "https://.../R005001.png",
      "description": "用于质量研究。"
    }
  ]
}

→ { "ok": true, "created": 1, "updated": 0, "invalid": 0, "codes": ["R005001"] }

字段名智能兼容中英文键：code/item_code/sku/货号/编号 → 货号；name/name_cn/品名/名称/productname → 名称；cas/cas_no/CAS号 → CAS；formula/mf/分子式 → 分子式；mw/mol_weight/molecular_weight/分子量 → 分子量；stock/qty/库存 → 库存；structure_url/img/结构式/图片 → 结构式；description/remark/备注/说明 → 描述。

产品字段说明（增删改查通用）

字段	类型	必填	说明
`code`	文本 ≤30字符	推送必填*	货号，全局唯一。*推送时若无货号但提供了CAS，自动生成 `EXT-{CAS}` 码。编辑/删除/打标签时作为定位键
`name_cn`	文本 ≤200	是	中文名（推送时智能匹配 name/品名/名称等键）
`name_en`	文本 ≤200	否	英文名（多语言；后台可自动翻译）
`cas`	文本 ≤40	否	CAS号，无则存 N/A；用于无货号时匹配产品
`formula`	文本 ≤60	否	分子式
`mw`	数值	否	分子量（兼容 mol_weight / molecular_weight）
`synonyms`	文本 ≤300	否	同义词，分号分隔；参与前台搜索命中（如"EP杂质A"）
`category`	枚举	否	分类：`杂质对照品` / `标准品` / `中间体`（默认杂质对照品；自定义分类先用分类接口创建）
`series`	文本 ≤50	否	药物系列（如"利伐沙班"），详情页按系列聚合展示
`status`	枚举	否	库存状态：`in_stock`现货 / `futures`期货（默认）/ `custom`可定制 / `off`下架。推送时传 `stock` 数字>0 也自动判为现货
`tags`	文本 ≤300	否	标签，分号分隔（如"热销;基因毒性;申报推荐"）；参与搜索，前台多彩展示
`structure_url`	URL ≤500	否	结构式图片地址（png/jpg），前台详情页与产品卡片展示
`description`	文本 ≤1000	否	产品描述
`description_en`	文本 ≤1000	否	英文描述（多语言同步用）
`updated_at`	时间戳	系统	最后更新时间（任何写入操作自动刷新；增量拉取的依据）

PUT

编辑产品 KEY

PUT /api/v1/products/{货号} —— Body 只传要修改的字段，未传字段保持不变。

PUT /api/v1/products/R005001
X-API-Key: hd_xxxx

{ "status": "futures", "mw": 333.34, "tags": "热销;基因毒性" }

→ { "ok": true, "code": "R005001", "updated_fields": ["status","mw","tags"] }

可编辑字段：name_cn / name_en / synonyms / cas / formula / mw / category / series / status / structure_url / description / description_en / ai_summary / ai_summary_en / tags

DELETE

删除产品 KEY

DELETE /api/v1/products/{货号} 删除单品；DELETE /api/v1/products/batch + Body {"codes":["A001","A002"]} 批量删除（单次≤500个）。响应返回 deleted 与 not_found 清单。

GETPOSTDELETE

分类管理接口

接口	鉴权	说明
`GET /api/v1/categories`	开放	查询全部分类列表 → `{"ok":true,"data":["杂质对照品","标准品","中间体"]}`
`POST /api/v1/categories`	KEY	新增分类：Body `{"name":"新分类"}` 或 `{"names":["A","B"]}`；已存在自动跳过 → `{"added":1,"skipped":0}`
`DELETE /api/v1/categories`	KEY	删除分类：Body `{"name":"旧分类"}` 或 `{"names":[...]}`；不影响已挂该分类的产品（产品仍保留原分类文本）

建议对接ERP时：先把ERP的品类映射到我们的分类（不够就新增），再推产品时带上 category 字段。

GETPOST

标签管理接口

接口	鉴权	说明
`GET /api/v1/tags`	开放	查询标签字典（按使用频次排序）→ `{"data":[{"tag":"热销","use_count":12},...]}`
`POST /api/v1/tags`	KEY	新增标签到字典：Body `{"tag":"基因毒性"}` 或 `{"tags":[...]}`
`POST /api/v1/tags/apply`	KEY	给产品打标签（批量）：Body `{"codes":["R005001","A057001"], "tags":["热销","申报推荐"], "mode":"append"}`；mode 可选 `append`追加（默认，去重合并）/ `replace`替换 → `{"done":2,"not_found":[]}`

GETPOSTPUT

图片上传接口（结构式/产品图）KEY

三种上传方式任选（均需 API Key，返回 url 后填入产品推送的 structure_url 字段即可；单张≤10MB，单次最多20张，不限流）。上传的图片进入本站媒体库，前台永久可访问。

方式	接口	适用场景
① JSON base64	`POST /api/v1/media`	程序调用（ERP/脚本）：Body `{"dataUrl":"data:image/png;base64,..."}` 或 `{"image":"<base64>","mime":"image/png"}`；支持数组批量
② 表单文件直传	`POST /api/v1/media/upload`	标准 multipart/form-data（网页表单、curl -F、Postman）
③ 二进制裸传	`PUT /api/v1/media/{文件名.png}`	curl --data-binary 直传图片本体，文件名带扩展名（.png/.jpg/.gif/.webp/.bmp）
查询媒体列表	`GET /api/v1/media`	开放；最近100张图片的 id/url/分组/文件名

# 方式一：JSON base64
POST /api/v1/media
X-API-Key: hd_xxxx
Content-Type: application/json

{ "dataUrl": "data:image/png;base64,iVBORw0KGgo..." }
// 或批量：[{ "dataUrl": "...", "filename": "R005001.png" }, ...]

→ { "ok": true, "uploaded": 1, "results": { "ok": true, "url": "/media/58", "id": 58 } }

# 方式二：表单直传
curl -X POST https://域名/api/v1/media/upload \
  -H "X-API-Key: hd_xxxx" \
  -F "file=@R005001.png"

# 方式三：二进制裸传
curl -X PUT https://域名/api/v1/media/R005001.png \
  -H "X-API-Key: hd_xxxx" \
  --data-binary @R005001.png

→ { "ok": true, "url": "/media/58" }

完整地址 = https://域名 + 返回的 url（如 https://域名/media/58）。之后推送产品时带上："structure_url": "https://域名/media/58"。

限流与安全

Key 持有者：写入类接口（产品推送/编辑/删除/分类/标签/图片上传）不限流，查询 600 次/分钟；匿名只读 120 次/分钟。全部调用记录在后台「同步中心 → 同步日志」。请通过 HTTPS 调用并妥善保管 API Key。

典型对接流程（ERP → 本站）

1. 后台「同步中心」签发 API Key → 2. （可选）POST /api/v1/categories 同步分类 → 3. （可选）POST /api/v1/media 上传结构式图片 → 4. POST /api/v1/sync/push 推送产品（structure_url 填图片返回地址） → 5. 后台产品管理筛选「仅同步来源」核对 → 6. 日常用 PUT 更新、DELETE 删除、/tags/apply 打标签。

快速体验

接口清单 · 试读3条产品 · 分类列表 · 标签字典 · 搜索示例

合作对接请联系：info@hdimpurity.com

开放 API · 数据同步中枢

概览