ZKTeco Biometric Attendance Sync

Key Features

Registers each terminal in a `ZKTeco Device` DocType (IP, port, serial, location, poll interval, active flag) for a single-site multi-device fleet

Pulls attendance transactions over the ZK protocol and inserts native ERPNext `Employee Checkin` records with correct `log_type` (IN/OUT) and device timestamp

Maps device biometric user IDs to ERPNext `Employee` via a dedicated mapping DocType, so re-enrolled or shared devices resolve correctly

De-duplicates on `device serial + transaction ID`, guaranteeing a re-poll or overlap window never creates a double punch

Scheduler-driven polling via `hooks.py` `scheduler_events` at your chosen interval, or event-driven ingestion for push-firmware devices

Runs device I/O through `frappe.enqueue` background jobs so slow or offline terminals never block the ERPNext request cycle

Offline buffering with a per-device last-read cursor plus exponential-backoff retry, back-filling missed punches in timestamp order on reconnect

Multi-location support: each device carries its own location/branch so check-ins land against the right shift and cost center

`ZKTeco Sync Log` DocType records every poll — records fetched, inserted, skipped-as-duplicate, and errors — for a full audit trail

Whitelisted methods expose a manual `Sync Now` action and a device health/heartbeat check callable from a client script button or the REST API

Doc events on `Employee Checkin` leave your existing Auto Attendance / shift-based `Attendance` generation working untouched

Permissions enforced through Frappe role profiles — only HR/admin roles can edit device config, remap employees, or replay a sync

Configurable IN/OUT resolution (device state, alternating logic, or first-in/last-out per shift) to match how your terminals report

Built and tested against Frappe/ERPNext v15 and v16, packaged as an installable app via `bench get-app` / `bench install-app`

Built to order, done for you

No DIY setup — a working app, built, installed and supported by ECOSIRE.

You order

Start with a one-time build price. We scope it with you at kickoff.

We build & install

ECOSIRE builds, configures and installs it on your ERPNext.

Go live + support

You go live in about 2–4 weeks, with a post-launch support window.

About this Product

Most ERPNext teams running ZKTeco or ZKBio hardware end up in the same place: punches live on the device, and someone exports a spreadsheet every morning to reconcile them by hand. ERPNext ships an Employee Checkin DocType and can turn those check-ins into Attendance via the Auto Attendance / shift logic, but it has no built-in connector to ZKTeco's proprietary protocol. There is no native poller, no device registry, no employee-to-biometric-ID mapping, and nothing to handle a device that drops off the network for two hours. That gap is exactly where a full month of overtime and shift calculations quietly goes wrong.

ECOSIRE builds a proper Frappe app — its own module, DocTypes, and hooks.py scheduler events — that closes the loop. We add a ZKTeco Device DocType to register each terminal (IP/port, location, serial, active flag, poll interval) and a ZKTeco Sync Log DocType for a full audit trail of every pull. A scheduler event (or a real-time listener where your firmware supports live push) connects to each device using the ZK protocol, reads new attendance transactions, maps the device's biometric user ID to the correct ERPNext Employee through a mapping table, and inserts Employee Checkin records with the correct log_type (IN/OUT) and timestamp. De-duplication is keyed on device serial plus transaction ID so a re-poll never double-counts a punch, and the connector supports multiple devices across multiple locations from one ERPNext site.

Under the hood it uses frappe.enqueue for background polling so device I/O never blocks the request cycle, whitelisted methods for a manual "Sync Now" button and health checks, and doc events on Employee Checkin so your existing Auto Attendance rules keep working untouched. Offline resilience is first-class: when a device is unreachable the app buffers the last-read cursor per device and retries with backoff on reconnect, then back-fills the missed window in timestamp order — no lost punches, no duplicate ones. Permissions are wired through Frappe role profiles so only HR/admin roles can edit device config or replay a sync, and all of it is tested against Frappe/ERPNext v15 and v16.

Because this is build-to-order, nothing ships until we agree on your exact scope. We start with a short scoping call to confirm your device models (ZKTeco push vs. pull firmware, ZKBio middleware, or direct TCP), site/location layout, sync cadence, and how you want IN/OUT resolved. We then build against a staging copy of your ERPNext, run UAT with your real device data, and only cut over to production with a rollback plan in hand. Typical delivery is 2 to 4 weeks from confirmed scope, and you receive the full source code and git repository so you are never locked in.

What you get

Installable Frappe app source code for your ERPNext version (v15 or v16), packaged for `bench get-app` / `bench install-app`

Installation and configuration on your environment, including device registration, employee-ID mapping, and scheduler/interval setup

Technical documentation: DocType reference, `hooks.py` events, whitelisted methods, and device-connection/config notes

User guide plus a live training session for HR/admin staff covering device setup, manual sync, and reading the sync log

UAT on a staging copy of your ERPNext with your real device data, plus a documented production cutover and rollback plan

Post-go-live support window for bug fixes and adjustments after launch

Full git repository handover so you own the code with no vendor lock-in

Who this is for

HR / Payroll Manager

Runs monthly attendance and payroll in ERPNext and is tired of exporting device logs to Excel every morning. Needs trustworthy `Employee Checkin` data that flows into shift and overtime calculations automatically, with a clear audit trail when a number looks off.

ERPNext System Administrator / IT Lead

Owns the ERPNext deployment and the ZKTeco hardware. Wants a proper Frappe app with clean DocTypes, background jobs, and role-based permissions rather than a fragile cron script — plus the source and git repo so the integration is maintainable in-house.

Multi-Location Operations Manager

Oversees several branches or sites, each with its own ZKTeco terminals. Needs every device polled reliably into one ERPNext site, with punches attributed to the correct location and resilient handling when a branch loses connectivity.

Frappe / ERPNext Implementation Partner

Delivering ERPNext to an end client and needs a reliable biometric connector without building it from scratch. Wants a tested, documented, handover-ready app they can install, brand, and support under their own engagement.

How ZKTeco Biometric Attendance Sync Compares

Criterion	ECOSIRE	Custom Build	Competitor
ZKTeco connectivity	Built for your exact devices and firmware (pull/push, ZKBio)	Depends entirely on your developer's ZK-protocol experience	Generic connector; may not match your device model
Employee Checkin integration	Writes native `Employee Checkin`; Auto Attendance untouched	Possible, but easy to bypass ERPNext's own logic	Usually writes Checkin, quality varies
De-duplication & offline buffering	Serial+txn dedupe, per-device cursor, retry-and-backfill	Only if explicitly built and tested	Often basic; offline handling frequently weak
Multi-device / multi-location	Per-device registry with location tagging, one site	Buildable but adds scope and testing	Varies; some are single-device only
Source code & ownership	Full source + git repo handover, no lock-in	You own it, but you also carry all the risk	Often closed or license-gated
ERPNext v15/v16 support	Built and tested against both	Whatever your team validates	May lag on version compatibility
Support & warranty	Post-go-live support window + optional retainer	Depends on your in-house availability	Marketplace support, quality varies
Time to working solution	2-4 weeks build-to-order with UAT + rollback	Unpredictable; often longer once edge cases surface	Fast to install, but rework if it fits poorly

Frequently Asked Questions about ZKTeco Biometric Attendance Sync

How long does delivery take?

This is a build-to-order app, so it is built for your specific device fleet and site layout — not an instant download. Typical delivery is 2 to 4 weeks from confirmed scope. It begins with a scoping call to lock device models, sync cadence, and IN/OUT logic, followed by the build, UAT on your staging environment, and a planned production cutover.

What support and updates are included?

Every engagement includes a post-go-live support window for bug fixes and adjustments. Because you receive the full source code and git repository, your own team can maintain and extend it afterward. We also offer optional ongoing support and version-upgrade retainers (for example, moving from ERPNext v15 to v16) if you would rather we keep it current.

Which ZKTeco / ZKBio devices are supported?

We support ZKTeco terminals over the standard ZK TCP protocol (both pull and push firmware) and ZKBio middleware setups. During scoping we confirm your exact models, firmware, and whether the device pushes events or must be polled, so the connector is built to match how your hardware actually reports.

Does this replace ERPNext's attendance features?

No — it feeds them. The app writes native `Employee Checkin` records, so your existing ERPNext Auto Attendance, shift assignments, and `Attendance` generation keep working unchanged. It only fills the gap ERPNext core leaves: there is no native connector to ZKTeco hardware, and this provides it.

How does it avoid duplicate or lost punches?

De-duplication is keyed on the device serial plus the transaction ID, so re-polls and overlapping sync windows never create a duplicate check-in. For lost punches, each device keeps a last-read cursor; when a terminal is offline the app buffers, retries with backoff, and back-fills the missed window in timestamp order once it reconnects.

Can it handle multiple devices across several locations?

Yes. Each terminal is registered in its own `ZKTeco Device` record with its own IP, serial, location, and poll interval, and all of them sync into a single ERPNext site. Check-ins are tagged with the correct location so they roll up to the right branch, shift, and cost center.

Do we own the code, or is it locked to ECOSIRE?

You own it. We hand over the complete git repository and installable source for your ERPNext version. There is no license server and no lock-in — your team can read, modify, and redeploy the app independently.