¶ Zectrix 极趣云平台 API 文档

已于 2026-10-13 按云平台 API 文档同步更新。后续变更请以云平台文档为准。

¶ 如何获取 API Key

1. 使用浏览器打开 极趣云平台，选择扫码登录。
2. 打开小程序，依次进入我的 → 扫一扫登录平台，扫描网页上的二维码完成登录。
3. 登录后，在平台菜单中进入开放 API。
4. 点击创建 API Key，按照页面提示完成创建，并妥善保存生成的 API Key。

API Key 相当于账号密码，请勿公开或分享给他人，也不要直接写入公开的代码仓库。

¶ 认证方式

当前云平台文档中，/open/v1/ 开放接口使用以下请求头认证：

X-API-Key: zt_your_key_here

JSON 请求体需设置 Content-Type: application/json。图片上传使用 multipart/form-data，由 HTTP 客户端自动生成 boundary。

¶ 基础信息

• API 基础地址: https://cloud.zectrix.com
• API 版本前缀: /open/v1/
• API Key: zt_xxx

---

¶ 一、设备管理

¶ 获取设备列表

• 方法: GET
• URL: https://cloud.zectrix.com/open/v1/devices

响应示例:

{
  "code": 0,
  "data": [
    {
      "deviceId": "AA:BB:CC:DD:EE:FF",
      "alias": "我的设备",
      "board": "bread-compact-wifi"
    }
  ]
}

curl 示例:

curl "https://cloud.zectrix.com/open/v1/devices" \
  -H "X-API-Key: zt_xxx"

---

¶ 修改同步周期

• 方法: PUT
• URL: https://cloud.zectrix.com/open/v1/devices/{deviceId}/sync-interval

curl 示例:

curl -X PUT "https://cloud.zectrix.com/open/v1/devices/AA:BB:CC:DD:EE:FF/sync-interval" \
  -H "X-API-Key: zt_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"syncInterval":60}'

响应示例:

{
  "code": 0,
  "msg": "success",
  "data": {
    "deviceId": "AA:BB:CC:DD:EE:FF",
    "syncInterval": 60
  }
}

---

¶ 二、待办事项

¶ 获取待办列表

• 方法: GET
• URL: https://cloud.zectrix.com/open/v1/todos

参数:

响应示例:

{
  "code": 0,
  "data": [
    {
      "id": 1,
      "title": "买牛奶",
      "description": "",
      "dueDate": "2026-03-20",
      "dueTime": "09:00",
      "repeatType": "none",
      "status": 0,
      "priority": 1,
      "completed": false,
      "deviceId": "AA:BB:CC:DD:EE:FF",
      "deviceName": "我的设备",
      "createDate": "2026-03-18 10:00:00",
      "updateDate": 1742284800
    }
  ]
}

---

¶ 创建待办

• 方法: POST
• URL: https://cloud.zectrix.com/open/v1/todos

请求体:

{
  "title": "买牛奶",
  "description": "",
  "dueDate": "2026-03-20",
  "dueTime": "09:00",
  "repeatType": "none",
  "priority": 1,
  "deviceId": "AA:BB:CC:DD:EE:FF"
}

请求体参数说明:

响应示例:

{
  "code": 0,
  "data": {
    "id": 1,
    "title": "买牛奶",
    "status": 0,
    "priority": 1,
    "deviceId": "AA:BB:CC:DD:EE:FF",
    "createDate": "2026-03-18 10:00:00"
  }
}

---

¶ 更新待办

• 方法: PUT
• URL: https://cloud.zectrix.com/open/v1/todos/{id}

路径参数:

请求体示例:

{
  "title": "买牛奶和面包"
}

请求体可更新字段:

响应示例:

{
  "code": 0,
  "data": {
    "id": 1,
    "title": "买牛奶和面包",
    "status": 0,
    "priority": 1
  }
}

---

¶ 标记完成/取消完成

• 方法: PUT
• URL: https://cloud.zectrix.com/open/v1/todos/{id}/complete

路径参数:

响应示例:

{
  "code": 0,
  "msg": "success"
}

---

¶ 删除待办

• 方法: DELETE
• URL: https://cloud.zectrix.com/open/v1/todos/{id}

路径参数:

响应示例:

{
  "code": 0,
  "msg": "success"
}

---

¶ 三、显示推送

¶ 推送图片到设备

• 方法: POST
• URL: https://cloud.zectrix.com/open/v1/devices/{deviceId}/display/image

路径参数:

请求参数（multipart/form-data）:

响应示例:

{
  "code": 0,
  "data": {
    "totalPages": 1,
    "pushedPages": 1,
    "pageId": "1"
  }
}

---

¶ 推送文本到设备

• 方法: POST
• URL: https://cloud.zectrix.com/open/v1/devices/{deviceId}/display/text

路径参数:

请求体:

请求体示例:

{
  "text": "今日天气：晴\n温度：25°C",
  "fontSize": 20,
  "pageId": "1"
}

响应示例:

{
  "code": 0,
  "data": {
    "totalPages": 1,
    "pushedPages": 1,
    "pageId": "1"
  }
}

---

¶ 推送标题+正文到设备

• 方法: POST
• URL: https://cloud.zectrix.com/open/v1/devices/{deviceId}/display/structured-text

路径参数:

请求体:

请求体示例:

{
  "title": "会议提醒",
  "body": "15:00 三楼会议室\n请带笔记本",
  "pageId": "1"
}

响应示例:

{
  "code": 0,
  "data": {
    "totalPages": 1,
    "pushedPages": 1,
    "pageId": "1"
  }
}

---

¶ 删除页面

• 方法: DELETE
• URL: https://cloud.zectrix.com/open/v1/devices/{deviceId}/display/pages/{pageId}

路径参数:

响应示例:

{
  "code": 0,
  "msg": "success"
}

---

¶ 错误码

---

最近同步日期：2026-10-13