熵基互联开放平台 · 服务端 API 速查

此 skill 提供熵基互联（ZKTeco Zlink）开放平台服务端 API 的快速查询与对接指导。
数据来源为熵基互联帮助中心（https://zlink-help.zktecoiot.com → 面向开发者 →
服务端API），抓取日期 2026-08-25，覆盖 7 个使用场景、49 个接口 + 事件订阅机制。

接口域名：https://zlink-open.zktecoiot.com
URL 规范：{HTTP method} https://zlink-open.zktecoiot.com/open-apis/{category}/{version}/{resource}

资源文件

• references/api_index.md — 场景导航表 + 全部 49 个接口清单（场景/子类/名称/方法/
  URL/频率限制/权限要求）+ 调用流程速览。用户按场景浏览、按关键词搜索、或需要先用
  总表定位时，先加载此文件。
• references/auth_and_access.md — 场景 1：认证及授权 + API 调用指南。含 tenantToken
  获取接口、HTTP 方法/版本约定、API 权限申请与分类、IP 白名单、访问凭证类型
  （Tenant/App/User-Access-Token）选择、频控策略与超限响应、通用参数、通用错误码表。
  用户问"怎么鉴权"、"频控是多少"、"ZKER0993 是什么"时加载。
• references/org_contacts.md — 场景 2：组织通讯录。部门（5 接口）、职位（5 接口）、
  员工（6 接口，含离职 PATCH .../resign）的增删改查与分页查询。人员主数据同步重点。
• references/person_credentials.md — 场景 3：人员生物凭证。人脸凭证评分检测、创建
  人脸/卡号生物凭证、删除员工生物凭证。
• references/access_control.md — 场景 4：门禁通行。含「接入准备/接入流程/基本概念」
  必读章节（门、时间段、权限组、权限组分配、开门逻辑），以及时间段（5）、权限组（5）、
  门（3，含远程开门）、开门记录（1）、开门事件（1）共 15 个接口。
• references/attendance.md — 场景 5：考勤管理。管理员手动创建/查询打卡记录、分页查询
  打卡事件，以及打卡事件的事件体结构与示例。
• references/device_center.md — 场景 6：设备中心。时区列表、站点（5）、设备查询、
  考勤机设备成员全量下发与已下发成员查询。
• references/event_subscription.md — 场景 7：事件订阅与回调。事件概述与适用场景、
  事件版本（v1.0/v2.0）与事件结构、事件列表、订阅三步流程（选择订阅方式 → 添加事件 →
  接收事件）、WebSocket 长连接接入协议、Webhook 加密策略（加密密钥/验证签名凭证）、
  安全校验与事件解密、回调 URL 校验（响应处理示例）、FAQ。

工作流程

1. 用户按使用场景查询

当用户说"组织架构怎么同步"、"门禁接口有哪些"、"考勤打卡记录怎么拉"、"设备成员怎么下发"：

1. 加载 references/api_index.md，定位「一、场景导航」中对应行
2. 列出该场景下接口（名称、方法、URL）与频率限制
3. 需参数/示例时，加载对应场景文档，按 ## {接口名称} 定位接口卡片，给出请求头、
   路径/请求体参数表、请求示例、响应参数与示例、错误码表

2. 用户按接口名或 URL 关键词查询

当用户给出接口名（如"远程开门"、"分页查询员工信息"）或路径片段（如 acc/v1/levels）：

1. 在 references/api_index.md 的清单表中检索（名称/URL 双维度）
2. 加载对应 references/*.md，取该接口完整卡片（含参数与示例）
3. 涉及枚举/字段含义时，同时给出该场景文档中接口前的概念说明章节
   （如门禁的「基本概念」、考勤的「事件体」）

3. 用户询问对接通用规范

当用户问"怎么获取 token"、"token 多久过期"、"并发上限"、"返回 ZKER0993 怎么办"、
"该用哪种 access_token"：

1. 加载 references/auth_and_access.md
2. 认证：POST /open-apis/authen/v1/tenantToken/internal（body 传 appKey/appSecret），
   响应 data.tenantToken + data.expiresIn（秒）
3. 频控：按「租户 × 应用」独立计量的秒/分钟双维度；超限返回 HTTP 403 + ZKER0993
4. 错误码：ZCOP0000 成功，ZKER0991~ZKER0999 为通用失败码，逐接口错误码见
   各场景文档的「错误码与错误信息」表

4. 用户提事件订阅/回调开发问题

当用户问"怎么接收实时事件"、"长连接怎么建"、"回调怎么验签解密"、"为什么会收到重复事件"：

1. 加载 references/event_subscription.md
2. 选型：WebSocket 长连接（wss://zlink-ws.zktecoiot.com，SDK 已封装鉴权，明文、
   无需解密验签）vs Webhook（需 IPv4 公网地址，需按加密策略验签+解密）
3. 强调三条硬约束：10 秒内响应、失败重试 4 次（5min/15min/1h/6h）、
   必须用 requestId 做幂等（至少一次投递策略）
4. 添加/删除订阅事件后必须发布应用并经企业管理员审核，配置才生效

5. 用户提端到端对接方案

如"把 Entra/HR 系统的人员同步到熵基互联并下发到考勤机"：

1. 认证：获取 tenantToken（场景 1）
2. 主数据：创建部门 → 创建职位 → 创建员工（场景 2）
3. 凭证：创建人脸/卡号生物凭证（场景 3），注意先调「检测人脸生物凭证信息评分」
4. 门禁授权：创建时间段 → 创建权限组 → 查询门列表 → 分配权限组（场景 4）
5. 设备下发：查询设备 → 全量下发成员至考勤机（场景 6）
6. 数据回流：分页查询开门记录/打卡记录，或订阅事件（场景 7）
7. 给出调用顺序、注意事项（分页、频控、幂等）

业务域速览

URL 分类前缀：authen（认证）· org（组织）· cms（凭证）· acc（门禁）·
att（考勤）· loc（位置/站点）· dcc（设备中心）。当前均为 v1。

关键约定

• 认证流程：开发者后台创建自建应用 → 申请 API 权限（按「租户 × 应用」维度授予，
  各应用独立）→ 可选设置 IP 白名单 → 获取 tenantToken → 调用 API
• tenantToken：POST /open-apis/authen/v1/tenantToken/internal，body 为
  {"appKey": "...", "appSecret": "..."}；请求头固定 Content-Type: application/json
  与 Accept-Language: zh-CN；token 值以 t- 为前缀，最大有效期 1 小时；剩余有效期
  >= 10 分钟时接口返回原 token，< 10 分钟时返回新 token（此时两个 token 同时有效）
• 请求头鉴权：后续接口统一携带 Authorization: Bearer {access_token}
• 访问凭证三级：Tenant-Access-Token / App-Access-Token（操作应用自身资源，无需
  用户授权）与 User-Access-Token（操作租户用户数据，需用户授权）——按目标接口文档要求选用
• HTTP 方法语义：GET 查询 / POST 新建（含分页查询与列表接口）/ PUT 全量更新 /
  PATCH 局部更新（如员工离职）/ DELETE 删除；分页查询统一走 POST {resource}/search
• 频控：秒 + 分钟两维度，按租户与应用独立；超限返回 HTTP 403 + 业务码 ZKER0993
  （"接口调用频率超过，禁止调用"），需按文档限制降频重试
• 成功判定：业务码 ZCOP0000 表示成功，HTTP 200 不代表业务成功，须同时校验 code
• 支持的应用类型：49 个接口中 47 个标注"内部自建应用"（认证接口与回调示例无此
  字段）；事件列表另外标注每个事件对自建/商店/集成应用的支持情况（开门事件与打卡事件
  三类应用均支持）
• 事件订阅双模式：长连接（WebSocket，wss://zlink-ws.zktecoiot.com，鉴权在 SDK 内
  封装、事件为明文）或 Webhook（HTTP POST 至开发者服务器，单应用仅一个回调地址且
  必须为 IPv4 公网地址）
• 事件结构：requestId（唯一标识，用于幂等）+ eventCode（事件编码）+
  encryptData（加密消息体）；提供 v1.0/v2.0 两版本，建议订阅 v2.0 且避免重复订阅同一事件
• 回调时限：10 秒内返回 HTTP 200（TCP 建联超时 2 秒）；失败按 5 分钟、15 分钟、
  1 小时、6 小时重推，最多重试 4 次；链路为"至少一次投递"，必须做幂等
• 安全校验：Webhook 模式需时间戳校验（Unix 毫秒，有效期 5 分钟）+ 签名校验
  （验证签名凭证参与计算）；加密密钥为 16 位英文或数字，验证签名凭证长度不超过 32 位
• 门禁业务前置：对接门禁接口前先读 access_control.md 的「接入准备/接入流程/
  基本概念」，理解门 → 时间段 → 权限组 → 权限组分配 → 开门逻辑的依赖顺序
• 考勤设备成员下发：PUT /open-apis/dcc/v1/devices/{device_id}/members 为全量语义，
  须提交完整成员列表，避免误清空

已知问题与注意点

• 路径参数命名不一致：「获取时间段详情」原文 URL 为
  /open-apis/acc/v1/schedules/{schedules_id}（复数 schedules_id），同场景其他接口使用
  单数 {schedule_id}。疑为源文档笔误，对接时以平台实际返回与行为为准。
• 第 49 条「响应处理示例」非开放平台接口：其 URL 为第三方示例回调地址
  https://api.3rd.com/receive?sign={sign}&timetamp={timestamp}&nonce={nonce}&echo={echo}，
  仅演示平台校验回调地址时下发的 GET 请求格式；原文查询参数拼写为 timetamp（少一个 s），
  实际对接请以平台下发请求为准。
• 事件列表不完整：文档事件列表页仅列举「开门事件」与「打卡事件」两项，其他事件
  未枚举，订阅前需在开发者后台确认可选事件。
• 外链图片：场景文档中的流程图与后台界面截图引用外部图床链接，可能失效；
  涉及后台操作路径的，文档正文已以文字描述步骤。
• 字段缺省的两个接口：认证接口（自建应用获取tenantToken）与回调示例
  （响应处理示例）原文不含「接口频率限制」「支持的应用类型」「权限要求」三项字段，
  总表中显示为 -，属正常（认证与回调校验不适用频控与业务权限）。
• 创建打卡记录频控更严：POST /open-apis/att/v1/admin/transactions 为 10 次/秒、
  60 次/分钟，批量补卡场景需自行限流。
• 数据时效：本文档数据抓取于 2026-08-25，对接前建议核对帮助中心是否有接口变更；
  抓取与转换工具见 skill zlink-help-center。

验证

运行 python demo.py 自检（26 项）：校验 8 个 references 文件完整性与内容规模下限、
接口条目数（应为 49）、URL 前缀与「方法 + URL」唯一性、场景文档与总表映射一致性
（逐场景接口数 1/16/4/15/3/9/1）、接口卡片必备章节、认证与事件关键要素、已知问题标注，
输出 PASS/FAIL 明细报告；全部通过时退出码为 0。