V1 · 兼容通道

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}/ack
POST /api/v1/devices/tasks/{request_id}/result
GET  /api/v1/devices
GET  /api/v1/devices/{device_key}
POST /api/v1/devices/commands
GET  /api/v1/devices/{device_key}/commands/latest
GET  /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
需要新协议与 Kotlin/Java 客户端?切换至 API V2 文档 →

V1 网关首页 · 返回官网