物联网灌溉平台 API

POST GET 无需 access_token

参数	必填	说明
appid	是	AppId，示例：{APP_ID}
timestamp	是	Unix 时间戳（秒）
nonce	是	16~32 位随机字符串
sign	是	UPPER(MD5(appid+timestamp+nonce+appsecret))

返回字段

外层 code、msg 见响应规范。data 字段如下：

字段	类型	说明
access_token	string	访问令牌，前缀 oat_，业务接口携带此值
token_type	string	固定为 Bearer
expires_in	int	有效时长（秒），默认 7200

响应示例

{
  "code": 1,
  "msg": "获取成功",
  "data": {
    "access_token": "oat_xxxxxxxx",
    "token_type": "Bearer",
    "expires_in": 7200
  }
}

POST 需 access_token

Header 携带当前 X-Api-Token 或 Authorization: Bearer {access_token}，返回新的 access_token，旧令牌立即失效。

无请求体参数。

返回字段

与换取 Token相同，data 含 access_token、token_type、expires_in。

响应示例

{
  "code": 1,
  "msg": "刷新成功",
  "data": {
    "access_token": "oat_xxxxxxxx",
    "token_type": "Bearer",
    "expires_in": 7200
  }
}

POST 需 access_token

返回当前用户已绑定的工程列表。

无请求体参数。

返回字段

data 为数组，每项字段如下。调用其他接口时请使用 pid 作为 project_id。

字段	类型	说明
pid	int	工程 ID
project_name	string	工程名称
create_time	string	当前账号绑定该工程的时间

响应示例

{
  "code": 1,
  "msg": "获取成功",
  "data": [
    {
      "pid": 10,
      "create_time": "2025-01-01 12:00:00",
      "project_name": "测试工程"
    }
  ]
}

POST 需 access_token

参数	必填	说明
project_id	是	工程 ID

返回字段

data 为工程对象，含下属设备列表 equipments。

字段	类型	说明
id	int	工程 ID
name	string	工程名称
address	string	工程地址
status	int	工程状态
remark	string	备注
equipments	array	设备列表，每项字段见设备列表返回项，另含 device_type_image 图标 URL

POST 无需登录

一次性返回设备类型、闸门类型、灯光类型等配置，可用于对接初始化。

无请求体参数。

返回字段

字段	类型	说明
equipment_types	array	设备类型列表，每项含 id、name、nickname、image（图标 URL）
gate_type	array	闸门类型列表，每项含 id、name
dgTypeArr	array	灯光类型列表，每项含 id、name
kill_lamp_form_hint	object	杀虫灯表单说明（dg_type 灯管类型、timer_seconds 定时设置）
water_level_form_hint	object	水位仪表单说明（bind_equipment_id、water_calibration、C/h/F 等）
water_level_bind_hint	object	关联闸门规则说明（一扇闸一台水位仪）
water_level_reset_hint	object	重置原点角说明：api=POST /wlw/resetOriginAlpha，wait_seconds=30，note 含 30s 内勿混发查询提示

POST 需 access_token

参数	必填	说明
project_id	是	工程 ID
page	否	页码，默认 1
limit	否	每页条数，默认 10
name	否	设备名称模糊搜索
device_type	否	设备类型 ID 或名称
gate_type	否	闸门类型 ID 或名称
status	否	设备状态

返回字段

data 为设备对象数组；分页信息在 extend（count、page、limit，见响应规范）。

字段	类型	说明
id	int	设备 ID，API 参数 equipment_id 使用此值
project_id	int	所属工程 ID
name	string	设备名称
serial_number	int	设备序号，同工程内唯一，从 0 起递增
device_type	int	设备类型 ID
device_type_name	string	设备分类名称
device_type_nickname	string	设备分类别名
gate_type	int	闸门/设备子类型：1 滑板阀，2 溢流闸，3 渠道阀，4 杀虫灯，5 水位仪
percentage	int|float	当前开度 0～100（渠道阀 gate_type=3 状态/开度上报后写入；设开度后请轮询此字段）
longitude_latitude	string	经纬度
status	int	设备状态
vol	float	最新电压（V）
vol_time	string	最新电压获取时间
equipment_status	string	运行状态（闸门开/关/平/停，杀虫灯关/开/工作中等）
equipment_status_time	string	运行状态最新更新时间
other_attributes	string	其他属性（JSON 字符串，水位仪含 C/h/F/alpha_deg 等）
bind_equipment_id	int|null	水位仪关联闸门 ID
bind_relation_label	string	关联展示：水位仪行显示「闸门名（类型）」；闸门行显示「水位仪名（类型）」
bind_gate_label	string	水位仪绑定闸门展示
bind_water_level_label	string	闸门绑定水位仪展示
water_calibration	float	水位校准(mm)，同 JSON 内 h
water_level_params	object	解析后的 C/h/F、alpha_deg、depth_mm、beta_deg 等（仅水位仪）
alpha_deg	float	原点角 α（°），标定后写入
alpha_time	string	原点角 α 更新时间
alpha_calibrated	int	是否已标定 α：1 已标定，0 未标定
depth_mm	float	最新液位 H（mm）
depth_time	string	最新液位更新时间
beta_deg	float	浮球角 β（°）
dg_type	int	杀虫灯灯管类型 ID（1~8）
dg_type_name	string	灯管类型名称
lamp_params	object	杀虫灯扩展（lamp_status、定时秒数等）
lamp_status	string	杀虫灯状态，同 equipment_status
lamp_status_time	string	杀虫灯状态更新时间

POST 需 access_token

水位仪添加/编辑前拉取本工程下尚未被占用的闸门类设备。

参数	必填	说明
project_id	是	工程 ID
exclude_id	否	编辑水位仪时传自身设备 ID，保留当前已绑闸门

返回字段

data 为闸门数组，每项含 id、serial_number、name、gate_type_name。

POST 需 access_token

参数	必填	说明
project_id	是	工程 ID
equipment_id	是	设备 ID

返回字段

data 为单个设备对象，字段与设备列表返回项相同。

POST 需 access_token

参数	必填	说明
equipment_id	是	单个 ID 或逗号分隔多个，如 1,2,3
project_id	否	工程 ID，传入时会校验设备归属

返回字段

data 为设备对象数组（即使只查一个 ID 也返回数组），每项字段与设备列表返回项相同。指令下发后轮询本接口读取 depth_mm、lamp_status、vol_time、percentage（开度）等时，建议携带 project_id 校验归属。

POST 需 access_token

参数	必填	说明
project_id	是	工程 ID
name	是	设备名称
device_type	是	设备类型 ID
longitude_latitude	是	经纬度
gate_type	否	闸门类型：1 滑板阀，2 溢流闸，3 渠道阀（水位仪一般不必传）
bind_equipment_id	否	关联闸门设备 ID（可选），先调 /wlw/gateEquipments
water_calibration	建议填	水位校准(mm)，旧 H5 字段名，平台写入 other_attributes.h
dg_type	杀虫灯必填	灯管类型 ID，取值见 getEquipmentConfig.dgTypeArr（1 白光 … 8 青光）
lamp_tube_type	否	同 dg_type，兼容字段名
status	否	状态
other_attributes	否	高级：JSON 字符串（可含 C/F）

序号 serial_number 由系统自动递增（同一工程下从 0 起）。

返回字段

字段	类型	说明
id	int	新建设备 ID
serial_number	int	分配的设备序号
bind_equipment_id	int|null	关联闸门 ID（水位仪）
bind_gate_name	string	关联闸门名称
dg_type	int|null	灯管类型 ID（杀虫灯）
dg_type_name	string	灯管类型名称，如「紫光」

POST 需 access_token

参数	必填	说明
id	是	设备 ID
name	是	设备名称
device_type	是	设备类型 ID
longitude_latitude	是	经纬度
gate_type	否	闸门类型
bind_equipment_id	否	水位仪关联闸门 ID
water_calibration	否	水位校准(mm)
dg_type	杀虫灯必填	灯管类型 ID
lamp_tube_type	否	同 dg_type
status	否	状态
other_attributes	否	其他属性 JSON

返回字段

字段	类型	说明
id	int	已更新设备 ID

POST 需 access_token

参数	必填	说明
id	是	设备 ID

返回字段

成功时通常仅返回 code 与 msg，无 data。

POST 需 access_token

参数	必填	说明
project_id	是	工程 ID
equipment_id	是	设备 ID

返回字段

data 为指令对象数组，按设备类型与闸门类型过滤。发送指令时可使用 id（作为 command_id）或 english_name（作为 action）。

字段	类型	说明
id	int	指令 ID（虚拟点位为 0）
function_name	string	中文功能名，如「开闸」
english_name	string	英文动作名，如 open
command_type	int	适用类型：1~3 闸门，4 杀虫灯
remark	string	备注说明
virtual	int	可选；溢流闸固定点位为 1（无命令表 ID，用 english_name 下发）

溢流闸（gate_type=2）额外返回 overflow_ui（布局、hide_aperture、点位列表），详见溢流闸固定点位。

POST 需 access_token

参数	必填	说明
project_id	是	工程 ID
equipment_id	是	设备 ID
command_id	二选一	指令表 ID（兼容旧版）
action	二选一	英文动作名，见下方附录
aperture	条件	开度 0–100 整数；仅 action=aperture 且设备为渠道阀 gate_type=3 时必填，详见开度控制
timer_seconds	条件	定时秒数 1-65534，kill_lamp_timer_set 或 command=17 时必填

返回字段

字段	类型	说明
success_count	int	成功下发到的网关连接数
fail_count	int	失败数（保留字段，当前一般为 0）
total_count	int	本次尝试下发的连接总数
action	string	实际执行的动作名
equipment_id	int	目标设备 ID
project_id	int	目标工程 ID

响应示例

{
  "code": 1,
  "msg": "消息发送完成",
  "data": {
    "success_count": 1,
    "fail_count": 0,
    "total_count": 1,
    "action": "open",
    "equipment_id": 1,
    "project_id": 10
  }
}

水位仪说明

查液位请用 action=water_level_query 或 origin_angle_query（效果相同，回包当 β 算液位），下发后轮询 getEquipmentById 读 depth_mm / depth_time。

标定/重置原点角 α 请勿用本接口，须调用专用接口 POST /wlw/resetOriginAlpha。禁止传 reset_origin_angle_query / reset_origin_angle。

α 与 β 共用下行物理帧 4146{设备ID}0300000009。调用 resetOriginAlpha 后 30 秒内勿再对本设备发 water_level_query / origin_angle_query，否则回包意图可能错乱（后端会拒绝并发查询）。

约定摘要

项	说明
适用设备	仅 gate_type = 3（渠道阀）
动作	action=aperture
参数	aperture：整数 0～100（必填）
协议换算	下行 data 末字节 = 开度 + 4（十六进制）
急停	action=stop（与开度独立；渠道阀常见末字节 69，以命令表为准）
回写字段	设备上报后主表 percentage 更新；对接方轮询 getEquipmentById / 设备列表即可

换算对照（验收）

开度 %	末字节 hex	说明
0	04	关到位侧
50	36	中间开度
100	68	开到位侧

单台设开度

POST /wlw/sendMessage（需 access_token）

project_id=10&equipment_id=12&action=aperture&aperture=30

{
  "project_id": 10,
  "equipment_id": 12,
  "action": "aperture",
  "aperture": 30
}

sendMessage 成功只表示指令已发出，不代表设备已到位。成功后请轮询设备 percentage（建议间隔 1～2 秒，超时 15～30 秒）。

批量设开度

POST /wlw/sendMessageBatch

project_id=10&equipment_ids=12,15&action=aperture&aperture=50

• 所选设备须全部为渠道阀，否则整批拒绝。
• 本批次共用同一 aperture；接口立即返回，后台按队列串行下发。
• 结果靠轮询各设备 percentage / 通讯记录 / 回调。

H5 / 小程序界面建议

1. 仅当 gate_type === 3 时展示开度与「设开度」按钮。
2. 展示当前 percentage（无则 -）。
3. 点击「设开度」→ 输入 0～100 → 调 sendMessage → 轮询更新 percentage。
4. 非渠道阀不要展示设开度入口。

常见错误（开度）

msg	处理
当前设备不是渠道阀（gate_type!=3），不支持开度控制	仅对渠道阀调用；界面按 gate_type 隐藏入口
开度指令需要 aperture 参数，且范围0-100	补传整数 aperture
开度批量下发仅支持渠道阀（gate_type=3）…	批量列表勿混入非渠道阀

约定摘要

项	说明
适用设备	仅 gate_type = 2
开度滑条	不支持 aperture（请隐藏）
平闸	不支持 flat
停	action=stop，末字节 69（非命令表通用 03）
布局建议	左开75/50/25；中 开|停|关；右溢流高/中/低

点位 → action → 末字节

点位	action	末字节
溢流低	overflow_low	04
溢流中	overflow_mid	12
溢流高	overflow_high	21
关闭	close / overflow_close	2F
开25%	open_25	3D
开50%	open_50	4B
开75%	open_75	5A
全开	open / overflow_full	68
停	stop / overflow_stop	69

注意：溢流闸上 close=2F（关闭），不是旧习惯的 04（现为溢流低）；stop=69，不是通用闸门 03。

下发示例

POST /wlw/sendMessage

{
  "project_id": 10,
  "equipment_id": 12,
  "action": "overflow_low"
}

/wlw/commands 对溢流闸会返回虚拟点位及 overflow_ui（含布局与 hide_aperture）。

POST 需 access_token

水位仪标定/重置原点角 α 的专用同步接口。下发 reset_origin_angle_query 并阻塞等待设备回包，最长 30 秒。成功时直接返回更新后的 alpha_deg、alpha_time 及完整 equipment 对象。

参数	必填	说明
project_id	是	工程 ID
equipment_id	是	水位仪设备 ID

返回字段（data）

字段	类型	说明
alpha_deg	float	更新后的原点角 α（°）
alpha_time	string	原点角更新时间
wait_seconds	int	同步等待上限，默认 30
equipment	object	完整设备对象（字段同设备列表）

成功响应示例

{
  "code": 1,
  "msg": "原点角 α 已更新为 21.9727°",
  "data": {
    "alpha_deg": 21.9727,
    "alpha_time": "2026-07-07 11:32:28",
    "wait_seconds": 30,
    "equipment": {
      "id": 56,
      "alpha_deg": 21.9727,
      "alpha_time": "2026-07-07 11:32:28",
      "alpha_calibrated": 1
    }
  }
}

POST 需 access_token

参数	必填	说明
project_id	是	工程 ID
equipment_ids	是	设备 ID 数组，或 JSON 字符串 / 逗号分隔；最多 50 个
action	是	英文动作：open / close / flat / stop / status / voltage / current 等
aperture	条件	仅 action=aperture 时必填（0–100）；所选须全部为渠道阀，详见开度控制

返回字段

字段	类型	说明
batch_id	string	本批次 ID（便于后台排查队列表）
queued_count	int	已入队条数
project_id	int	工程 ID
action	string	本次动作

响应示例

{
  "code": 1,
  "msg": "已加入下发队列，将按顺序逐台发送；执行结果请通过回调通知接收",
  "data": {
    "batch_id": "a1b2c3...",
    "project_id": 1,
    "action": "open",
    "queued_count": 50
  }
}

POST 需 access_token

参数	必填	说明
project_id	是	工程 ID
action	是	open / close / flat / stop，或 broadcast_open 等

兼容写法：POST /wlw/sendMessage + mode=broadcast（可不传 equipment_id）。

示例

project_id=10&action=open

POST 需 access_token

参数	必填	说明
project_id	是	工程 ID

返回分组列表及成员 equipment_ids / 序号等。

POST 需 access_token

参数	必填	说明
project_id	是	工程 ID
id	否	有则更新，无则新建
name	是	分组名称
code	否	分组编号
sort	否	排序
equipment_ids	否	成员设备 ID 列表（数组或逗号分隔）

POST 需 access_token

参数	必填	说明
project_id	是	工程 ID
id / group_id	是	分组 ID

POST 需 access_token

参数	必填	说明
project_id	是	工程 ID
record_type	是	voltage / current / position / time / status / reply / water_level / sensor
equipment_id	否	设备 ID
device_code	否	设备序号 / 采集仪地址
page / limit	否	分页，limit 最大 100

record_type=sensor 时重点字段：collector_id、channel_count、channels_json、extra_data。

V2.5 2026-09

• 溢流闸固定点位：gate_type=2 支持 8 停点（溢流低/中/高、关闭、开25/50/75%、全开）；不建表；见溢流闸固定点位。

V2.4.2 2026-09

• 回执补发收敛：仅 4146 指令字节 01 超时原帧重发；非 01（如查状态 03）不补发。

V2.4.1 2026-09

• 补偿策略调整：仅操作超时重发原控制；查询一律不补发。时序仍为 5s / 5s / 最多 3 次。回调规则同 V2.4（有回传推状态，满次推设备异常）。

V2.4 2026-09

• 指令回执补偿：凡有回执的命令，5s 无上行则同网关补偿（V2.4 时操作曾补对应查询；自 V2.4.1 起改为重发原指令）。成功按现网回调，满次无回执推送设备异常终态。覆盖闸门/灯/水位/智能开关/传感器；广播不适用。

V2.3 2026-08

• 入口拆分：用户客户端（/h5/）与用户开放平台（对接文档免登录 /openapi + 工作台需密钥 /client）。
• 广播群控：sendBroadcast（或 sendMessage + mode=broadcast）；设备域 ffffffff，无回执。
• 设备分组：groups / groupSave / groupDelete；组控走 sendMessageBatch。
• 传感器：gate_type=6，EB55/EB5A；action 见新设备类型；历史 record_type=sensor。
• 流量计：gate_type=7，设备详情返回 k/k1/s/s1（K=K1×S/S1）。
• 智能开关：gate_type=8，open/close，帧设备域固定 ffffffff。
• 其它：夜间巡检跳过离线网关；24V 电压按 2 字节解析。

V2.2 2026-07

• 渠道阀开度：支持设置开度 0～100（单台 / 批量），设备信息返回当前开度 percentage。详见开度控制。
• 闸门数据更准确：开闸位置、保护时间（分钟）、上行/下行阻断电流等解析与展示已校正。
• 夜间自动巡检：夜间自动查询闸门状态与电压；异常可标记故障或缺电，便于次日查看。

V2.1 2026-07

• 杀虫灯：支持开关、定时、状态查询；设备信息可返回灯管类型、灯光状态等字段。
• 水位仪：支持液位查询、可选关联闸门；提供重置原点角专用接口；设备信息可返回液位、原点角等字段。
• 批量控制：支持对多台闸门设备一次下发相同动作（如全开 / 全关）。