储能设备APP与数据后台开发前，需要准备哪些接口资料？

点表里少一列倍率，APP就可能把62.4%显示成624%；功率方向少一句定义，后台会把放电曲线画成充电。储能软件开发最怕的不是没有接口，而是拿到一个能连上、却解释不清的数据口。

设备厂家确认支持Modbus TCP、MQTT或HTTP，只说明双方大致用什么方式通信，并没有说明某个寄存器代表簇电压还是单体电压，也没有说明功率正负值、字节序和异常值怎么解释。连接成功只是第一步，离“数据可用”还很远。

对APP和数据后台来说，读到一个数并不难，难的是确认这个数属于哪台设备、在什么时间产生、单位是什么、当前是否可信，以及用户下发命令后设备究竟有没有执行。开发前准备接口资料，目的就是把这些问题提前说清楚。

先把接入边界画出来，再谈接口

一套储能系统里，通常不只有电池。BMS、PCS、EMS、电表、空调、消防、液冷、门禁、环境传感器和视频设备，可能来自不同厂家，也可能分别接到站控层、边缘网关或厂商云。APP看到的“一个储能柜”，在后台很可能对应多层设备和几千个测点。

因此，项目最先需要的不是一份孤立的API文档，而是一张能够核对的数据链路图。图里至少要看清：

• 现场有哪些设备，品牌、型号、数量、序列号规则和当前固件版本分别是什么。
• 电池系统按电站、储能单元、电池舱、簇、PACK、单体怎样分层，设备编号如何对应现场铭牌。
• 各设备通过RS485、CAN、以太网还是其他方式接入，经过哪个采集器、网关、EMS或厂家云。
• APP与数据后台是直连现场网关、调用现有EMS接口，还是对接设备厂商云平台。
• 哪一端是各类数据的权威来源。例如SOC以BMS为准，充放电功率以PCS还是关口电表为准，累计电量是否需要用于结算。
• 哪些数据只读，哪些参数允许远程设置，哪些命令必须留在站内操作。
• 现场网络是公网、专线、VPN还是内外网隔离，服务器部署在公有云、企业私有云还是站内。

如果项目有多个设备品牌，不能用一句“协议都一样”带过。即便都使用Modbus，不同型号的寄存器地址、量程、状态码和控制条件也可能完全不同；同一型号升级固件后，点表也可能增加或改动。设备型号和协议版本必须一一对应。

点表要细到开发人员不用猜

点表是设备接入最核心的资料。产品彩页能说明设备有哪些能力，却不能直接用来解析数据。可开发的点表至少应包含以下字段：

例如，一个标为SOC的字段还不够。需要继续确认它是整站、储能单元、簇还是PACK级SOC；原始值856是否代表85.6%；通信中断时设备会保留上次值、返回特定异常值，还是直接不响应。APP是否显示“小数一位”，只是页面问题；数据本身是否还能用，则是接口语义问题。

功率和电量尤其容易出错。充电功率为正还是放电功率为正，厂家做法并不统一；累计充电量是设备生命周期累计、每日清零还是按一次充放电过程累计，也必须说明。只要这类口径没有写进资料，后台图表即使能画出来，也未必代表真实运行情况。

截至2026年7月，国家标准平台将GB/T 34131-2023《电力储能用电池管理系统》和GB/T 36558-2023《电力系统电化学储能系统通用技术条件》列为现行标准。它们可以作为系统和设备技术边界的核对入口，但具体项目仍然要取得厂家针对型号、固件和协议版本提供的点表。国家标准不能替代设备寄存器表，也不能替代项目双方对数据口径的确认。

不同通信方式，各自还缺哪些资料

使用Modbus RTU或Modbus TCP

除了寄存器表，还要提供站号或Unit ID、串口波特率、数据位、停止位、校验方式、TCP端口、支持的功能码、寄存器地址采用零基还是一基表示，以及多字节数据的字节序和字序。

读写限制也要写出来，包括一次最多连续读取多少寄存器、轮询太快是否会触发设备保护、通信超时多长、异常码怎样处理、写入后通过哪个状态点确认生效。很多联调问题并不是设备没有数据，而是地址偏了一位，或者两个16位寄存器拼成32位数时顺序相反。

使用MQTT上传数据

需要准备Broker地址和端口、TLS要求、客户端标识规则、用户名或证书鉴权方式、Topic清单、发布与订阅方向、QoS、Retain、遗嘱消息、心跳、重连和离线缓存机制。每个Topic都应带完整JSON或二进制报文示例，并说明字段是否可能缺省、消息是否会重复、设备时间和平台接收时间分别怎样记录。

MQTT 5.0规范定义了发布/订阅协议本身，但不会替具体储能项目决定Topic命名、设备身份、业务字段和断网补传规则。这些仍然属于厂商接口资料。

使用HTTP API或厂家云接口

需要提供测试与生产环境地址、鉴权流程、令牌有效期、签名算法、请求方法、请求与响应结构、状态码、错误码、分页、限流、幂等、回调签名和重试规则。站点、设备、实时数据、历史曲线、告警、报表和控制命令分别有哪些接口，也要列成完整目录。

接口文档最好提供机器可读的OpenAPI文件，并附上能够直接执行的请求示例。截至2026年7月，OpenAPI Specification最新发布版本为3.2.0。项目不一定非要采用这个版本，但文档至少要做到字段类型、必填项、示例、错误响应和鉴权方式能够被开发与测试共同核对，不能只放几张截图。

如果使用IEC 60870-5-104或IEC 61850，还应提供信息体地址或SCL配置文件、逻辑节点和数据对象映射、数据集、报告控制块、品质位与时间品质说明。这里同样不能停在“支持104”或“支持61850”这句话上。

控制接口必须和遥测数据分开确认

查看SOC、温度和功率，与远程启停、模式切换、功率设定不是同一个风险等级。红数科技在项目启动评审时，会把控制接口单独拉出一张命令矩阵，不把它混在普通点表里。

这张矩阵需要说明：谁能操作、设备处于什么状态时允许操作、设定值范围是多少、是否需要二次确认、命令受理后怎样查询执行结果、超时后能否重发，以及被设备拒绝时会返回什么原因。常见命令包括PCS启停、有功和无功设定、充放电模式切换、告警复位、空调控制与策略下发。实际开放范围应以设备安全要求和项目授权为准。

控制返回“成功”也要继续拆开。它可能表示平台已经收到请求，也可能表示命令已经发到网关，未必代表设备完成动作。可靠的接口应能区分受理、下发、设备确认、执行完成和执行失败，并用同一个命令编号串起全过程。

远程控制还要提前确定这些安全条件：

• 用户、角色、项目、站点和设备之间的授权关系，不能只判断用户是否登录。
• 高风险命令是否要求复核、短时有效凭证或站内授权。
• 每次操作记录操作者、目标设备、原值、设定值、时间、结果和失败原因。
• 同一命令重复提交时怎样保证幂等，网络超时后是否允许自动重试。
• APP账号停用、项目移交和人员离职后，权限怎样及时回收。

OWASP API Security Top 10 2023把对象级授权、身份认证和功能级授权问题列为主要API风险。放到储能后台里，就是不能因为用户知道一个设备ID，便允许他查询或控制那台设备；也不能只在APP按钮上隐藏功能，后台接口本身必须逐次校验权限。

告警资料不能只有一个故障码列表

设备把故障码传上来，只解决了“发生过什么”。APP和运维后台还要知道这条告警何时产生、是否仍在持续、严重到什么程度、影响哪一层设备，以及在什么条件下恢复。

一份可用的告警表，应包含告警编码、名称、来源设备、级别、触发条件、恢复条件、是否锁存、是否允许远程复位、可能影响和建议处置。温度过高、单体压差大、绝缘异常、通信中断、PCS停机和消防动作不能全部显示成同一种红色提示，更不能由开发人员根据名称猜级别。

还要确认告警是设备主动上送，还是平台轮询状态后自行判断；同一故障是否会重复上送；短时间抖动需不需要防抖；设备恢复后会发送恢复事件，还是只能通过状态点反查。告警产生时如果需要保存SOC、温度、功率等现场快照，也应在接口和存储方案里提前约定。

历史曲线最怕时间和口径没有统一

实时页面看起来正常，历史曲线仍可能出现断点、重复、倒序和跨天偏移。开发前要明确设备时间、网关时间和服务器时间分别从哪里校准，接口使用本地时间还是UTC，时间戳精确到秒还是毫秒。跨地区部署时，时区必须作为明确字段或统一采用带偏移量的时间格式，不能靠服务器所在地猜。

数据存储也需要一张规则表：哪些测点保存原始值，采样周期是多少；哪些数据按变化保存；断网缓存多长时间；补传数据如何去重；日报、月报按什么粒度聚合；原始数据、分钟数据和报表数据分别保留多久。通信中断时，平台应展示缺数还是延用上次值，要按数据用途决定。对温度、功率等运行数据，长时间沿用旧值却不标记质量，容易让用户误以为设备仍在正常上报。

如果后台需要计算充放电量、收益、效率、等效循环次数或可用率，还应取得每个指标的公式、输入点位、统计周期、边界条件和舍入规则。指标名称相同，不代表各方计算口径相同。验收时最好用一段确定的原始数据手工复算，确认后台结果与约定一致。

APP和数据后台自身的接口资料，也要同时准备

设备接入只是底层。APP和后台还要处理组织、项目、站点、设备、用户、角色、消息、工单和报表。开发前需要确定这些对象的层级和关系：一个用户能否属于多个企业，一个站点能否由不同运维单位共同查看，设备迁站后历史数据跟随设备还是留在原站点，项目移交后原账号还能看什么。

如果已经有ERP、企业微信、统一身份认证、运维工单、短信、地图或第三方算法平台，需要同步提供对方接口文档、测试账号、白名单、回调规则和数据责任边界。APP要收集手机号、位置、设备照片或推送标识时，应提前列清用途、必要性、保存期限、删除方式和授权页面。可参考现行的GB/T 35273-2020《信息安全技术 个人信息安全规范》，并结合项目适用的法律、等保要求和企业安全制度落实；不能等上线审核时再补隐私和权限设计。

没有测试条件，再完整的文档也只能算纸面准备

正式排期前，项目方应准备可持续使用的测试环境。现场设备可以是测试柜、实验台或经过授权的真实站点；暂时无法提供实机时，应有厂家认可的模拟器或网关测试环境。测试设备的型号、固件和协议版本要与计划上线的设备一致。

一起交付的联调资料通常包括：

• 测试设备或模拟器的访问条件，测试站点、设备编号和账号权限。
• 正常通信的原始报文、API请求与响应样例，以及一段可用于回放的数据。
• 证书、密钥、令牌和白名单的安全交接方式，不把生产密钥写进普通需求文档。
• 网关和设备日志的获取方式，时间同步状态，以及接口问题由哪一方判断。
• 正常启停、设定值越界、设备拒绝、通信中断、重复消息、数据补传、告警产生与恢复等测试场景。
• 协议变更流程，包含版本号、变更内容、兼容范围、通知时间和回退方案。

联调不能只看APP上有没有数字。至少要同时核对四处：设备实际状态、设备或网关原始报文、后台解析结果、APP显示结果。控制场景还要加上操作日志和设备回执。五处一致，才说明链路真正跑通。

什么状态才算资料齐了

项目可以用下面这张表做开工检查。资料名称不必完全一致，但验收结果要能达到同样的颗粒度。

如果设备厂家只能提供宣传资料，点表没有适用版本，控制命令没有设备回执，或者项目现场没有任何可测试条件，就不适合直接承诺完整工期。此时更实际的做法是先做接口预研：用一台设备跑通身份识别、实时数据、告警和一个受控命令，把数据口径和异常路径确认下来，再锁定APP与后台范围。

界面原型可以在资料整理期间同步推进，但设备接入、数据模型和控制流程不能靠原型替代。把同一段原始报文分别交给设备厂家、平台开发和测试人员，三方能够得到相同的设备状态、时间和业务结果，这套资料才到了可开发的程度。

核验依据

• GB/T 34131-2023《电力储能用电池管理系统》
• GB/T 36558-2023《电力系统电化学储能系统通用技术条件》
• GB/T 35273-2020《信息安全技术 个人信息安全规范》
• OASIS：MQTT Version 5.0
• OpenAPI Specification 3.2.0
• OWASP API Security Top 10 2023