通用说明

在逐个看接口之前，先了解平台的统一约定：返回体结构、状态码、时间戳、分页、字段命名。 这些约定在所有接口中一致，理解一次即可到处套用。

统一返回格式

平台的返回体有两种风格，取决于接口所属的服务模块：

风格 A：完整包装（大多数接口）

{
  "requestId": "4a994407-96e3-4072-8c9c-744ef9616d2a",
  "code": 200,
  "message": null,
  "data": { },
  "errorDetail": null,
  "timestamp": 1630550922261,
  "success": true
}

字段	类型	说明
requestId	String	本次请求的唯一标识（UUID）。报障时必须提供
code	Int	业务状态码，200 表示成功，见 错误码
message	String | null	提示信息；成功时可能为 null
data	Object | Array | null	业务数据，结构随接口而异
errorDetail	String | null	错误详情；成功时为 null
timestamp	Long	服务端响应时间戳（毫秒）
success	Boolean	便捷布尔判断，等价于 code == 200

风格 B：精简包装（实时与控制类接口）

部分实时控制接口只返回 code + data + message：

{
  "code": 200,
  "data": { "status": 1 },
  "message": "SuccessCode"
}

两种风格不要混用判断逻辑

• 风格 A 请判断 code == 200 或 success == true
• 风格 B 请判断 code == 200，且注意 message 的成功值是 "SuccessCode" 而不是 "success" 或 null
• 两种风格的 data 都可能为 null，取值前务必判空

建议的判成功写法（两种风格通用）

ok = resp.status_code == 200 and isinstance(body, dict) and body.get("code") == 200

不要用 if body.get("success") —— 风格 B 没有这个字段，会永远判为失败。

状态码约定

状态码	含义	处理建议
200	操作成功	正常处理 data
401	未授权	仅登录接口会返回；核对账号密码
403	请求拒绝	未携带凭证或凭证无效（HTTP 403）；换新凭证重试一次
404	未找到资源	检查 deviceCode / deviceId / stationId，或控制地址是否存在

本文档只给出了这 4 个状态码

接口文档末尾只列出了 200 / 401 / 403 / 404 四个。 本文档的 错误码 页在此基础上补充了通用 HTTP 状态码与排查建议， 补充部分已明确标注，请区分「文档定义」与「通用参考」。

时间戳约定

两种时间格式并存，按字段名区分

字段形态	格式	出现在哪些字段	示例
*Timestamp	毫秒级 Unix 时间戳（13 位整数）	startTimestamp、endTimestamp、timestamp	1659283200000
*Date / dateTime / createDate	字符串日期时间（yyyy-MM-dd HH:mm:ss）	dateTime、createDate、modifiedDate	"2022-08-01 16:56:17"

时区

平台暂未说明时区

接口文档未明确说明日期时间字段的时区。从示例数据与业务场景看应为中国标准时间（UTC+8）， 但请以实际返回与你所在地的观测结果为准。跨时区对接时请与运营方确认。

如何构造时间戳

# 今天 0 点（中国标准时间，毫秒）
date -d "$(date +%Y-%m-%d) 00:00:00" +%s000

# 当前时间（毫秒）
date +%s000

from datetime import datetime, timedelta

now = datetime.now()
start_of_today = now.replace(hour=0, minute=0, second=0, microsecond=0)

start_ms = int(start_of_today.timestamp() * 1000)
end_ms = int(now.timestamp() * 1000)
print(start_ms, end_ms)     # 1659283200000 1659369599000

import java.time.*;

long startMs = LocalDate.now()
        .atStartOfDay(ZoneId.systemDefault())
        .toInstant()
        .toEpochMilli();
long endMs = System.currentTimeMillis();

缺省行为

多数查询接口的 startTimestamp / endTimestamp 都是可选参数，缺省时平台会自动补：

• startTimestamp 缺省 = 当天 0 点
• endTimestamp 缺省 = 当前时间戳

分页约定

带分页的接口（/api/weather-data/list、/api/video-data/list）使用同一套参数与返回结构。

请求参数

参数名	类型	必填	默认值	说明
pageNumber	Int	否	1	页码，从 1 开始
pageSize	Int	否	10	单页数量，最大 100

返回结构

{
  "code": 200,
  "data": {
    "data": [],
    "pageNumber": 1,
    "pageSize": 10,
    "totalCount": 983
  },
  "timestamp": 1659344745407,
  "success": true
}

字段	类型	说明
data.data	Array	当前页的数据列表
data.pageNumber	Int	当前页码
data.pageSize	Int	当前页大小
data.totalCount	Int	总记录数（不是总页数）

分页的坑

• pageSize 超过 100 时行为暂未定义，请勿依赖，保持 ≤ 100
• 总页数需要自行计算：ceil(totalCount / pageSize)
• 注意 data.data 是双层嵌套——外层 data 是包装对象，内层 data 才是列表

字段类型说明

数字型字段在 JSON 里可能是字符串

平台的字段表把所有字段都标为 String，实际返回中：

• originValue、order、isValid、isBreakdown 等常以字符串形式返回（如 "0"、"1"）
• value、deviceId 等可能是数字

建议反序列化时对这些字段使用宽松类型（或字符串），再在业务层转换， 不要直接映射为强类型 Integer，否则会遇到反序列化失败。

常见字段命名规律

后缀 / 形态	含义
*Id	平台内部 ID（如 deviceId、stationId、customerId）
code	设备编码，16 位字符串，设备指令与实时数据都用它
name / displayName	名称；displayName 通常是前端的展示名（可能为空串）
*Type	类型枚举值
factor	传感器类型英文缩写，见 因子对照表
is*	布尔语义字段，取值多为字符串 "0" / "1"

id 与 code 不要搞混

• 查询类接口（站点、设备、历史、聚合、视频）用 id（或 deviceId / stationId）
• 实时与控制类接口（/api/sensor-data、/api/device_status、/api/get-value、/api/set-value）用 deviceCode

用错会返回「找不到资源」或空数据。两者的对应关系来自 /api/device 接口： id 与 code 在同一对象里同时返回。

请求通用要求

项	约定
编码	UTF-8
请求体	POST 接口使用 application/json
鉴权	Authorization: Bearer <token>，见 使用凭证
请求方式	查询用 GET，控制用 POST（不要用 GET 触发控制）
幂等性	查询接口幂等；控制接口不保证幂等（重复调用会重复下发）

关于控制接口的幂等性

POST /api/set-value 没有幂等保护——网络超时后重试可能导致指令重复下发。 生产实现请：

1. 设置合理超时（建议 ≥ 30s），避免过早判定失败
2. 超时后先用 /api/get-value 读回状态判断是否已生效，再决定是否重试
3. 记录每次下发的 deviceCode / address / value，便于追溯

下一步

• 完整错误码 → 错误码
• 开始调接口 → 站点列表