ZKTeco 考勤 PUSH 通讯协议专业参考（V5.8 / PUSH V2.4.2）

概述

提供熵基科技（ZKTeco）考勤 PUSH 通讯协议 V5.8（PUSH 协议版本 V2.4.2）的完整专业参考。该协议基于 HTTP 1.1（TCP/IP），适用于考勤设备（标准考勤/人证核验/信息屏）与服务端之间的数据交互。所有行为由设备端发起。

核心特征

• 设备主动发起 HTTP 请求，服务端被动响应
• 编码：UTF-8（用户姓名字段在中文设备上使用 GB2312）
• 分隔符：字段间使用制表符 \t（HT），记录间使用换行符 \n（LF）
• 子协议：att（标准考勤）/ pid（人证核验）/ ins（信息屏）
• 通信加密：PUSH 协议版本 ≥ 2.4.0 支持（DH 密钥交换 + sessionKey 对称加密）

与安防 PUSH 的主要区别

快速定位指南

API 接口速查

设备→服务器上传接口：

服务器→设备命令格式：

所有命令通过设备轮询 GET /iclock/getrequest?SN={SN} 下发：

C:{CmdID}:{命令类型} {参数}

命令类型速查

附录速查

使用流程

第一步：理解协议体系

1. 确认协议版本（文档 V5.8 / PUSH 协议 V2.4.2）
2. 查看 API 接口速查 表了解所有 HTTP 接口
3. 阅读 通信流程 了解整体交互顺序

第二步：实现服务器端基本框架

标准对接顺序：

1. 初始化信息交互 → 实现 GET /iclock/cdata?options=all 处理
2. 心跳 → 实现 GET /iclock/ping 处理
3. 上传数据 → 实现 POST /iclock/cdata 处理（至少 ATTLOG）
4. 命令获取 → 实现 GET /iclock/getrequest 命令队列
5. 命令回复 → 实现 POST /iclock/devicecmd 处理

第三步：处理具体数据

• 上传考勤记录：table=ATTLOG → 解析 Tab 分隔字段（Pin/Time/Status/Verify...）
• 上传考勤照片：table=ATTPHOTO → 解析照片元数据 + 二进制流
• 上传操作记录：table=OPERLOG → 解析 OPLOG 格式
• 上传用户信息：table=OPERLOG → 解析 USER 格式
• 上传指纹/面部/指静脉模板：table=OPERLOG → 解析 FP/FACE/FVEIN 格式
• 上传一体化模板：table=BIODATA → 解析 BIODATA 格式
• 上传异常日志：table=ERRORLOG → 解析 ErrCode

第四步：下发命令

• 下发用户信息：DATA UPDATE USERINFO
• 下发指纹模板：DATA UPDATE FINGERTMP
• 下发面部模板：DATA UPDATE FACE
• 下发一体化模板：DATA UPDATE BIODATA
• 下发比对照片：DATA UPDATE BIOPHOTO
• 删除数据：DATA DELETE {TableName}
• 查询数据：DATA QUERY {TableName}

第五步：高级功能

• 远程登记：ENROLL_FP / ENROLL_MF / ENROLL_BIO
• 在线升级：UPGRADE（支持三种方式）
• 后台验证：PostVerifyData
• 异地考勤：RemoteAtt

代码生成指南

Python PUSH 服务端框架

在 assets/att_push_demo.py 中提供完整的 PUSH 服务端参考实现，包括：

生成集成代码

当第三方公司提出以下需求时，参考对应章节生成代码：

代码规范

• 所有示例代码使用 Python 3.8+
• 依赖仅限标准库（http.server, urllib, json, base64 等）
• 代码中关键路径和字段使用注释标明参考章节号
• 错误处理和边界情况包含注释说明

参考文档

完整的协议参考文档位于 references/att-push-v58-reference.md，包含：

• 全部 16 种上传数据格式的字段定义和示例
• 全部 DATA UPDATE（20 种）/ DELETE（13 种）/ QUERY（5 种）子命令的完整字段定义
• 全部 3 种远程登记命令的格式和返回值
• 全部 10 个附录的完整枚举值表
• 全部控制命令、检查命令、配置命令、文件命令的格式
• 通信加密方案（DH 密钥交换）详细流程
• 混合识别协议规范说明
• 与安防 PUSH 协议差异对比表
• 对接注意事项（编码、数据量、卡号格式等）

示例代码资产

assets/att_push_demo.py 提供可直接运行的 PUSH 服务端示例：

# 启动服务端（默认端口 8088）
python att_push_demo.py

# 服务端日志输出示例
[INIT] SN=0316144680030 - 初始化成功，返回配置参数
[UPLOAD] SN=0316144680030 - 收到考勤记录 9 条
[UPLOAD] SN=0316144680030 - 收到操作记录 1 条
[HEARTBEAT] SN=0316144680030 - 心跳 OK

常见问题

📞 帮助与支持

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