NexusCore API V1 对接文档
版本:V1 兼容通道 / 文档 6.0
一、适用范围
V1 供既有客户端、旧版 Native 和用户自行维护的既有对接程序使用。
V1 不是 V2 的镜像文档;新接入优先阅读 V2 文档。
V1 与 V2 文档长期并存,调用方可根据自己的客户端版本选择。
二、地址
网关首页:https://NexusCore.sufox.sbs/api/v1/
健康状态:https://NexusCore.sufox.sbs/api/v1/health
统一查询参数:https://NexusCore.sufox.sbs/api/v1/?r=/health
兼容文件名:https://NexusCore.sufox.sbs/api/v1/api_gateway.php?r=/health
三、默认协议与认证
V1 兼容 JSON 命令协议,默认端口 HTTPS 443。
POST /api/v1/?r=/auth/token
Content-Type: application/json
{"key":"NexusCoreUserKey_..."}成功返回 access_token,后续使用 Authorization: Bearer <token>。
用户密钥重置、账号封禁或角色变化后,旧 Token 会失效。
四、V1 设备心跳
POST /api/v1/?r=/devices/heartbeat
Content-Type: application/json
Authorization: Bearer <token>
{"device_id":"设备标识",
"info":{"model":"设备型号","brand":"品牌","sdk":"34","android":"14",
"client_type":"binary"
}
}
V1 未提供 execution_layer 时,binary 默认按 native 处理。
返回 task 为 null 表示没有任务,否则包含 request_id 与 command。
五、V1 接口
GET /api/v1/health
POST /api/v1/auth/token
POST /api/v1/devices/heartbeat
POST /api/v1/devices/tasks/{request_id}/ackPOST /api/v1/devices/tasks/{request_id}/resultGET /api/v1/devices
GET /api/v1/devices/{device_key}POST /api/v1/devices/commands
GET /api/v1/devices/{device_key}/commands/latestGET /api/v1/user/info
POST /api/v1/upload
POST /api/v1/upload_base64
GET /api/v1/private/files
DELETE /api/v1/private/files/{id}GET /api/v1/public/files
GET /api/v1/public/announcement
六、结果上报
POST /api/v1/?r=/devices/tasks/{request_id}/result{"stdout":"输出","stderr":"错误输出","exit_code":0,"duration_ms":100,"client_type":"binary"}先 ACK 再上报结果,服务端保存请求 ID、状态、退出码和输出。
七、V1 限制
V1 继续使用兼容错误结构,例如 {"error":"Missing or invalid token"}。
V1 不提供 V2 新增的全部管理能力;新协议能力只在 V2 扩展。
V2 维护时 V1 用作受控降级;V1 自身也可由开发者停用。
设备、命令、文件仍执行归属校验,管理员/开发者权限由服务端判断。
普通 JSON 请求体、请求频率、上传类型与内容仍受安全策略限制。
V1 同样执行上传前检查与落盘后二次检查,危险文件会被删除、下架、计次和邮件警告。
八、文档入口
V1:https://NexusCore.sufox.sbs/api/v1/api_socs.html
V2:https://NexusCore.sufox.sbs/api/v2/api_socs_v1.html
通用安全说明:https://NexusCore.sufox.sbs/API公开文档.txt