ZenovaConnect

为你自己的能源应用接入设备数据

ZenovaConnect 面向已经在构建能源软件的团队:监控 SaaS、资产运营平台、VPP、EMS、储能聚合、工商业能碳平台或集团内部数字化系统。你不需要按厂商分别写解析器。我们把不同设备来源归一成稳定的实体、点位、告警和时序数据结构,然后通过你选择的通道推送。

5 步上手

申请 API Key → 加厂商凭据 → 注册 Webhook → 接收数据 → 扩展到更多厂商。

  1. 申请 API Key

    提交联系表单,售前会在 1 个工作日内给你发放接入账号(账号密码 + 测试环境)。Free tier 可申请 10 设备的永久配额。

  2. 把厂商凭据交给我们

    申请账号后,先用账号密码换 access_token,后续所有接口都用这个 token 通过 Authorization 头携带:

    add-vendor.sh
    # 申请凭据后,先用账号密码换 token
    curl -X POST 'https://api.zenovaconnect.com/sol-emqx/login' \
      -d 'username=YOUR_USERNAME' \
      -d 'password=YOUR_PASSWORD'
    
    # 响应:
    # {
    #   "success": true,
    #   "code": 200,
    #   "result": { "access_token": "eyJ..." }
    # }
  3. 注册接收 Webhook

    拿到 token 之后,把厂商账户(在厂商开发者平台申请到的凭据)交给我们,然后调用同步接口拉取该账户下的所有电站和设备:

    register-webhook.py
    import requests
    
    TOKEN = "eyJ..."
    headers = {"Authorization": f"Bearer {TOKEN}"}
    
    # 同步某个厂商账户下的电站和设备
    resp = requests.get(
        "https://api.zenovaconnect.com/apiDevice/syncApiPlantAndDevice",
        headers=headers,
        params={"dataAccessUserId": "your-account-id"}
    )
    
    plants = resp.json()["result"]
    print(f"同步了 {len(plants)} 个电站")
  4. 接收推送数据

    实现一个 Webhook endpoint,我们会按统一 BaseData schema 把设备数据推过来。先验 HMAC 签名,再处理数据:

    receive-webhook.js
    // 你的 Webhook endpoint,接收 ZenovaConnect 推送的设备数据
    app.post('/webhooks/zenova', (req, res) => {
      const payload = req.body;
    
      // 验证签名 (HMAC-SHA256)
      const sig = req.headers['x-zenova-signature'];
      if (!verifyHmac(payload, sig, process.env.ZENOVA_SECRET)) {
        return res.status(401).end();
      }
    
      // payload 是统一 BaseData schema
      const { DataSources, InverterSN, EDay, PowerACOutputActive } = payload;
      console.log(`[${DataSources}] ${InverterSN} 当日 ${EDay} kWh`);
    
      res.status(200).end();
    });
  5. 扩展到更多厂商

    对接更多厂商账户只需重复 Step 3,系统已经原生支持 15 家厂商(华为、阳光、固德威、锦浪、古瑞瓦特、上能、爱士惟、首航、禾望、昱能、麦田、思格云、禾迈、益邦阳光、海康)。批量管理设备、按电站组织数据、监听设备上下线事件——都通过 OpenAPI 完成。

统一 Schema

无论来自哪家厂商,你拿到的字段、单位、精度都一样。

为什么这件事重要?

15+ 家厂商有 15 种字段命名、15 种单位、15 种时区策略。我们把它们消化成一套 50+ 字段的 BaseData schema 推给你——你写一次解析就够了,接新厂商不用改你这边的代码。

下面是两条来自不同厂商的真实结构样例(BaseData schema)。50+ 字段覆盖逆变器、采集器、组件级运行数据 · 三相电压电流(UAC1/IAC1/UAC2/IAC2/UAC3/IAC3)+ 多路 MPPT(UPV1/IPV1...)+ 告警数组——注意 DataSources 标明数据从哪家拉取,InverterSN 是真实设备 SN,其他字段在所有厂商上一致:

来自固德威(SEMS Portal)

goodwe-payload.json
{
  "deviceType": "inverter",
  "CollectorSN": "C1234567890",
  "InverterSN": "INV20250526001",
  "DataSources": "goodwe",
  "Timezone": "GMT+8",
  "Datetime": 1748246400,
  "currentDateTime": "2026-05-26 12:00:00",
  "State": "1",
  "StateDesc": "正常发电",
  "EDay": 35.6,
  "ETotal": 128500.8,
  "PowerACOutputActive": 8.75,
  "Temperature": 42.5,
  "FrqAC": 50.01,
  "UAC1": 231.5,
  "IAC1": 12.6,
  "UPV1": 620.5,
  "IPV1": 9.8,
  "AlertArray": [],
  "turnonTime": "2026-05-26 06:30:00"
}

来自华为(FusionSolar)

huawei-payload.json
{
  "deviceType": "inverter",
  "CollectorSN": "C9876543210",
  "InverterSN": "INV20250526002",
  "DataSources": "huawei",
  "Timezone": "GMT+8",
  "Datetime": 1748246400,
  "currentDateTime": "2026-05-26 12:00:00",
  "State": "1",
  "StateDesc": "正常发电",
  "EDay": 41.2,
  "ETotal": 215800.4,
  "PowerACOutputActive": 9.12,
  "Temperature": 38.9,
  "FrqAC": 49.99,
  "UAC1": 230.8,
  "IAC1": 13.2,
  "UPV1": 615.7,
  "IPV1": 10.1,
  "AlertArray": [],
  "turnonTime": "2026-05-26 06:28:00"
}

BaseData 50+ 字段、ts 时区、单位(kWh / kW / V / A / Hz / °C)在所有厂商上都一致。你的解析逻辑写一次就够了——DataSources 字段会告诉你这条数据来自哪家厂商,排查时一目了然。

BaseData Schema 字段表(节选)
字段类型说明
deviceTypestring设备类型(逆变器固定为 "inverter")
DataSourcesstring数据来源(huawei / sungrow / goodwe ... 与 /protocols 矩阵一致)
InverterSNstring逆变器序列号(厂商原生 SN)
Datetimelong采样时间戳(秒级 Unix);另有 currentDateTime 给出可读时间
State / StateDescstring逆变器状态码 + 中文描述,例如 "1" / "正常发电"
EDaydouble当日发电量(kWh)
ETotaldouble累计发电量(kWh)
PowerACOutputActivedouble当前交流有功输出(kW)
UAC1 / UAC2 / UAC3double三相交流电压(V)— 工业级三相数据
IAC1 / IAC2 / IAC3double三相交流电流(A)
UPV1 ~ UPV32double组件级直流电压(V),最多 32 路
IPV1 ~ IPV32double组件级直流电流(A),最多 32 路
Temperaturedouble逆变器机壳温度(°C)
AlertArray / WarnArray / StatusArrayarray告警 / 警告 / 状态数组,结构原样透传

推送通道

选你最舒服的通道接收数据。HTTP、Kafka、MQTT 任选。

HTTP Webhook

最通用,任意语言 / 平台都能接。

适合快速接入和中小规模 SaaS。

security:
TLS 1.3 + HMAC
throughput:
10k req/s

Apache Kafka

高吞吐场景,适合 SaaS 集群消费。

适合多消费者、数据平台和事件驱动架构。

security:
SASL_SSL + TLS
throughput:
100k msg/s

MQTT 5.0

IoT 标准协议,低带宽友好。

适合实时订阅、边缘或物联网场景。

security:
TLS + ACL + JWT
throughput:
30k msg/s

送达语义:签名、重试、幂等

下游系统拿到的每一条 payload 都带签名、可重放、有幂等键。下面是接入时要处理的三件事。

HMAC 签名验证

Webhook 请求带 X-ZenovaConnect-Signature 头,使用 HMAC-SHA256 + 你的接入 secret 对 raw body 签名。Kafka 走 SASL_SSL + TLS、MQTT 走 TLS + JWT/ACL,不需要再加签名。你的接收端必须在处理前先验证签名,签名错误返回 401。

重试策略

Webhook 在 2xx 之外的响应或超时 (默认 10s) 会按指数退避重试,最多 8 次,跨度约 24 小时。Kafka 走原生 ack + 消费者位点,我们重投至 ack 成功。MQTT 走 QoS 1,broker 自动重传。请你的处理端保证幂等。

幂等键 (idempotency_key)

每条 payload 自带 idempotency_key (来源: vendor + device_id + ts),全网唯一。重试到来时这个键不会变,你只需要在 DB 或 Redis 用这个键去重即可。同一台设备的同一时间戳事件,只会被处理一次。

准备开始?

申请技术对接,售前会在 1 个工作日内联系你,发放测试 API Key 与凭据配置指引。

申请技术对接