---
title: "5.0 Synchronization Process"
space: "ZKTeco Biometric Integration for FrappeHR"
url: "https://docs.navari.co.ke/zkteco/60-synchronization-process"
updated: "2026-05-24"
---

# Synchronization Process

The following describes what happens inside each sync cycle in detail.

### Step 1: Scheduler fires

Frappe's background scheduler evaluates all active `ZKTeco Biometric Settings` documents. For each document where **Enable** is checked and the configured frequency interval has elapsed since `last_sync_timestamp`, the sync job is triggered.

### Step 2: Authenticate

The system checks whether the stored JWT token is valid. If it has expired or is absent, re-authentication is performed using the stored credentials. A fresh token is stored before proceeding.

### Step 3: Fetch transactions

The system calls the device's transaction endpoint:

```
GET {URL}/iclock/api/transactions/
```

The request includes filter parameters based on `last_sync_timestamp` to retrieve only new records since the last successful sync. The device returns a paginated JSON payload of punch records.

### Step 4: Process each punch record

For each transaction record returned:

1. Read the `emp_code` field.
2. Query FrappeHR for an Employee whose Biometric ID matches `emp_code`.
3. If no match: log the error and skip.
4. If match found: check whether an Employee Check-in already exists for that employee at that exact timestamp. If a duplicate is found: skip.
5. If no duplicate: determine the log type. ZKTeco punch states are mapped as follows:


| ZKTeco Punch State | FrappeHR Log Type                      |
| ------------------ | -------------------------------------- |
| 0 (Check-In)       | IN                                     |
| 1 (Check-Out)      | OUT                                    |
| Other values       | Mapped to IN by default (configurable) |


 

6. Create the `Employee Checkin` document with fields: `employee`, `time` (punch timestamp), `log_type` (IN/OUT), `device_id` (device URL for traceability).

### Step 5: Update sync timestamp

After all records are processed, `last_sync_timestamp` is updated to the current time on the settings document. This prevents re-fetching already-processed records on the next cycle.

### Step 6: Post-checkin device user control

After creating each Employee Check-in record, the integration calls the device's user management API to enable or disable the user on the device, based on the log type.