Time & attendance
ZKTeco Integration Guide — HumanR
How to connect ZKTeco attendance machines (fingerprint / face / card, any model with ADMS a.k.a. Cloud Server support) to HumanR so punches flow in automatically. No SDK, no middleware, no polling — the device pushes to the app over plain HTTP using ZK's iClock "push" protocol, which HumanR implements natively at /iclock/*.
This is the guide HumanR users read inside the product, published as-is. It is written for someone with the screen in front of them, so it describes buttons you cannot click from here — which is rather the point: you can check how the product behaves before you commit to it.
1. Requirements
| What | Value |
|---|---|
| Server | The machine running HumanR, reachable from the device's network |
| Port | 5080, plain HTTP (ZK devices do not speak HTTPS reliably — do not put the iClock endpoint behind TLS-only) |
| Device firmware | Any with ADMS / Cloud Server option in the Comm menu (most ZK models since ~2015) |
| Network | Device must reach the server IP on port 5080. Same LAN, or router/VPN route from site to office. Test from a laptop on the device's network: http://<server-ip>:5080 should show the HumanR login page. |
Give the HumanR server a fixed IP (or DHCP reservation). If the server IP changes, every device must be reconfigured at its physical menu.
2. Configure the device (at the machine)
On the device: Menu → Comm. → ADMS (some firmware: Cloud Server Setting / Server Settings):
| Setting | Value |
|---|---|
| Enable Domain Name | OFF (use IP) — or ON with a hostname if you run DNS |
| Server Address | <server-ip> e.g. 192.168.1.10 |
| Server Port | 5080 |
| Enable Proxy Server | OFF |
| HTTPS | OFF |
Also check Menu → Comm. → Ethernet: device has an IP, gateway, and DNS that can reach the server (static IP recommended for the device too, but not required — only the server address matters).
Save and reboot the device (most firmwares apply immediately; reboot forces the first handshake).
There is no username/password in the protocol — HumanR authenticates devices by
serial number whitelist (next step). Everything else in the app requires login; only
/iclock/* is open, and it answers only to known, enabled serial numbers.
3. Enable the device in HumanR (one-time per device)
- As soon as a correctly-configured device first calls in, HumanR auto-registers it in Admin → Attendance Devices — disabled (its punches are rejected with
ERROR: unknown deviceuntil you act). If auto-register is off it simply won't appear; add the serial number manually with the Add row. - Open Admin → Attendance Devices (Admin role), find the serial number (printed on the device sticker and in Menu → System Info), give it a name ("Thilafushi gate") and a work site, tick Enabled, Save.
- The Last seen column updates every time the device talks to the server — this is your health check. A device that stops calling in has a network problem, not a HumanR problem.
4. Map device PINs to staff numbers (one-time per employee)
ZK devices identify people by a numeric user PIN (the user ID enrolled on the machine).
Staff numbers like FS-001 are not valid device PINs, so HumanR keeps a mapping:
Employee → Device PIN.
Two ways to build the mapping:
- Before punches arrive: on the employee's edit page set Device PIN to the number the person is enrolled under on the machine.
- After punches arrive (easier in practice): let people punch, then open Attendance → Unmapped PINs. Every unknown PIN is listed with its punch count and first/last time. Type the staff number next to a PIN and Map — the PIN is saved on the employee and all past punches for that PIN are claimed retroactively. Nothing is lost while unmapped.
Rules: one PIN belongs to at most one employee (the screen enforces uniqueness). Enroll the same PIN for the same person on every device they use — the mapping is by PIN, not per-device.
Tip for new enrollments: use the numeric part of the staff number as the PIN (FS-023 → 23 or 1023 for uniqueness across series) so mapping is guessable. Any scheme works as long as PINs are unique per person.
5. Verify end-to-end
- Punch on the device (enrolled finger/face/card).
- Within ~30 seconds: Attendance → Punches for today shows the punch (device pushes in near-real-time; some firmwares batch a minute or two).
- Within 15 minutes: Attendance dashboard day counts update — the rollup job recomputes today and the two previous days every 15 minutes, marking punched employees Present with first-in / last-out times.
- Attendance → Monthly accumulates into the 25th→24th salary-period summary (CSV export for payroll).
Re-pushed logs are harmless: the same punch (device + PIN + timestamp) is stored once, so device "resend all" operations never create duplicates.
6. Troubleshooting
| Symptom | Check |
|---|---|
| Device never appears in Devices list | Network: can a laptop on that LAN open http://<server-ip>:5080? Server address/port typo on device? Proxy accidentally ON? |
| Device listed but Last seen is old | Device lost network or was reconfigured. Check cable/Wi-Fi, ping the device IP, reboot the device. |
Punches rejected (ERROR: unknown device in server logs) | Device exists but Enabled is unticked in Admin → Attendance Devices. |
| Punch visible in Punches but employee shows Absent | PIN not mapped — check Attendance → Unmapped PINs. Rollup runs every 15 min; use the Recompute button on the Attendance page to force it. |
| Person marked Absent while abroad | Their leave record should cover the date (status Gone), or employee status OnLeave — the rollup then marks OnLeave, never Absent. |
| Wrong punch time | Check device clock/timezone (Menu → System → Date Time; Maldives UTC+5). HumanR stores device-local time as-is; the handshake also tells devices TimeZone=5. |
| Machine broken / site offline for days | Enter punches manually: Attendance → Punches → Manual punch (records who/when/why, flagged IsManual for audit). Once the device is back online it re-pushes its stored logs — duplicates are impossible, gaps self-heal. |
Server-side visibility: run the app with console logs — every /iclock call is
logged with SN, table, and line counts.
7. Rollout checklist per site
- ☐ Server reachable from site network on port 5080 (test with a browser)
- ☐ Device: ADMS server address + port set, proxy off, clock correct (UTC+5)
- ☐ Device appears in Admin → Attendance Devices; named, site assigned, Enabled
- ☐ Staff enrolled on device; PINs mapped (Attendance → Unmapped PINs is empty)
- ☐ Test punch appears in Attendance → Punches; person goes Present after rollup
- ☐ Site supervisor knows the manual-punch fallback and who to call