ZKTeco → ERPNext Middleware Desktop App

A Windows desktop middleware application that connects to a ZKTeco biometric attendance device, fetches attendance logs, maps them to ERPNext Employee Checkin, and syncs records using ERPNext REST API.

Project Structure

• src/ — application source modules
• config/settings_example.json — sample local configuration
• db/schema.sql — SQLite database schema
• requirements.txt — Python dependencies
• README.md — setup and usage guide

Features

• Connects to ZKTeco device over LAN (TCP/IP)
• Fetches fingerprint and face attendance logs
• Converts logs for ERPNext Employee Checkin
• Supports device user → ERPNext employee mapping
• Avoids duplicate records using local SQLite storage
• Retries failed syncs and caches offline logs
• Simple PyQt5 desktop UI with status/log panel
• Optional REST API server for remote control

Setup Guide

1. Install Python 3.10+ on Windows.
2. Open PowerShell in the project folder.
3. Create a virtual environment:

python -m venv .venv
.\.venv\Scripts\Activate.ps1

4. Install dependencies:

python -m pip install --upgrade pip
python -m pip install -r requirements.txt

5. Copy sample configuration:

copy config\settings_example.json settings.json

6. Edit settings.json with your device details and ERPNext credentials.
7. Run the desktop app:

python src\main.py

Convert to .exe with PyInstaller

1. Install the application dependencies and PyInstaller:

py -3.14 -m pip install --upgrade pip
py -3.14 -m pip install PyQt5 requests Flask python-dateutil
py -3.14 -m pip install pyinstaller

If you need ZKTeco device communication, also install the zk package:

py -3.14 -m pip install zk

Note: zk may require Microsoft C++ Build Tools on Windows.

2. Build the executable manually:

py -3.14 -m PyInstaller --onefile --windowed --paths src src\main.py --name "ZKTecoERPNextSync"

3. Or run the helper script:

build_exe.bat

3. The executable will be in dist\ZKTecoERPNextSync.exe and settings.json will be copied next to it.

Create a Windows installer

If you have NSIS installed, run:

build_installer.bat

This uses installer.nsi to build ZKTecoERPNextSyncInstaller.exe.

SQLite Database Schema

The database stores cached device logs, synced records, and sync metadata. See db/schema.sql.

Running the REST API Server

If you want remote status or an HTTP trigger for sync, run:

python src\api_server.py

Then use these endpoints:

• GET /api/health
• POST /api/sync
• GET /api/config
• POST /api/config
• GET /api/logs

Notes

• Ensure your ERPNext site has Employee records that can be matched to the device user IDs.
• If your ERPNext Employee doctype uses a custom biometric field, update the matching logic in src/erpnext_client.py.
• The project is designed to be extendable for multi-device support and service startup integration.