ZKEco Pro API 集成

概述

ZKEco Pro 是熵基科技的时间&安全精细化管理平台，开放平台 API（v10.0.1）提供 24 个接口，
覆盖 6 大业务域。全部接口为 POST，JSON 格式，纯拉取式（无 webhook/回调），
需第三方主动轮询。

快速上手（30 秒关键约定）

接口速查（24 个）

department（部门）

employee（人员）

iclock（设备）

position（职务）

record（记录 — 核心轮询）

zone（区域）

核心模式

1. 鉴权

所有接口 URL 携带 ?key=ACCESS_KEY，在 ZKEco Pro 管理后台获取。

# Python
url = f"{BASE_URL}/api/v2/department/get/?key={ACCESS_KEY}"

// Java
String url = BASE_URL + "/api/v2/department/get/?key=" + ACCESS_KEY;

2. ret 返回码处理

3. 增量同步（记录类接口核心模式）

所有记录类接口（考勤/门禁/消费）使用 id 自增流水号做增量游标：

# 伪代码：增量同步考勤记录
last_id = db.load_checkpoint("transaction_last_id")  # 从本地库读取上次位置
while True:
    resp = client.post("/api/v2/transaction/get/", {
        "id": last_id,        # 从此 ID 之后开始拉取
        "number": 2000,       # 每页条数（消费类用 5000）
        "startdate": "2026-06-01",
        "enddate": "2026-07-01",
    })
    if resp["ret"] != 0: break
    items = resp["data"]["items"]
    if not items: break
    for item in items:
        process(item)            # 写入本地库
        last_id = max(last_id, item["id"])
    db.save_checkpoint("transaction_last_id", last_id)
    if len(items) < 2000: break  # 不足一页，已拉完

关键约束：
- startdate ~ enddate 时间跨度 ≤ 1 个月
- 考勤/门禁 number ≤ 2000，消费 ≤ 5000
- id 为 0 时从最早开始拉取
- pin / sn / id 三者至少提供一个（否则时间窗必填）

4. 批量写入

# 批量新增人员（≤200 条/次）
employees = [
    {"pin": "10001", "name": "张三", "deptnumber": "D001", ...},
    {"pin": "10002", "name": "李四", "deptnumber": "D001", ...},
]
resp = client.post("/api/v2/employee/update/", employees)
if resp["ret"] == 2:
    for err in resp["error_list"]:
        print(f"部分失败: {err}")

5. 门禁权限组管理

# 追加权限组（tag="0"）
client.post("/api/v2/employee/level/", {
    "pin": "10001",
    "levels": [1, 2, 3],   # 权限组 ID 列表
    "tag": "0",            # "0"=追加, "1"=删除
})

完整示例代码

assets/ 目录提供可运行的 Python 与 Java 集成示例：

• assets/ZKEcoPro_API示例_Python.py — 仅依赖 urllib 标准库，含 ZKEcoClient 封装类、
  全 6 业务域方法、ret 校验、增量同步生成器（iter_transaction / iter_access_record /
  iter_consumer_ic / iter_consumer_id）、批量写入（≤200），可直接复制使用。
• assets/ZKEcoPro_API示例_Java.java — Java 11 HttpClient + Jackson，同等封装，
  含 Maven 依赖注释。

使用示例代码的方式：

1. 复制 assets/ 下的对应语言文件到项目
2. 修改 BASE_URL 和 ACCESS_KEY 为实际值
3. 调用方法即可

详细参数查阅

当需要查看某个接口的完整请求参数表、响应字段表、返回码、示例 JSON 时，
读取 references/ 下的文档：

• references/ZKEcoPro_API对接梳理_校验版.md — 推荐，逐接口校验版，88 条全局返回码表、
  每个接口含请求/响应参数表 + 示例 + 本接口返回码。优先使用此文件。
• references/ZKEcoPro_API对接梳理.md — 初版概览，含对接结论与建议。

常见问题

Q: 如何获取 ACCESS_KEY？

在 ZKEco Pro 管理后台 → 系统设置 → API 密钥中生成。

Q: 增量同步时 id 从哪里开始？

首次从 0 开始（拉取全部历史），后续从本地持久化的最大 id 开始。注意：id 是平台全局自增流水号，跨接口独立。

Q: 考勤记录和门禁记录的区别？

• /transaction/get/：打卡记录（考勤），含验证方式/比对照片
• /record/get/：门禁通行事件，含开门方式/门编号/进出方向

Q: 删除部门失败 ret=？

检查该部门下是否还有子部门或人员，需先清空。

Q: 人员照片怎么传？

通过 /employee/update/ 的 enrollpic 字段传 BASE64 编码的 JPG 图片（≥640×480）。
若面部检测失败返回 ret=-100。

Q: 如何处理时间窗口超限？

按月分片拉取，每月一个窗口，用递增的 id 确保不遗漏。

集成检查清单

向第三方交付时确认以下项：

• [ ] ACCESS_KEY 已获取并配置
• [ ] 网络可通 ZKEco Pro 服务器（默认 81 端口）
• [ ] 增量同步已实现 id 游标持久化
• [ ] ret==2 部分失败场景已处理（检查 error_list）
• [ ] 时间窗口 ≤1 个月分片逻辑就绪
• [ ] 记录类 number ≤2000（消费 ≤5000）
• [ ] 写入批量 ≤200 条
• [ ] 照片 BASE64 解码/存储方案就绪
• [ ] 定时轮询调度策略已部署（建议 1~5 分钟间隔）

📞 帮助与支持

• 联系微信 <u>Principles_RD</u>（备注协议对接）获得技能使用支持；