Biometric Attendance for ERPNext: Connect ZKTeco Devices via Cloud REST API

Introduction

Setting up biometric attendance for ERPNext should be a solved problem by now. ZKTeco devices are deployed in thousands of offices worldwide, and ERPNext is one of the fastest-growing open-source ERPs. But if you have tried connecting the two, you know the reality: fragile Python scripts, LAN-only access, manual cron jobs, and attendance records that arrive hours late — if they arrive at all.

This tutorial shows a different approach. Instead of running local sync scripts, you will use a cloud REST API that receives punch data from your ZKTeco devices in real time and pushes it directly into ERPNext via webhooks. No VPN, no static IP, no local software on your ERPNext server.

How ERPNext Handles Biometric Attendance Today

ERPNext (now part of the Frappe HR ecosystem) has an official tool for biometric integration: the Biometric Attendance Sync Tool maintained by the Frappe team on GitHub. Here is how it works and where it breaks down.

The official approach requires you to install pyzk or a similar library on a machine that shares a local network with your ZKTeco device. A Python script polls the device over TCP, pulls attendance logs, and writes them to ERPNext via the Frappe API. You schedule this script with cron — typically every 10 to 30 minutes.

This works for a single office with one device on the same network as a self-hosted ERPNext instance. It falls apart in every other scenario.

The LAN constraint is the core problem. If your ERPNext instance runs on Frappe Cloud, you cannot install pyzk on their servers. If your devices are in branch offices across different networks, each location needs its own sync machine. If your office network uses DHCP (most do), the device IP can change and break the connection silently.

The sync delay is the second problem. Cron-based polling means attendance data is 10-30 minutes stale. For shift-based operations — manufacturing floors, warehouses, agricultural sites — that delay creates payroll disputes and compliance gaps.

The maintenance burden is the third problem. The pyzk library has known compatibility issues across ZKTeco firmware versions. Device model A works fine; device model B returns garbled data. You discover this at 2 AM when attendance stops syncing and nobody notices until payroll runs.

The Cloud API Approach: Why It Works Better

Instead of pulling data from devices, a cloud API flips the model: the device pushes attendance data to the cloud, and the cloud pushes it to your ERPNext instance via webhooks.

Here is what changes with this architecture.

No LAN requirement. The ZKTeco device connects to the cloud over standard HTTPS. As long as the device has internet access — WiFi, Ethernet, even a mobile hotspot — it works. Your ERPNext instance can be on Frappe Cloud, a VPS in another country, or a server under your desk. The device and ERP never need to be on the same network.

Real-time data. Attendance events arrive within seconds of the punch, not on a 10-minute cron cycle. When an employee scans their fingerprint at 8:00:01 AM, your ERPNext instance knows about it by 8:00:03 AM.

No local software. Nothing to install on your ERPNext server. No pyzk, no sync scripts, no cron jobs. The integration is a webhook endpoint that receives JSON payloads — something any ERPNext custom app can handle in 50 lines of code.

Multi-site by default. 100 devices across 20 offices? They all push to the same cloud endpoint. One dashboard, one API, one webhook configuration. No per-site sync infrastructure.

Step-by-Step: Setting Up Biometric Attendance for ERPNext with PunchConnect

Here is the full setup, from device registration to attendance records appearing in ERPNext. Total time: about 30 minutes.

Prerequisites

You need three things before starting.

An ERPNext instance (v14 or later) with API access enabled. This can be Frappe Cloud, a self-hosted instance, or ERPNext on Docker — any deployment works.

A ZKTeco biometric device with internet connectivity. PunchConnect supports any ZKTeco-compatible device with a built-in web server — that includes the SpeedFace V5L, ProFace X, uFace 800, MB460, and dozens of other models.

A PunchConnect account with your API key. The 7-day free trial gives you full API access, no credit card required.

Step 1: Register Your Device in PunchConnect

Log into the PunchConnect dashboard and add your device. You will get a unique device identifier and connection instructions specific to your device model. Configure your ZKTeco device to connect to PunchConnect through the dashboard — the setup takes about 2 minutes per device.

Once connected, verify the device appears as "online" in your dashboard. You can test it by scanning a fingerprint and watching the event appear in real time.

Step 2: Configure a Webhook for ERPNext

Set up a webhook in PunchConnect that fires on every attendance event. Point it at your ERPNext instance.



The response confirms your webhook is active:

Step 3: Build the ERPNext Webhook Receiver

Create a custom Frappe app (or add to an existing one) with a whitelisted API method that receives punch data and creates Attendance records.



This code does four things: verifies the webhook signature to prevent spoofed requests, maps the device employee ID to an ERPNext Employee record, determines check-in vs. check-out direction, and creates an Employee Checkin document that feeds into ERPNext's automatic attendance system.

Step 4: Map Employees Between Systems

Each employee in ERPNext needs an attendance_device_id field that matches their ID on the ZKTeco device. You can retrieve all enrolled employees from PunchConnect:



Then update your ERPNext Employee records with the matching device IDs. For bulk mapping, use the ERPNext Data Import tool with a CSV that has two columns: name (ERPNext Employee ID) and attendance_device_id (device employee ID).

Step 5: Let ERPNext Auto-Attendance Do the Rest

ERPNext v14+ includes an Auto Attendance feature that converts Employee Checkin records into Attendance entries. Enable it in HR Settings > Auto Attendance and configure your shift types.

Once enabled, the full pipeline runs automatically: device captures punch → PunchConnect receives it in real time → webhook fires to your ERPNext instance → Employee Checkin is created → Auto Attendance processes it into an Attendance record with correct shift assignment.

Pulling Historical Attendance Data

When you first set up the integration, you may need to backfill attendance records that were captured before the webhook was configured. PunchConnect's REST API lets you query historical data by device and date range:



This is useful for initial migration and for reconciling any gaps if a webhook delivery fails (PunchConnect automatically retries failed deliveries 3 times over 24 hours, but you can always backfill manually).

Comparing the Approaches: Manual Sync vs. Cloud API

Here is how the two approaches compare across the dimensions that matter for production deployments.

Network requirements. The pyzk approach requires the sync machine and ZKTeco device to share a LAN. The cloud API approach requires only internet access on the device — no VPN, no static IP, no port forwarding.

Data freshness. Manual sync runs on a cron schedule, typically delivering data 10-30 minutes after the punch. The cloud API delivers data in 1-3 seconds via webhooks.

Deployment complexity. Manual sync needs a dedicated machine per site running Python, pyzk, and cron. The cloud API needs one webhook endpoint on your ERPNext instance — that is it.

Multi-site support. With manual sync, each branch office needs its own sync infrastructure. With the cloud API, 100 devices across 50 sites all push to one endpoint.

Reliability. pyzk is sensitive to firmware differences and can fail silently when device IPs change. The cloud API handles device communication independently and retries failed webhook deliveries automatically.

Cost. The pyzk approach is free (open source) but costs engineering time to maintain. PunchConnect is $200 per device with a $50/year renewal — predictable cost with zero maintenance overhead.

For a 10-device deployment across 3 offices, the manual approach requires 3 sync machines, 3 cron configurations, and ongoing maintenance. The cloud API approach requires one webhook endpoint and 10 device licenses at $2,000 total — roughly the cost of a single day of developer time spent debugging pyzk firmware issues.

Frequently Asked Questions

Does biometric attendance for ERPNext work with Frappe Cloud?

Yes. Since PunchConnect sends data via webhook to a standard Frappe API endpoint, it works with any ERPNext deployment — including Frappe Cloud, ERPNext on Docker, and self-hosted instances. The ZKTeco device and ERPNext server do not need to be on the same network.

Which ZKTeco devices are compatible with this integration?

PunchConnect supports any ZKTeco-compatible device with a built-in web server. This includes popular models like the SpeedFace V5L, ProFace X, uFace 800, MB460, iClock 680, and many others. If your device supports cloud connectivity, it will work with PunchConnect.

Can I use this alongside the existing Frappe biometric-attendance-sync-tool?

Yes. The webhook receiver creates standard Employee Checkin documents — the same doctype the official sync tool uses. You can run both in parallel during migration. Once you have confirmed the cloud API is capturing all punches, disable the cron-based sync script.

How does PunchConnect pricing compare to building my own sync infrastructure?

PunchConnect costs $200 per device with a $50/year renewal starting in Year 2. For 10 devices, that is $2,000 upfront and $500/year. Building and maintaining your own sync infrastructure across multiple sites typically costs 20-40 hours of developer time for initial setup plus ongoing maintenance — at standard developer rates, the cloud API pays for itself within the first month.

What happens if my ERPNext server is temporarily down?

PunchConnect stores attendance data and retries failed webhook deliveries 3 times over 24 hours. You can also use the REST API to pull historical attendance data for any date range, so no data is ever lost even during extended outages.

Get Started in 30 Minutes

The fastest way to set up biometric attendance for ERPNext is to start with a single device. Sign up for the 7-day free trial — no credit card required — register your ZKTeco device, configure the webhook, and deploy the 50-line Python receiver above. You will have real-time attendance data flowing into ERPNext before lunch.

If you are evaluating options for a larger deployment, check the PunchConnect pricing page for volume discounts or contact the team for enterprise deployments with 50+ devices.