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 认证，直接在请求头中传入即可。

API Key 认证

在请求头中添加 Authorization：

curl -X GET "https://api.franklinwh.com/v2/sites" \
  -H "Authorization: Bearer your_api_key_here"

OAuth 2.0 Coming in V1.1

OAuth 2.0 客户端凭证认证将在 V1.1 版本支持，届时可通过 Client Credentials 流程获取 Access Token。

快速入门

5 分钟完成第一次 API 调用：

通过 FleetView SSO 登录获取 API Key
配置认证信息
调用 GET /sites 获取站点列表
查看响应数据

查看完整教程 →

错误处理

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获取设备列表

Free+

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}获取设备详情

Basic+

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获取设备实时状态

Basic+

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 套餐并获取访问权限。

开通流程

步骤	操作	说明
1	通过 FleetView SSO 登录	使用您的 FleetView 账号登录 API Portal
2	选择套餐	Free 立即开通；付费套餐需提交申请
3	等待审批（付费套餐）	销售团队将在 24 小时内联系您
4	获取 API Key	套餐开通后自动生成 API Key

套餐对比

套餐	月费	月度配额	Rate Limit	超量单价
Free	$0	1,500 次	10/min	不可超出
Basic	$149	100,000 次	100/min	$0.005/次
Pro	$449	400,000 次	300/min	$0.004/次
Max	$899	1,000,000 次	500/min	$0.003/次
Enterprise	定制	定制	最高 1000/min	定制

查看完整套餐对比 →

🧪 沙盒环境使用指南

在沙盒环境中测试 API 调用，无需真实设备，使用模拟数据。

沙盒 Base URL

# 沙盒环境
https://sandbox.api.franklinwh.com/v2

沙盒环境特点

✅ 免费使用，不消耗正式配额
✅ 预置模拟数据（站点、设备、遥测）
✅ 支持所有 API 端点测试
✅ 与生产环境 API 格式完全一致
⚠️ 数据每日重置，不持久化

预置场景

场景	站点 ID	描述
正常运行	`sandbox_site_normal`	设备在线，数据正常
设备离线	`sandbox_site_offline`	模拟设备断联场景
告警状态	`sandbox_site_alert`	存在活跃告警
低电量	`sandbox_site_lowsoc`	SOC < 20%
满电量	`sandbox_site_fullsoc`	SOC = 100%
断电场景	`sandbox_site_outage`	模拟电网断电

使用示例

# 在沙盒环境获取站点列表
curl -X GET "https://sandbox.api.franklinwh.com/v2/sites" \
  -H "Authorization: Bearer your_sandbox_api_key"

前往 Swagger UI 测试 →

⚡ Rate Limit 说明

了解 API 请求频率限制规则和配额管理。

频率限制

套餐	每分钟限制	月度配额	超出处理
Free	10 次/分钟	1,500 次	拒绝调用 (429)
Basic	100 次/分钟	100,000 次	按超量单价计费
Pro	300 次/分钟	400,000 次	按超量单价计费
Max	500 次/分钟	1,000,000 次	按超量单价计费
Enterprise	最高 1000 次/分钟	定制	定制

响应头信息

API 响应中包含以下 Rate Limit 相关头信息：

X-RateLimit-Limit: 100          # 每分钟允许的最大请求数
X-RateLimit-Remaining: 85      # 当前窗口剩余请求数
X-RateLimit-Reset: 1620000060   # 窗口重置的 Unix 时间戳
X-Quota-Limit: 100000           # 月度配额总量
X-Quota-Remaining: 95234        # 本月剩余配额

429 错误处理

当超出 Rate Limit 时，API 返回 429 Too Many Requests：

{
  "success": false,
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "请求过于频繁，请稍后重试",
    "retryAfter": 30
  }
}

最佳实践

✅ 实现指数退避重试（Exponential Backoff）
✅ 监控 X-RateLimit-Remaining 头信息
✅ 使用批量接口减少请求次数
✅ 缓存不常变化的数据
⚠️ 避免在短时间内发起大量请求

版本迁移

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获取告警列表

v1.0 功能限制

功能	v1.0	v2.0
批量调度	不支持	支持
历史数据聚合	不支持	支持
OAuth 2.0	不支持	支持

立即迁移到 v2.0 →

FranklinWH API 文档

概述

Base URL

认证方式

API Key 认证

OAuth 2.0 Coming in V1.1

快速入门

错误处理

站点 (Sites)

设备 (Devices)

GET /v2/devices

请求参数

请求示例

响应示例

GET /v2/devices/{id}

路径参数

请求示例

响应示例

GET /v2/devices/{id}/status

请求示例

响应示例

遥测数据 (Telemetry)

告警 (Alerts)

设置 (Settings)

📋 套餐开通指南

开通流程

套餐对比

🧪 沙盒环境使用指南

沙盒 Base URL

沙盒环境特点

预置场景

使用示例

⚡ Rate Limit 说明

频率限制

响应头信息

429 错误处理

最佳实践

版本迁移

最佳实践

概述

Base URL

认证方式

API 端点 (v1.0)

站点与设备

遥测数据

告警

v1.0 功能限制