Appearance
开放接口
本页说明当前开放接口的接入方式，以及设备信息查询接口的请求和返回格式。
API Key 获取与使用
开放接口通过 API Key 鉴权，不使用网页登录态。
获取方式：
- 登录系统
- 打开个人中心
- 进入
API Key 管理 - 创建或重置
API Key - 复制创建时返回的明文 key
使用方式：
- 在请求头中传入
X-API-Key - 每个用户当前只有一把 key
- 重置后，旧 key 会立即失效
- 禁用后，当前 key 无法继续调用开放接口
请求头示例：
http
X-API-Key: mph_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx当前范围
当前开放接口使用 API Key 鉴权，定位是外部系统只读查询。
现阶段已开放：
GET /api/open/device/{deviceId}
鉴权方式
开放接口不使用网页登录态，而是通过请求头传递 API Key：
http
X-API-Key: mph_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx接口收到请求后会：
- 从请求头读取
X-API-Key - 校验该 key 是否存在且已启用
- 识别当前调用所属用户
- 校验该用户是否拥有目标设备
注意
API Key 只在创建或重置时展示一次，请妥善保存。
请求地址
http
GET https://hcgl.top/api/open/device/{deviceId}私有部署说明
如果你使用的是私有部署版本，请将文档中的 https://hcgl.top 替换为你自己的服务地址。
路径参数
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
deviceId | string | 是 | 打印机设备 ID |
请求头
| 名称 | 必填 | 说明 |
|---|---|---|
X-API-Key | 是 | 当前用户的开放接口凭证 |
请求示例
bash
curl -X GET \
'https://hcgl.top/api/open/device/DEVICE_ID' \
-H 'X-API-Key: 这里替换成你的apikey'返回说明
返回结构遵循系统统一响应格式：
json
{
"code": 0,
"data": {
"name": "客厅 P1S",
"deviceId": "DEVICE_ID",
"model": "P1S",
"printStatus": "RUNNING",
"printProgress": 42,
"taskImage": "https://example.com/task-cover.png",
"remainingTime": 126,
"chamberLight": "on",
"chamberLight2": "off",
"workLight": "on",
"bedTemp": 60,
"chamberTemp": 35,
"layerNum": 88,
"totalLayerNum": 210,
"trayType": "PLA"
},
"message": "ok"
}data 字段说明
| 字段 | 类型 | 说明 |
|---|---|---|
name | string | 打印机名称 |
deviceId | string | 设备 ID |
model | string | 打印机型号，枚举见下方 |
printStatus | string | 当前打印状态，枚举见下方 |
printProgress | number | 当前打印进度，范围 0-100 |
taskImage | string | 当前任务封面图地址，可能为空 |
remainingTime | number | 预计剩余打印时间，单位分钟 |
chamberLight | string | 主打印腔灯状态，常见值为 on / off |
chamberLight2 | string | 第二路打印腔灯状态，常见值为 on / off |
workLight | string | 工作灯状态，常见值为 on / off |
bedTemp | number | 当前热床温度 |
chamberTemp | number | 当前仓温 |
layerNum | number | 当前层数 |
totalLayerNum | number | 总层数 |
trayType | string | 当前使用中的耗材类型，枚举见下方 |
printStatus 枚举
printStatus 来自设备状态中的 gcode_state，当前项目中使用的枚举值如下：
| 值 | 含义 |
|---|---|
FAILED | 失败 |
FINISH | 完成 |
IDLE | 空闲 |
OFFLINE | 离线 |
PREPARE | 准备中 |
RUNNING | 打印中 |
PAUSE | 暂停 |
SLICING | 切片中 |
INIT | 初始化 |
说明
不同设备型号或不同阶段上报的状态可能不完全一致，但当前系统内部已明确使用并兼容以上值。
model 枚举
model 返回的是系统映射后的型号文本，当前项目中已定义的型号如下：
| 返回值 | 底层设备型号值 |
|---|---|
X1C | BL-P001 |
P1P | C11 |
P1S | C12 |
X1E | C13 |
A1MINI | N1 |
A1 | N2S |
X2D | N6-V2 |
P2S | N7-V2 |
H2C | O1C2-V2 |
H2D | O1D |
H2S | O1S |
说明
如果后端收到未在映射表中的设备型号，接口会直接返回原始型号值，而不是上表中的文本。
trayType 枚举
trayType 表示当前使用中的耗材类型，当前可能的值包括：
| 值 | 值 | 值 | 值 |
|---|---|---|---|
ABS | ABS-GF | ASA | ASA-AERO |
ASA-CF | BVOH | EVA | HIPS |
PA | PA-CF | PA-GF | PA6-CF |
PC | PCTG | PE | PE-CF |
PET-CF | PETG | PETG-CF | PHA |
PLA | PLA-AERO | PLA-CF | PP |
PP-CF | PP-GF | PPA-CF | PPA-GF |
PPS | PPS-CF | PVA | TPU |
TPU-AMS |
说明
trayType 由设备当前激活的料盘信息解析得到；当设备未上报耗材信息或当前槽位无法识别时，该字段可能为空。
权限校验说明
该接口会同时校验：
API Key对应的用户- 设备缓存归属
- 数据库中的设备归属
如果设备不属于当前 API Key 用户，或缓存归属与数据库归属不一致，请求会直接返回错误，不继续处理。
常见错误
| 场景 | 说明 |
|---|---|
未传 X-API-Key | 请求未通过开放接口鉴权 |
API Key 无效或已禁用 | 无法识别当前调用用户 |
deviceId 不存在 | 目标设备不存在 |
| 当前用户无权访问该设备 | 设备不属于当前 API Key 用户 |
| 设备归属校验不一致 | Redis 缓存归属与数据库归属不一致 |
错误返回示例
接口错误时同样会返回统一响应结构，通常格式如下：
json
{
"code": 40101,
"data": null,
"message": "无权访问该设备"
}常见错误示例
未传 X-API-Key 或身份缺失：
json
{
"code": 40100,
"data": null,
"message": "Open API 调用身份缺失"
}API Key 无效：
json
{
"code": 40100,
"data": null,
"message": "API Key 无效"
}API Key 已禁用：
json
{
"code": 40100,
"data": null,
"message": "API Key 已禁用"
}无权访问该设备：
json
{
"code": 40101,
"data": null,
"message": "无权访问该设备"
}设备不存在：
json
{
"code": 40400,
"data": null,
"message": "设备不存在"
}设备归属校验不一致：
json
{
"code": 40101,
"data": null,
"message": "设备归属校验不一致"
}调试建议
- 可先调用
GET /api/open/whoami验证当前API Key是否生效 - 再调用
GET /api/open/device/{deviceId}验证设备访问权限 - 如果出现归属不一致，请先检查设备绑定关系和缓存同步是否正常