楼宇平台OpenAPI对接验收：数据口径、签名、权限与异常处理

对接验收不应止于调用一次接口获得成功响应。第三方系统还要知道数据代表什么、权限何时失效、超时能否重试，以及失败时应该怎样呈现。协同互联北向OpenAPI提供设备、点位、历史、告警与受控写点入口，项目双方需要围绕这些真实能力形成一致的接口清单和测试记录。

先约定编码、单位与时间口径

接入前列出双方设备和标准点的对应关系，说明单位、精度、采集时间与质量字段的含义。历史数据查询还应明确时间区间、时区、分页和数据为空时的处理。选择同一设备，将平台详情、接口响应和第三方显示逐项比较，避免接口字段正确但业务系统把累计量、瞬时量或时间解释错误。

第三方应用应具有独立凭据和明确责任人，按用途配置设备、点位、告警读取及控制写入权限，同时约定来源、调用频率和有效期。凭据交接通过双方约定的受控渠道完成，不能放入官网示例、前端静态文件或公开文档。开发、联调与正式使用的应用范围也需要分别确认，防止测试授权被长期沿用。

正常请求通过后，再测试错误签名、过期时间、重复随机标识和授权失效等情况。请求签名依赖实际方法、路径、查询和报文，代理改写或编码差异也可能导致失败。双方应保存可脱敏比对的请求标识与错误信息，排查时核对签名原文和时间同步，避免为了联调方便关闭校验。

需要操作设备时，先确认允许控制的点位、值域、责任人和现场恢复方式。控制调用使用幂等标识处理可能的重复请求，同一次业务重试应保持约定标识，不应把每次超时都当成全新命令。接口返回提交结果后，还要通过实际反馈确认设备状态；能够读取点位，不表示已具备控制授权或现场控制能力。

分别模拟无权限、频率限制、网络超时、接口不可用和空数据。第三方画面应区分无数据、数据过旧与真实零值，不应把接口失败改写成“全部正常”。对可重试情况约定间隔与次数，避免持续高频请求放大故障。恢复后重新核对采集时间和数据质量，确认读取的是新的实际状态。

交付接口版本、字段说明、编码映射、权限范围、频率约定、错误处理和凭据轮换责任。测试记录标明请求标识、预期结果、实际结果及问题结论，敏感密钥不进入普通截图或日志。应用停用、人员变更或合作结束后，核对撤销后的请求已被拒绝。后续增加点位或控制权限，应再次检查对应范围。