为什么门禁厂商要把接口开放出来

过去门禁系统是一个闭环：设备、控制器、后台都在一家手里，管理员在这个后台里发卡、查记录、设权限。这套模式在单点部署时很好用，但只要客户已经有自己的物业系统、人事系统或者园区平台，数据就开始两头跑。人事入了职要在这里发卡，离职了要去那边删权限，通行记录导出来还要人工对表，运维成本全压在使用方身上。

开放 API 的本质是把门禁从「一套独立系统」变成「一个能力模块」。人员、权限、设备、记录这些核心对象通过接口暴露出去，客户在自己熟悉的平台里统一管理，门禁只在底层负责识别与开门。这样既保住了设备的稳定性，又避免了重复建设，对使用方和厂商都是更经济的选择。

接口分层：人员、权限、通行记录、访客

先说人员。人员是主体，包含唯一标识、姓名、部门、证件信息、有效期与状态。接口应支持新增、更新、停用与查询，注意「停用」与「删除」要分开设计：停用保留历史通行记录，删除才真正清理数据。很多对接出问题就出在这一点上，一旦物理删除，历史记录就失去关联对象。

权限与设备是第二层。权限是把人、门、时间段三者绑在一起的规则，接口要支持按人员或按门反查。通行记录是结果数据，通常按时间段分页拉取，支持按人员、门、结果状态过滤。访客是特殊场景，涉及预约、临时授权、到期回收与陪同规则，建议单独一组接口，不要把访客混进正式人员表，否则权限清理会失控。

鉴权、签名与幂等设计

接口鉴权建议采用应用级密钥加签名的方式：每个接入方分配独立的 appid 与 secret，请求带时间戳与随机串，服务端校验时间窗口防止重放。令牌设置有效期并支持主动吊销，密钥轮换要能在不停机的情况下完成。不要用一个全局密钥给所有客户用，一旦泄露就是全量风险。另外建议给每个接入方配独立的调用配额与告警阈值，异常放量时能第一时间定位到具体调用方，而不是对着总流量猜测是谁在刷接口。

写类接口必须支持幂等。新人入职重复推送、网络超时重试都是常态，如果没有幂等键，就会出现同一人重复建档或者权限重复下发。建议由接入方传入业务唯一号，服务端按该号去重并返回首次结果。返回结构要稳定，错误码要区分「参数错误」「权限不足」「资源不存在」「服务繁忙」四类，方便接入方做差异化重试。

同步模型：全量与增量怎么配合

首次接入用全量，之后走增量。全量接口按分页返回，页大小控制在合理范围，避免超时；增量按更新时间戳或者版本号拉取，服务端要保证同一时间戳内的数据不漏，通常用「时间戳 + 主键」的复合游标解决。只靠时间戳会在高并发写入时丢数据，这个问题在人员集中导入时特别容易暴露。游标要落库保存，不能只放在内存里，否则服务重启之后会从头再拉一遍，接入方那边就会出现重复数据，处理起来比漏数据更麻烦，清洗成本也高得多。

方向也要明确。人员数据一般由客户平台单向推给门禁，通行记录由门禁单向推给客户平台或者由客户平台拉取。如果两边都能改，就要定义冲突处理规则，否则同一个人的权限今天在A系统里加、明天在B系统里删，最后谁都说不清。建议明确单一数据源，另一侧只读，把复杂度提前消化掉。

典型对接场景与调用顺序

最常见的场景是人事联动：入职时创建人员、绑定卡或人脸、下发权限到指定门组，离职时停用人员并回收权限。顺序上必须先建人、后下发权限，权限下发要能查询到执行结果，而不是发出去就认为成功。设备离线时指令会排队，接口应返回「待下发」状态，并在设备恢复后回写最终结果。

第二个场景是访客预约：访客在客户平台填信息，平台调用接口创建预约并下发临时权限，到期自动失效。第三个场景是记录回流：客户平台按时段拉取通行记录，用于考勤、安全审计或者人员轨迹分析。三个场景可以同时存在，接口要按业务域隔离，避免一个场景的高频调用拖垮另一个。

联调与上线验证

联调阶段先跑通「单条链路」：建一个人、下发一个门、刷一次卡、查到一条记录。这四步全通，才算链路成立。之后再做批量与异常：批量导入一千人看耗时与失败明细，模拟设备离线看指令排队与补发，模拟网络中断看重试与幂等，模拟权限到期看回收是否及时。

上线前要有一份验证清单，逐项打勾：鉴权失败是否有明确错误码、分页是否有上限保护、时间格式与字符集是否统一、并发写入是否有序、日志能否按请求号串联。清单不是形式，它能挡掉绝大多数「上线后才发现」的问题。跑完清单再切流量，灰度到部分门组，稳住之后再全量。切换当天安排人盯着错误率与耗时曲线，出现突增立刻回退到旧链路，把影响面控制在一个门组之内，这比事后写复盘报告有用得多。

常见问题

开放接口会不会带来安全风险

风险主要来自密钥管理而不是接口本身。建议每个接入方独立密钥、请求签名加时间窗校验、令牌可吊销、关键操作留审计日志。同时按最小权限授权，只开客户实际需要的接口域，并定期复核调用量与异常来源。

设备离线时下发的权限会丢吗

正常情况下不会丢，指令会进入队列，设备恢复后补发。接口应返回待下发状态，并提供结果查询。但要注意队列有有效期，长时间离线需要重新下发；上线前建议实测离线超过一天再恢复的补发行为。

通行记录一般能保存多长时间

取决于存储策略与合规要求，常见是半年到两年。接口侧建议支持按时间段分页拉取并提供总量预估，避免接入方一次拉取过多导致超时。历史数据归档后仍应可查，只是查询接口的响应时效会不同。

能不能只用接口不用后台

技术上可行，但不建议完全没有后台。排查设备故障、处理临时开门的紧急情况、核对指令下发结果，这些操作在后台里更快。比较合理的分工是客户平台管人与权限，厂商后台管设备与诊断。

接口对接一般要多久能上线

取决于客户平台的改造量。如果只是人员与记录同步，通常几天到两周可以联调完成；涉及访客、考勤、多品牌混合的场景会更久。关键是先把数据源与字段口径对齐，口径不清会导致反复返工。

全国服务热线：400-6537-085