客流公共云平台 HTTP API 接入指南

系统集成商在承接门店、商场、景区项目时，常遇到同一份需求里混着几种品牌的客流设备。项目要交付，数据要汇总，硬件又不允许全部换掉。客流公共云平台的 HTTP API 就是为这类场景准备的：把存量专用设备的计数结果统一收进云端，再由集成商在自有系统里做二次开发。接入本身不复杂，难点在于边界清楚、口径对齐、联调扎实。

先确认边界，再谈接口

平台的接入协议只有 HTTP API 一种，不是 ONVIF，也不通过通用视频流取数。这一点在方案报价阶段就要向甲方讲明。可接入的设备是客流专用设备，海康、大华、宇视、华为等主流品牌在兼容列表内，列表持续更新中，并提供免费兼容性检测。普通网络摄像机不在支持范围内，因为它不产生客流计数结果，平台也没有从中提取人流的路径。

数据侧同样有明确边界。平台输出的只有计数结果和匿名化特征向量，不保留人脸图像。集成商在写需求文档时，不要预设"调取抓拍图"或"回传人脸底库"这类功能，接口层面不存在对应能力，承诺出去会在验收时变成返工。

对接前需要落实的四项准备

第一项是设备清单。型号、固件版本、安装高度与俯角、通道数量，逐台登记。平台给出的准确率前提是安装高度 2.5 至 3.5 米、俯角 0 至 15 度、头部像素不低于 60px，现场条件不达标时，接口通了数据也未必可用。

第二项是网络。设备需要能访问公网，或者经甲方既有出口转发。项目现场常有访客网络与业务网络分离的情况，端口策略要提前申请，不要等到联调当天才发现设备出不去。

第三项是账号与权限。平台按组织架构分配权限，集成商通常拿到的是项目范围内的账号。需要确认该账号能看到哪些门店、哪些设备、能否创建下级账号，这决定了后续是单账号集中拉取，还是按客户分别授权。

第四项是指标口径。进店率、停留时长、过店人数在不同甲方那里定义不同。接口给的是原始计数，口径换算在集成商侧完成。口径先谈定，联调时就不会出现"同一个数两边对不上"的争议。

认证、传输与调用方式

平台采用 API Key 认证与 HTTPS 加密传输。密钥属于项目级凭证，应当放在服务端，不写进前端代码，也不随安装包分发。多客户交付时，建议按客户维度分配独立密钥并记录使用范围，出现异常调用时能快速定位到具体项目。

调用方式上，集成商的常见做法是建一个同步服务：定时从平台拉取增量数据，落库后再向甲方系统供数。这样做的原因是甲方系统往往不能直连外网，中间加一层缓冲，网络波动不会直接影响业务查询。同步频率按业务需要设定，日报场景每小时一次足够，实时看板则要评估设备侧的上报节奏，不要用高频轮询去追一个本身就有延迟的数据源。

具体接口路径、请求参数与返回字段，以官网开发者文档为准。文档会随兼容设备与功能迭代更新，集成商应把文档版本号写进项目技术方案，避免交付半年后无法追溯当时的字段定义。

从试跑到验收的推进路径

规范的推进顺序是四步。先用免费兼容性检测确认现场设备能否接入，这一步不产生费用，也能提前暴露固件过旧的问题。再开 14 天免费试用，用真实设备跑通数据链路，试用无需绑定信用卡。第三步做联调，重点验证三件事：断网恢复后数据是否连续、跨零点的时间归属是否正确、多设备汇总时是否存在重复计数。第四步小范围灰度，选一到两个门店跑满一个完整营业周期，再复制到其余点位。

这套顺序的价值在于把风险前移。设备兼容问题在第一步暴露，成本最低；口径问题在第三步暴露，还来得及改文档；等到全量上线才发现某类设备的数据延迟超出预期，调整空间就很小了。