# 进销存开放平台 API 文档

版本: v1.0 | 基础URL: https://yisheng.cpolar.cn

认证方式

所有API请求都需要通过HMAC-SHA256签名验证，确保请求的合法性和完整性。

### 请求头

参数名 | 类型 | 必填 | 说明
--- | --- | --- | ---
X-API-Key | String | 是 | API密钥，用于标识调用方身份
X-Timestamp | String | 是 | 时间戳（秒级），用于防止重放攻击
X-Sign | String | 是 | 请求签名，HMAC-SHA256算法生成

### 签名生成步骤

1. 参数排序
将所有请求参数（不包括签名相关参数）按参数名ASCII码升序排列
2. 拼接参数字符串
将排序后的参数按 key=value 格式拼接，参数之间用 & 连接
3. 添加时间戳
在参数字符串末尾追加 ×tamp={时间戳}
4. 生成签名
使用 HMAC-SHA256 算法，以 API Secret 为密钥，对完整字符串进行签名
⚠️ 注意事项

- 时间戳有效期：7天
- 签名大小写敏感
- 参数值不进行URL编码
- 空值参数不参与签名

### 签名示例（JavaScript）

async function generateSignature(params, timestamp, apiSecret) { // 1. 参数排序 const sortedKeys = Object.keys(params).sort(); // 2. 拼接参数字符串 let paramStr = ""; for (const k of sortedKeys) { const v = params[k]; if (v !== null && v !== "") { if (paramStr) paramStr += "&"; paramStr += k + "=" + v; } } // 3. 添加时间戳 const fullStr = paramStr + "×tamp=" + timestamp; // 4. 生成签名 const encoder = new TextEncoder(); const messageData = encoder.encode(fullStr); const secretData = encoder.encode(apiSecret); const key = await crypto.subtle.importKey( "raw", secretData, { name: "HMAC", hash: "SHA-256" }, false, ["sign"] ); const signature = await crypto.subtle.sign("HMAC", key, messageData); return Array.from(new Uint8Array(signature)) .map(b => b.toString(16).padStart(2, "0")) .join(""); }
出库接口
GET /api/v1/chuku

查询出库（销售）数据，支持分页和日期范围过滤

### 请求参数

参数名 | 类型 | 必填 | 说明
--- | --- | --- | ---
start_date | String | 否 | 开始日期，格式：YYYY-MM-DD
end_date | String | 否 | 结束日期，格式：YYYY-MM-DD
page | Integer | 否 | 页码，默认：1
limit | Integer | 否 | 每页数量，默认：50，最大：500

### 请求示例

GET /api/v1/chuku?start_date=2024-02-02&end_date=2026-06-22&page=1&limit=100 Headers: X-API-Key: 4e2bf206a82f846c699e978cea8c2f87 X-Timestamp: 1782119268 X-Sign: 3f1b80b43f2bd83f85fc08ade76515773a58b8673b137b8f77e4e90d3dab9acc

### 响应示例

成功响应 (200)
{ "code": 200, "msg": "success", "total": 1500, "data": [ { "type": "销售登记", "ticket_no": "A01C202606160002", "register_time": "2026-06-16", "customer_code": "001", "customer_name": "喀喇沁旗中医蒙医医院", "total_amount": 2035.0, ... } ] }
错误响应 (500)
{ "code": 500, "msg": "数据查询失败: SQL Server 连接不可用" }
入库接口
GET /api/v1/ruku

查询入库（采购）数据，支持分页和日期范围过滤

### 请求参数

参数名 | 类型 | 必填 | 说明
--- | --- | --- | ---
start_date | String | 否 | 开始日期，格式：YYYY-MM-DD
end_date | String | 否 | 结束日期，格式：YYYY-MM-DD
page | Integer | 否 | 页码，默认：1
limit | Integer | 否 | 每页数量，默认：50，最大：500

### 请求示例

GET /api/v1/ruku?start_date=2024-02-02&end_date=2026-06-22&page=1&limit=100 Headers: X-API-Key: 4e2bf206a82f846c699e978cea8c2f87 X-Timestamp: 1782119268 X-Sign: 3f1b80b43f2bd83f85fc08ade76515773a58b8673b137b8f77e4e90d3dab9acc

### 响应示例

成功响应 (200)
{ "code": 200, "msg": "success", "total": 800, "data": [ { "type": "采购入库", "ticket_no": "A01Q202606160002", "register_time": "2026-06-16", "supplier_code": "1533", "supplier_name": "通化华夏药业有限责任公司", "total_amount": 101890.8, ... } ] }
错误响应 (500)
{ "code": 500, "msg": "数据查询失败: SQL Server 连接不可用" }
常见错误码

错误码 | 说明
--- | ---
200 | 请求成功
401 | 未授权，API Key无效或签名错误
403 | 禁止访问，权限不足或数据隔离配置错误
429 | 请求过于频繁，已触发限流
500 | 服务器内部错误，通常是数据库连接或查询失败

© 2026 进销存开放平台 | 文档版本 v1.0