My Experience Successfully Integrating ZKTeco Attendance Device with Laravel

mohamed kamel — Wed, 16 Apr 2025 07:55:37 +0000

In attendance management system projects, one of the biggest challenges was reliably and stably integrating a fingerprint device with a PHP Laravel-based system.

I tried libraries… I got tired. Looked into SDKs… gave up.
But in the end…
I found the solution! I'm sharing my full experience below 👇

The Challenge: Issues with Traditional Libraries

For example:
I used the library mehedijaman/laravel-zkteco, but it failed when connecting externally (on a VPS).
https://github.com/mehedijaman/laravel-zkteco

Reason:
The device operates on a local network (192.101.x.x), while the system is hosted on a remote server.

ZKTeco SDK tools (work only locally)

Solutions that rely on UDP/Port 4370

All of them work locally (localhost), but they:

Don't work on external hosting (WHM/VPS)

Don’t support some ZKTeco models

Require apps to always run on the same network

The Best & Most Reliable Solution:
ZKBioTime + Port Forwarding + Laravel API Integration

After deep research, I discovered the only trusted solution 🔐 is using ZKBioTime API by ZKTeco.

Device Used and Connectivity Method:

I used the ZKTeco SpeedFace V5L, an advanced device that supports both facial recognition and fingerprint scanning.

Connected via Wi-Fi:
Instead of connecting the device using a LAN cable, I opted for a wireless connection to reduce wiring and simplify the infrastructure.

I made sure that:

The device is connected to the same Wi-Fi network as the local server

The device IP is static so it doesn’t change on every reboot

The Cloud Server settings on the device are configured to send data

Important Note:
Even though the device is on Wi-Fi, it must be in the same network as ZKBioTime. Otherwise, synchronization will fail.

Steps for Successful Integration:

1️⃣ Install mehedijaman/laravel-zkteco library in Laravel
2️⃣ Update connection config:
Located at: config/zkteco.php

3️⃣ Install the official ZKBioTime software on a local server in the same network
4️⃣ Assign a Static IP to the ZKTeco device
5️⃣ Update ZKTeco Cloud Server Settings:
Server Address = 00.000.00. (Your Laravel server IP)
Port = 4370

6️⃣ Enable Port Forwarding on your router:
Forward port 4370 to the device's local IP 00.000.00

7️⃣ Open the port in the firewall using iptables + firewalld on the server

8️⃣ Connect ZKBioTime with the device and make sure the logs appear live

9️⃣ Test ZKBioTime API using Laravel

Handling Attendance Data:

ZKBioTime doesn’t send "in" or "out" flags — it only sends punch timestamps.

So I developed custom logic inside Laravel:

First punch of the day = “Clock In”

Last punch before shift end = “Clock Out”

With validation of time and employee status

Smart Syncing (e.g. Every 10 Minutes):

I created a Scheduled Job in Laravel

It fetches punches from /iclock/api/transactions/
(Path: App\Console\Kernel.php)

Stores them in the attendances table with logic to identify Clock In/Out

Then I activated a Cron Job on the server

Every 10 minutes, attendance data updates automatically ✅

Frequently Asked Questions:

Does the device need Internet?
Yes, and it must be on the same network as ZKBioTime.

Does this work with all ZKTeco models?
Yes, as long as ZKBioTime supports the device, Laravel just reads from the API.

Is ZKBioTime considered middleware?
Yes — it's an official API gateway that lets you communicate with the device without SDKs or USB connections.

Can the router change the IP?
Yes — use a Static IP and check DHCP Lease settings.

Can this work with a remote server?
Yes — via Port Forwarding and open ports.

Do I need an internal/local server?
Yes — to install ZKBioTime, which must be on the same network as the device.

The Final Result:

✅ A fully working, stable attendance system
🔁 Auto-sync every 10 minutes
🕒 Accurate clock-in and clock-out times
📊 Real-time & accurate data
📅 100% integrated with shifts, leaves, and reporting

If you're a developer or business owner facing the same challenge — this setup is the solution.
And if you need help integrating your device, DM me or drop a comment ✌️

DEV Community: mohamed kamel

My Experience Successfully Integrating ZKTeco Attendance Device with Laravel