快速开始

本节用 5 分钟带你跑通第一个接口：登录拿 token → 拉站点列表 → 拉某台设备的实时温湿度。

前置条件

• 已从平台运营方获得一个可用账号（用户名 + 密码）
• 本机可访问外网，已安装 curl（或 Postman / 任意 HTTP 客户端）
• 已知要查询的设备编码 deviceCode（16 位字符串，如 0010202204210071）

第 0 步：确认你要调哪个域名

你要做的事	域名
登录、查站点、查设备、查历史/聚合数据、查视频、查全量在线状态	yunshangwenshi.auto-control.com.cn
查实时传感器数据、查单设备在线状态、读写控制参数、下发控制指令	mqtt.iot.auto-control.com.cn

详见 环境与域名说明。

第 1 步：登录，拿到 token

curl -X POST 'https://yunshangwenshi.auto-control.com.cn/api/account/sign-in' \
  -H 'Content-Type: application/json' \
  -d '{"username": "<你的账号>", "password": "<你的密码>"}'

返回体中的 data.token 就是后续所有请求要带的访问凭证：

{
  "requestId": "54f39cd5-dbe1-4026-89de-841665b7b5c3",
  "code": 200,
  "message": null,
  "data": {
    "userId": 6,
    "customerId": 1586272542,
    "username": "奥托测试",
    "authorities": ["ROLE_ADMIN"],
    "token": "eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJ...<已截断>",
    "tokenType": "Bearer"
  },
  "errorDetail": null,
  "timestamp": 1626837675080,
  "success": true
}

把 token 存进环境变量，后面所有示例都能直接复用：

export IOT_TOKEN='eyJhbGciOiJIUzUxMiJ9...'

完整说明见 获取访问凭证。

第 2 步：拉站点列表

curl 'https://yunshangwenshi.auto-control.com.cn/api/station' \
  -H "Authorization: Bearer <token>"

从返回的 data[].id 里挑一个站点 ID（例如 5819），并记下它的 name。

# 只看站点 id 与名称，便于阅读
curl -s 'https://yunshangwenshi.auto-control.com.cn/api/station' \
  -H "Authorization: Bearer <token>" \
  | jq '.data[] | {id, name, deviceCount}'

第 3 步：拉该站点下的设备

curl 'https://yunshangwenshi.auto-control.com.cn/api/device?dataType=TEXT' \
  -H "Authorization: Bearer <token>" \
  | jq '.data[] | select(.stationId == 25) | {id, code, name, deviceTypeName}'

拿到设备编码 code（这就是接口里到处用的 deviceCode）。

第 4 步：读这台设备的实时数据

注意换域名了：

curl 'https://mqtt.iot.auto-control.com.cn/api/sensor-data?deviceCode=0010202204210071' \
  -H "Authorization: Bearer <token>"

{
  "code": 200,
  "data": [
    {
      "name": "空气温度",
      "order": 0,
      "isBreakdown": "0",
      "isTarget": "0",
      "isValid": "1",
      "isWeatherStation": "1",
      "originValue": 667,
      "value": 26.7,
      "unit": "℃",
      "factor": "atc",
      "dateTime": "2022-08-01 16:56:17",
      "sensorType": "1"
    },
    {
      "name": "空气湿度",
      "order": 0,
      "isBreakdown": "0",
      "isTarget": "0",
      "isValid": "1",
      "isWeatherStation": "1",
      "originValue": 480,
      "value": 48.0,
      "unit": "%",
      "factor": "ahc",
      "dateTime": "2022-08-01 16:56:17",
      "sensorType": "2"
    }
  ],
  "message": "SuccessCode"
}

到这里，一个完整的「登录 → 找站点 → 找设备 → 读数据」链路就跑通了。

第 5 步（可选）：读控制参数、画曲线

# 读这台控制器当前的一级风机/湿帘等状态
curl 'https://mqtt.iot.auto-control.com.cn/api/device_status?deviceCode=2022070314150044' \
  -H "Authorization: Bearer <token>"

# 查今天按小时聚合的空气温度曲线（注意这是业务域名）
curl 'https://yunshangwenshi.auto-control.com.cn/api/weather-data/avg?deviceId=8138&fields=atc,ahc&groupType=HOUR' \
  -H "Authorization: Bearer <token>"

常见问题

返回 403 / 未授权

1. 检查请求头是否为 Authorization: Bearer <token>，Bearer 与 token 之间必须有一个空格
2. 检查 token 是否有效 → 见 使用凭证
3. 检查是否复制了完整 token（JWT 有三段，以 . 分隔，容易截断）

返回 403 / 请求拒绝

账号本身有效，但没有访问该资源的权限。请确认：

• 该设备/站点是否属于你的 customerId
• 账号是否为子账号且未被授权该模块
• 联系方式：联系平台运营方核对账号权限

取不到数据（data 为空数组）

1. 该设备当前确实无上报（可用 /api/mqtt-client-status 查在线状态）
2. deviceCode 写错（务必用设备列表接口返回的 code，不要用 id）
3. 站点下没有设备（deviceCount 为 0）

下一步 → 接入流程 了解正式对接需要走哪些环节，或直接跳到 接口文档。