业务系统通常需要什么
业务系统接入摄像头网关时，通常不希望直接处理每个摄像头的差异。更常见的需求是读取设备和通道列表、获取浏览器播放地址、查看在线状态、查询录像索引、接收通道变化或告警事件，并把这些能力嵌入自己的业务页面。
StreamGate 的开放接口面向这类集成场景。业务系统可以围绕通道、播放、录像、状态和授权信息做对接，减少二次封装和现场联调成本。
WebHook 和 MQTT 适合什么
OpenAPI 更适合主动查询和管理操作，WebHook 适合把事件推送到业务系统，MQTT 适合已有消息总线或设备平台。具体使用哪种方式，取决于客户系统的架构、网络边界、权限模型和运维习惯。
正式项目中，建议先用少量真实设备验证播放地址、通道状态和事件通知，再扩展到更多设备和业务流程。
API 对接应围绕业务动作设计
摄像头网关的接口不应只暴露底层协议参数。业务系统通常更关心设备列表、通道列表、播放地址、录像索引、在线状态、事件通知、授权状态和错误诊断。接口设计越贴近这些业务动作，集成方越不需要理解每个摄像头的协议细节。
OpenAPI 适合主动查询、创建通道、获取播放地址和检索录像；WebHook 适合把通道变化、录像任务、异常和告警推送到业务系统；MQTT 适合已有物联网或设备平台的消息总线。对接前应确认鉴权方式、网络边界、回调地址、消息幂等、失败重试和日志字段。
建议先验证最短闭环
正式集成前，建议先完成四个动作：添加真实设备、通过 API 获取播放地址、接收一次状态或事件通知、查询一段录像并回放。这个最短闭环跑通后，再扩展到更多通道、更多事件和更复杂的权限模型。
接口落地时要留出运维信息
业务系统对接时不要只保存播放地址。建议同时保存通道 ID、设备名称、协议类型、在线状态、最近错误、录像状态和更新时间。出现黑屏、无录像或事件丢失时，这些字段能帮助现场人员判断是摄像头、网关、浏览器、网络还是业务系统的问题。
WebHook 和 MQTT 还应考虑重复消息、乱序消息和失败重试。接收端最好按事件 ID 或通道状态做幂等处理，并保留最近一次事件时间。这样即使网络短暂波动，也不会因为重复通知导致业务系统状态来回跳变。