Skip to main content

​
Get Started in 5 Minutes

This guide will help you set up and test the ZKTeco Biometric Server quickly.
1

Install Dependencies

Install Python 3.7+ and the required packages:
pip install flask pyzk pyopenssl requests psycopg2-binary
Or install from requirements.txt:
pip install -r requirements.txt
2

Configure Your Device

Set environment variables for your ZKTeco device connection:
export ZK_IP="192.168.1.205"
export ZK_PORT="4370"
export API_PORT="5000"
The server will auto-generate self-signed SSL certificates (cert.pem and key.pem) on first run if pyopenssl is installed.
3

Start the Server

Run the server using either implementation:
python servidor.py
You should see output like:
2026-03-06 10:30:00 [INFO] Certificados SSL generados.
2026-03-06 10:30:00 [INFO] Servidor ZKTeco en https://0.0.0.0:5000
2026-03-06 10:30:00 [INFO] Biometrico: 192.168.1.205:4370
Single Device Mode (servidor.py): Connects to one biometric device configured via environment variables.Multi-Device Mode (server.py): Manages multiple devices dynamically via REST API.
4

Test the Server

Verify the server is running:
curl -k https://localhost:5000/
Expected response:
{
  "status": "online",
  "device_ip": "192.168.1.205",
  "device_port": 4370,
  "timestamp": "2026-03-06 10:30:15"
}
Use -k flag with curl to skip SSL certificate verification for self-signed certificates.
5

Fetch Device Information

Get detailed information about your biometric device:
curl -k https://localhost:5000/device/info
Expected response:
{
  "success": true,
  "data": {
    "serialnumber": "BBGW201960001",
    "device_name": "ZKTeco",
    "platform": "ZEM600_TFT",
    "firmware_version": "Ver 6.60 Apr 14 2017",
    "users_count": 15,
    "device_time": "2026-03-06 10:30:20"
  }
}
6

Retrieve Attendance Records

Fetch attendance records from the device:
curl -k https://localhost:5000/attendance
Expected response:
{
  "success": true,
  "total": 2,
  "data": [
    {
      "user_id": "5",
      "timestamp": "2026-03-06 08:30:15",
      "status": 1,
      "punch": 0
    },
    {
      "user_id": "12",
      "timestamp": "2026-03-06 08:25:43",
      "status": 1,
      "punch": 0
    }
  ]
}

​
Next Steps

API Reference

Explore all available endpoints and their parameters

Device Management

Learn how to manage multiple biometric devices

User Management

Create, update, and delete users on devices

Advanced Features

Fingerprint enrollment, time sync, and more
Production Deployment: Replace self-signed SSL certificates with proper certificates from a trusted Certificate Authority before deploying to production.

Build docs developers (and LLMs) love

Get started for freeTalk to us