平台对接第三方系统的API设计方案

能源管理平台很少独立运行，通常要跟企业的ERP、MES、OA、BI等系统对接。API设计方案决定了对接效率和数据一致性。设计不合理的API导致对接周期长、数据丢失、维护困难。设计到位的API让平台对接像搭积木一样高效。

一、API认证与授权机制

第三方系统调用平台API前必须通过身份认证，认证机制是安全的**道防线。

1. Token认证。采用OAuth 2.0或JWT方案。第三方系统用AppID和AppSecret换取Access Token，Token有效期2小时，过期自动刷新。Token中包含调用方身份和权限范围，平台根据Token鉴权。

2. 权限分级。API权限按数据维度控制——只读权限允许查询数据，读写权限允许修改配置，管理权限允许增删设备。不同第三方系统分配不同权限级别。MES系统只需要读取能耗数据，运维系统需要读写设备配置。

3. 调用频率限制。单AppID默认调用频率100次/分钟，超出返回429状态码。高频场景（实时大屏刷新）可申请提升到1000次/分钟。频率限制防止单一调用方消耗过多服务器资源。GB/T 22239等保要求对API调用做审计日志记录。

二、数据接口规范

数据接口是平台对接第三方系统的核心，接口设计要遵循RESTful规范。

1. 资源命名。URL采用名词复数形式，如/api/v1/meters（电表列表）、/api/v1/meters/id/readings（电表读数）。版本号放在URL路径中（/v1/），便于后续升级不兼容时切换到/v2/。

2. 数据格式。统一用JSON格式，时间戳用ISO 8601格式（2026-08-19T10:30:00+08:00），数值用浮点数不保留多余小数位（功率精度2位小数，电量精度3位小数）。

3. 分页和过滤。列表接口必须支持分页（page和page_size参数，page_size默认20**100）和条件过滤（按时间范围、设备ID、数据类型筛选）。不设分页的接口在数据量大时会超时。

三、数据推送与消息通知

除了第三方系统主动拉取数据，平台还要支持数据推送到第三方系统。

1. Webhook回调。平台在指定事件（如告警触发、日冻结完成）发生时，主动POST数据到第三方系统注册的回调URL。回调数据包含事件类型、时间戳、设备ID和业务数据。回调失败自动重试3次，间隔30秒、60秒、120秒。

2. 消息队列订阅。对于数据量大的场景（如实时功率数据），平台提供Kafka Topic订阅接口。第三方系统消费指定Topic，获取实时数据流。相比Webhook回调，消息队列支持更高吞吐量，单Topic每秒可推送1万条以上消息。

3. 事件类型设计。标准事件类型包括：数据上报完成、告警触发、告警恢复、设备上下线、配置变更。第三方系统按需订阅事件类型，不订阅的事件不会推送。

四、错误处理和异常恢复

API对接中异常不可避免，错误处理机制决定了系统的健壮性。

1. 错误码体系。HTTP状态码加业务错误码双层设计。200表示成功，400表示请求参数错误，401表示认证失败，403表示权限不足，500表示服务器内部错误。业务错误码补充细节，如40001表示设备不存在、40002表示时间范围超限。

2. 幂等设计。同一请求重复提交不产生副作用。写入接口（如设备配置更新）用请求ID做幂等校验，重复请求返回首次处理结果。读取接口天然幂等。

3. 数据一致性保障。对接双方维护数据对账机制——每日凌晨比对平台和第三方系统的设备台账和累计电量。差异超过0.1%触发告警，人工介入排查。对账机制防止网络中断或程序异常导致的数据不一致。

平台对接第三方系统的核心是"接口标准化、认证规范化、异常可控化"。API设计方案不是堆功能，是让对接方少踩坑、少写适配代码。好的API设计能让一个第三方系统对接在2天内完成，差的API设计要反复联调2周。

FAQ

问：API接口支持哪些认证方式？
答：支持OAuth 2.0和JWT Token认证。第三方系统用AppID和AppSecret换取Access Token，Token有效期2小时。不支持Basic Auth和API Key直接传递，安全性不足。

问：平台API的响应时间有保障吗？
答：查询接口响应时间小于200ms（95分位），列表分页查询小于500ms。数据推送Webhook回调小于1秒。响应时间依赖数据库查询性能，时序数据库查询毫秒级。如响应超时先排查网络延迟和数据库负载。

问：对接多个第三方系统时数据怎么隔离？
答：每个第三方系统分配独立AppID，权限范围绑定到指定设备组或数据维度。AppID A只能访问厂区1的设备数据，AppID B只能访问厂区2的数据。数据隔离在API网关层强制校验，不依赖调用方自觉。

关于深圳合众致达科技有限公司

深圳合众致达科技有限公司专注智能水电表及能耗管理系统的研发制造，产品覆盖智能水表、智能电表、预付费系统及能源管理平台，服务工业园区、校园、商业综合体及市政供水等多个行业场景。