API 参考

概述

JanPNP Cloud API 提供 RESTful HTTP 接口，用于管理设备、执行贴装任务、控制硬件、管理料仓和执行视觉检测等操作。

基础信息

• Base URL: http://<host>:8766/api/v1
• 认证方式: JWT Bearer Token（部分公开端点无需认证）
• 响应格式: JSON

通用响应格式

成功响应

{
  "success": true,
  "...": "业务数据"
}

错误响应

{
  "success": false,
  "error": "错误描述"
}

HTTP 状态码

状态码	含义
200	请求成功
400	请求参数错误
401	未认证，请先登录
403	无设备访问权限
404	资源不存在
500	服务端错误
502	设备网关错误
504	设备响应超时

认证方式

在请求头中携带 JWT 令牌：

Authorization: Bearer <token>

获取令牌请参考认证鉴权 API。

API 端点一览

模块	端点	方法	说明
健康检查	/health	GET	服务健康检查
认证	/auth/login	POST	用户登录
	/auth/wechat-login	POST	微信小程序登录
	/auth/refresh	POST	刷新令牌
设备管理	/devices	GET	获取设备列表
	/devices/discover	GET	发现在线设备
	/devices/{id}	GET	获取设备详情
	/devices/{id}/overview	GET	获取设备概览
	/devices/{id}/status	GET	获取设备状态
	/devices/{id}/connection	GET	获取连接信息
	/devices/{id}/auth/login	POST	设备登录与绑定
系统管理	/devices/{id}/system/status	GET	系统状态
	/devices/{id}/system/settings	GET/PUT	系统设置读写
	/devices/{id}/system/settings/reset	POST	重置设置
	/devices/{id}/system/cal	POST	启动标定
贴装任务	/devices/{id}/tasks/current	GET	当前任务
	/devices/{id}/tasks/board_image	GET	板图像
	/devices/{id}/tasks/start	POST	启动任务
	/devices/{id}/tasks/pause	POST	暂停任务
	/devices/{id}/tasks/resume	POST	恢复任务
	/devices/{id}/tasks/stop	POST	停止任务
料仓管理	/devices/{id}/warehouse/components	GET/POST	元件列表/创建
	/devices/{id}/warehouse/components/{cid}	GET/PUT/DELETE	元件 CRUD
	/devices/{id}/warehouse/bom	GET	BOM 管理
	/devices/{id}/warehouse/feeder-slots	GET	飞达槽位
	/devices/{id}/warehouse/order-availability	GET	订单可用性
	/devices/{id}/warehouse/check-bom	POST	BOM 校验
机器视觉	/devices/{id}/vision/status	GET	视觉状态
	/devices/{id}/vision/model/status	GET	模型状态
	/devices/{id}/vision/model/switch	POST	切换模型
	/devices/{id}/vision/target/status	GET	目标状态
	/devices/{id}/vision/target/switch	POST	切换目标
	/devices/{id}/vision/detect/{cam}	POST	元件检测
硬件控制	/devices/{id}/hardware/position	GET	当前位置
	/devices/{id}/hardware/sync	GET	轴同步状态
	/devices/{id}/hardware/move	POST	运动控制
	/devices/{id}/hardware/pump	POST	泵控制
	/devices/{id}/hardware/valve	POST	阀控制
	/devices/{id}/hardware/light	POST	灯光控制
	/devices/{id}/hardware/pick	POST	吸取元件
调试接口	/devices/{id}/debug/ports	GET	串口列表
	/devices/{id}/debug/status	GET	调试状态
	/devices/{id}/debug/serial-log	GET	串口日志
	/devices/{id}/debug/send	POST	发送命令
固件发布	/firmware/slave/manifest.json	GET	固件清单
	/firmware/slave/system.bin	GET	固件镜像下载
	/admin/firmware/slave/releases	GET/POST	版本管理
	/admin/firmware/slave/releases/{id}/activate	POST	激活版本
订单管理	/devices/{id}/orders	GET/POST	订单列表/创建
	/devices/{id}/orders/recent	GET	最近订单
	/devices/{id}/orders/{oid}	GET	订单详情
	/devices/{id}/orders/parse	POST	解析订单
	/devices/{id}/orders/{oid}/cancel	POST	取消订单
	/devices/{id}/orders/{oid}	DELETE	删除订单
相机流	/devices/{id}/cameras/status	GET	相机状态
	/devices/{id}/cameras/{cam}/frame	GET	获取帧
扩展市场	/devices/{id}/extensions	GET	已安装扩展
	/devices/{id}/extensions/marketplace	GET	扩展市场
	/devices/{id}/extensions/stats	GET	扩展统计
	/devices/{id}/extensions/{eid}/install	POST	安装扩展
	/devices/{id}/extensions/{eid}/uninstall	POST	卸载扩展
用户反馈	/feedback	POST	提交反馈
广播	/broadcast	POST	广播消息（管理）