ZKEco Pro API 集成

要解决什么问题

企业把时间与安全业务跑在 ZKEco Pro 上时，HR、门禁、消费等数据往往要进自研系统或数据中台。官方开放平台（v10.0.1）有 24 个接口，但约定集中：全是 POST、JSON 体、URL 上 ?key=ACCESS_KEY 鉴权，且 没有 webhook，记录只能由你方 定时轮询。批量写入、查询时间窗、ret 与 error_list 若处理不当，很容易出现漏数、重复拉取或部分失败被当成成功。

技能如何帮你对接

本技能把对接要点压成可执行的「契约表」与模式说明，并指向 assets/ 里可复制的 Python（urllib） 与 Java 11 HttpClient 示例，内含 ZKEcoClient 封装、六大业务域方法，以及考勤/门禁/消费的 id 增量生成器（iter_transaction 等）。

• 基础路径：http://{host}:{port}/api/v2/（默认端口 81）
• 主数据：部门、人员（含离职/恢复、比对照、门禁权限组）、设备、职务、区域
• 记录拉取：考勤 transaction/get、门禁 record/get、IC/ID 消费等，用自增 id 作游标，从 last_id 继续
• 返回处理：ret=0 读 data.items；ret=2 必须遍历 error_list；字段类错误对照 100～171

需要某接口的完整参数表、响应字段与示例 JSON 时，按技能说明读取 references/ZKEcoPro_API对接梳理_校验版.md（优先）或初版概览文档。

边界与注意点

• 记录查询 时间跨度 ≤1 个月，单次条数考勤/门禁 ≤2000、消费类 ≤5000；写入批量 ≤200
• id 在各记录接口间独立，首次可从 0 拉全量，之后务必 持久化本地最大 id
• 人员照片经 enrollpic 传 BASE64 JPG（≥640×480），面部检测失败为 ret=-100
• 删除部门前须清空子部门与人员；集成侧需自行部署 1～5 分钟 级别的轮询调度