● v1.0 · 稳定版

序航医疗 API 文档

本 API 提供序航医疗网站核心数据的程序化访问能力，支持产品信息查询、行业资讯读取、询价表单提交等功能。接口采用 RESTful 规范设计，所有请求和响应均使用 JSON 格式。

BASE URL https://api.xuhang-medical.com/v1

所有接口均需在请求头中携带 API Key（见鉴权章节）。本文档中的示例均使用 YOUR_API_KEY 作为占位符。

鉴权

所有 API 请求需在 HTTP 请求头中携带 X-API-Key 字段。如需申请 API Key，请联系我们的技术团队。

🔐 请妥善保管您的 API Key，不要在前端代码或公开仓库中暴露 Key。建议通过后端服务转发 API 请求。

请求头示例

X-API-Key: YOUR_API_KEY
Content-Type: application/json

错误码

API 使用标准 HTTP 状态码表示请求结果。所有错误响应均包含 code 和 message 字段。

状态码	含义	说明
200	OK	请求成功
201	Created	资源创建成功（POST）
400	Bad Request	请求参数错误或缺失必填字段
401	Unauthorized	API Key 无效或未提供
403	Forbidden	权限不足
404	Not Found	请求的资源不存在
429	Too Many Requests	超出频率限制
500	Server Error	服务器内部错误

频率限制

默认情况下，每个 API Key 的请求频率限制为：

GET 接口：600 次 / 分钟
POST 接口：60 次 / 分钟

超出限制后，服务器将返回 429 状态码。响应头中会包含 X-RateLimit-Reset 字段，指示限制重置时间（Unix 时间戳）。

获取产品列表

GET /products 返回产品列表，支持分类筛选和分页

Query 参数

参数	类型	说明
category	string	产品分类：`diagnostic` \| `treatment` \| `consumables`
page	integer	页码，默认 1
limit	integer	每页条数，默认 20，最大 100
q	string	关键词搜索（产品名称、型号）

cURL 示例

curl -X GET "https://api.xuhang-medical.com/v1/products?category=diagnostic&page=1&limit=10" \
  -H "X-API-Key: YOUR_API_KEY"

响应示例 200 OK

{
  "success": true,
  "data": {
    "products": [
      {
        "id": "XH-US5000",
        "name": "彩色超声诊断仪",
        "category": "diagnostic",
        "model": "XH-US5000",
        "description": "高清成像，多探头配置...",
        "features": ["高清成像", "多探头", "智能诊断"],
        "createdAt": "2025-01-01T00:00:00Z"
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 10,
      "total": 32,
      "pages": 4
    }
  }
}

获取单个产品

GET /products/{id} 通过产品 ID / 型号获取详情

Path 参数

参数	类型	说明
id 必填	string	产品 ID 或型号，例如 `XH-US5000`

cURL 示例

curl -X GET "https://api.xuhang-medical.com/v1/products/XH-US5000" \
  -H "X-API-Key: YOUR_API_KEY"

产品分类

GET /products/categories 获取所有产品分类及计数

响应示例

{
  "success": true,
  "data": [
    { "id": "diagnostic",  "name": "诊断设备", "count": 12 },
    { "id": "treatment",  "name": "治疗设备", "count": 10 },
    { "id": "consumables", "name": "耗材用品", "count": 10 }
  ]
}

获取资讯列表

GET /news 获取行业资讯，支持类型和月份筛选

Query 参数

参数	类型	说明
type	string	`policy` \| `tech` \| `event`
month	string	月份格式：`2026-04`
page	integer	页码，默认 1
limit	integer	每页条数，默认 20

JavaScript 示例

const response = await fetch(
  'https://api.xuhang-medical.com/v1/news?type=policy&month=2026-04',
  { headers: { 'X-API-Key': 'YOUR_API_KEY' } }
);
const { data } = await response.json();

获取单条资讯

GET /news/{id} 通过资讯 ID 获取完整内容

Path 参数

参数	类型	说明
id 必填	string	资讯 ID，例如 `2026-04-001`

提交询价表单

POST /contact 提交在线询价或咨询请求

Request Body (JSON)

字段	类型	说明
name 必填	string	联系人姓名
phone 必填	string	手机号码（11位）
email	string	电子邮箱
company	string	单位名称
subject 必填	string	咨询类型
message 必填	string	详细内容（10-2000字）
productId	string	关联产品 ID（可选）

请求示例

curl -X POST "https://api.xuhang-medical.com/v1/contact" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "张医生",
    "phone": "13800138000",
    "company": "XX医院",
    "subject": "产品咨询",
    "message": "请提供XH-US5000超声诊断仪的报价及参数",
    "productId": "XH-US5000"
  }'

响应示例 201 Created

{
  "success": true,
  "data": {
    "id": "INQ-2026-04-00123",
    "message": "询价已提交，我们将在24小时内联系您",
    "createdAt": "2026-04-30T10:30:00Z"
  }
}

健康检查

GET /health 检查 API 服务可用性（无需鉴权）

响应示例

{
  "status": "ok",
  "version": "1.0.0",
  "timestamp": "2026-04-30T10:30:00Z",
  "services": {
    "database": "ok",
    "cache": "ok"
  }
}

快速测试

curl https://api.xuhang-medical.com/v1/health