FranklinWH API 文档
完整的 API 参考文档，帮助您快速集成 FranklinWH 储能设备
API v2.0
稳定版
OpenAPI 3.0
概述
FranklinWH API v2.0 提供 RESTful 接口，让您可以访问储能设备的实时数据、管理告警、配置设备设置等。 所有 API 使用 HTTPS 协议，返回 JSON 格式数据。
Base URL
# 生产环境
https://api.franklinwh.com/v2
# 沙盒环境
https://sandbox.api.franklinwh.com/v2
认证方式
API v2.0 支持两种认证方式：API Key 和 OAuth 2.0。
API Key 认证
在请求头中添加 Authorization：
curl -X GET "https://api.franklinwh.com/v2/sites" \
-H "Authorization: Bearer your_api_key_here"
OAuth 2.0
使用 OAuth 2.0 获取 Access Token：
curl -X POST "https://auth.franklinwh.com/oauth/token" \
-d "grant_type=client_credentials" \
-d "client_id=your_client_id" \
-d "client_secret=your_client_secret"
错误处理
API 使用标准 HTTP 状态码表示请求结果：
| 状态码 | 含义 | 处理建议 |
|---|---|---|
| 200 | 请求成功 | 正常处理响应数据 |
| 400 | 请求参数错误 | 检查请求参数格式 |
| 401 | 认证失败 | 检查 API Key 是否有效 |
| 403 | 权限不足 | 确认账号权限级别 |
| 429 | 请求过于频繁 | 降低请求频率 |
| 500 | 服务器错误 | 稍后重试或联系支持 |
站点 (Sites)
在线调试 →管理和查询站点信息
GET/v2/sites获取站点列表
GET/v2/sites/{id}获取站点详情
GET/v2/sites/{id}/devices获取站点下的设备
设备 (Devices)
在线调试 →查询设备信息和状态
GET/v2/devices获取设备列表
GET /v2/devices
获取当前账号有权限访问的所有设备列表。
请求参数
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| siteId | string | 否 | 按站点筛选 |
| type | string | 否 | 设备类型：agate / apower |
| page | integer | 否 | 页码，默认 1 |
| pageSize | integer | 否 | 每页数量，默认 20 |
请求示例
curl -X GET "https://api.franklinwh.com/v2/devices?siteId=site_001" \
-H "X-API-Key: fwh_your_api_key"
响应示例
{
"success": true,
"data": {
"items": [
{ "id": "dev_001", "type": "agate", "name": "Gateway", "status": "online" },
{ "id": "dev_002", "type": "apower", "name": "Battery 1", "soc": 85 }
],
"pagination": { "page": 1, "pageSize": 20, "total": 2 }
}
}
GET/v2/devices/{id}获取设备详情
GET /v2/devices/{id}
获取指定设备的详细信息，包括型号、容量、健康度等元数据。
路径参数
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| id | string | 是 | 设备 ID |
请求示例
curl -X GET "https://api.franklinwh.com/v2/devices/dev_001" \
-H "X-API-Key: fwh_your_api_key"
响应示例
{
"success": true,
"data": {
"id": "dev_001",
"type": "agate",
"model": "aGate 2.0",
"firmware": "3.2.1",
"status": "online",
"installedAt": "2025-08-15"
}
}
GET/v2/devices/{id}/status获取设备实时状态
GET /v2/devices/{id}/status
获取设备实时运行状态（SOC、功率、温度等）。
请求示例
curl -X GET "https://api.franklinwh.com/v2/devices/dev_002/status" \
-H "X-API-Key: fwh_your_api_key"
响应示例
{
"success": true,
"data": {
"id": "dev_002",
"type": "apower",
"soc": 85,
"power": { "charge": 0, "discharge": 2.1 },
"temperature": 28.5,
"status": "discharging",
"updatedAt": "2026-05-12T10:30:00Z"
}
}
遥测数据 (Telemetry)
在线调试 →获取设备实时和历史遥测数据
GET/v2/telemetry/realtime获取实时遥测数据
GET/v2/telemetry/history获取历史遥测数据
GET/v2/telemetry/aggregate获取聚合统计数据
告警 (Alerts)
在线调试 →查询和管理设备告警
GET/v2/alerts获取告警列表
GET/v2/alerts/{id}获取告警详情
POST/v2/alerts/{id}/acknowledge确认告警
GET/v2/alerts/statistics获取告警统计
设置 (Settings)
管理设备运行参数和配置
GET/v2/devices/{id}/settings获取设备设置
PUT/v2/devices/{id}/settings更新设备设置
版本迁移
API v1.0 将于 2026 年 12 月 31 日停止服务，请尽快迁移到 v2.0
v1.0 → v2.0 主要变更：
- 认证方式：X-API-Key → Authorization: Bearer
- 响应格式：统一使用 { success, data, error } 结构
- 分页参数：offset/limit → page/pageSize
- 新增设备设置接口 /devices/{id}/settings
最佳实践
批量操作
使用批量接口减少 API 调用次数
缓存数据
合理缓存不常变化的数据
重试机制
实现指数退避重试处理临时错误
监控配额
定期检查配额使用情况，避免超限
⚠️ API v1.0 即将停止服务
API v1.0 将于 2026 年 12 月 31 日停止服务，请尽快迁移到 v2.0。查看迁移指南 →
概述
FranklinWH API v1.0 提供基础的设备数据查询和控制功能。
Base URL
# 生产环境
https://api.franklinwh.com/v1
认证方式
API v1.0 使用 X-API-Key 请求头认证：
curl -X GET "https://api.franklinwh.com/v1/sites" \
-H "X-API-Key: your_api_key_here"
API 端点 (v1.0)
站点与设备
GET/v1/sites获取站点列表
GET/v1/devices获取设备列表
遥测数据
GET/v1/telemetry获取遥测数据
告警
GET/v1/alerts获取告警列表