How to Connect ZKTeco to Odoo: Cloud API Integration Guide

The ZKTeco-Odoo Integration Problem Every Developer Hits

You have a ZKTeco fingerprint scanner in your office. You have Odoo managing your HR. Connecting them should take an afternoon. Instead, you discover that every existing solution requires your Odoo server to be on the same local network as the device.

That works if Odoo runs on a PC under your desk. It does not work if you use Odoo Online, Odoo.sh, or any cloud-hosted instance — which in 2026, most companies do.

Why Traditional Approaches Fail

The three tools developers find first — pyzk, node-zklib, and Odoo App Store modules — all share the same fatal flaw: they need direct TCP access to the ZKTeco device on port 4370.

Odoo Online? You cannot install Python libraries. pyzk is impossible.

Odoo.sh? You cannot access local hardware. Same result.

Self-hosted Odoo on a VPS? Your device is in your office, your server is in a data center. You need a VPN tunnel, a static IP, or port forwarding — all of which break regularly and create security risks.

For companies with multiple offices, the problem multiplies. Each location needs its own VPN, its own static IP, its own firewall rules. One ISP change breaks the whole setup.

The Cloud API Solution: How PunchConnect Works

PunchConnect sits between your ZKTeco device and Odoo. The device pushes attendance data to PunchConnect's cloud. Odoo pulls it through a standard REST API.

No VPN. No static IP. No local software. The device connects outbound over HTTPS — the same way your phone connects to the internet. Your Odoo instance calls a REST API — the same way it talks to any web service.

Setup time: Under 30 minutes for the full pipeline.

Works with: Odoo Online, Odoo.sh, self-hosted, Community, Enterprise — any version from v14 onwards.

Step 1: Register Your Device

Create a PunchConnect account (7-day free trial, no credit card) and register your ZKTeco device:

Then configure the device through the PunchConnect dashboard — about 5 minutes. The device connects to the cloud automatically.

import requests

API_TOKEN = "pc_live_your_token_here"
BASE = "https://api.punchconnect.com"

response = requests.post(f"{BASE}/v1/devices", headers={
    "Authorization": f"Bearer {API_TOKEN}",
    "Content-Type": "application/json"
}, json={
    "serial_number": "BFGH234900045",
    "name": "Main Entrance",
    "location": "Headquarters"
})

print(response.json())

Step 2: Set Up Real-Time Webhooks

Tell PunchConnect where to send attendance events. Every fingerprint scan triggers an instant HTTP POST to your URL:

If you cannot receive webhooks (Odoo Online), skip to Step 3 — you can poll the API instead.

requests.post(f"{BASE}/v1/webhooks", headers={
    "Authorization": f"Bearer {API_TOKEN}",
    "Content-Type": "application/json"
}, json={
    "url": "https://your-odoo.com/api/punchconnect/webhook",
    "events": ["attendance.created"],
    "secret": "your_webhook_secret"
})

Step 3: Sync Attendance to Odoo

Here is the integration that connects everything. This script fetches attendance from PunchConnect and creates records in Odoo via XML-RPC:

Run this as an Odoo scheduled action (ir.cron) every 10 minutes, or as a webhook handler for real-time sync.

import requests, xmlrpc.client
from datetime import datetime, timedelta

# PunchConnect
PC_TOKEN = "pc_live_your_token_here"
PC_BASE = "https://api.punchconnect.com"

# Odoo
ODOO_URL = "https://your-company.odoo.com"
common = xmlrpc.client.ServerProxy(f"{ODOO_URL}/xmlrpc/2/common")
uid = common.authenticate("your-db", "admin@company.com", "api_key", {})
models = xmlrpc.client.ServerProxy(f"{ODOO_URL}/xmlrpc/2/object")

# Fetch recent punches
since = (datetime.utcnow() - timedelta(hours=1)).isoformat() + "Z"
records = requests.get(f"{PC_BASE}/v1/attendance", headers={
    "Authorization": f"Bearer {PC_TOKEN}"
}, params={"since": since, "limit": 100}).json()["data"]

# Sync each record to Odoo
for r in records:
    emp = models.execute_kw("your-db", uid, "api_key",
        "hr.employee", "search",
        [[[" barcode", "=", r["employee_id"]]]])
    if not emp:
        continue
    if r["direction"] == "in":
        models.execute_kw("your-db", uid, "api_key",
            "hr.attendance", "create",
            [{"employee_id": emp[0], "check_in": r["timestamp"]}])

Step 4: Push Employees to the Device

New hires should appear on the fingerprint scanner automatically:

employees = models.execute_kw("your-db", uid, "api_key",
    "hr.employee", "search_read",
    [[[" active", "=", True]]], {"fields": ["name", "barcode"]})

requests.post(f"{PC_BASE}/v1/employees/sync", headers={
    "Authorization": f"Bearer {PC_TOKEN}",
    "Content-Type": "application/json"
}, json={"employees": [
    {"id": e["barcode"], "name": e["name"]}
    for e in employees if e["barcode"]
]})

Which Odoo Deployment Works?

- Odoo Online — Cannot install pyzk. PunchConnect is the only viable option. Use polling (scheduled action) since you cannot receive inbound webhooks.
- Odoo.sh — Cannot access local hardware. PunchConnect works via webhooks or polling.
- Self-hosted — Could use VPN + pyzk, but it takes hours and breaks when IPs change. PunchConnect takes 30 minutes and never breaks.

For multi-location deployments, the difference is dramatic. A VPN setup requires per-site configuration. PunchConnect handles all devices from one dashboard and one API — whether you have 2 devices or 200.

Pricing

$200 per device — one-time license. No monthly fees. No per-user charges.

Volume discounts: $180 at 10+ devices, $160 at 25+, custom pricing at 50+.

PunchConnect currently powers attendance for 24,000+ active employees across 50+ sites in production. Read the AgriWise case study for the full story.

Frequently Asked Questions

Can I connect ZKTeco to Odoo Online without local software? Yes. PunchConnect is a cloud REST API — your ZKTeco device syncs to PunchConnect's cloud, and Odoo Online fetches data via HTTPS. No local software, VPN, or static IP required.

Which ZKTeco models work with PunchConnect? Most modern models: K-series, uFace, SpeedFace, ProFace, MB-series. If it has cloud/web server capability, it works. Contact us to verify your specific model.

How fast does attendance data reach Odoo? With webhooks: 1-3 seconds. With polling: depends on your interval (typically 5-15 minutes).

Do I need to install anything on the ZKTeco device? No. You configure a few settings on the device's admin panel through the PunchConnect dashboard. No firmware update, no SDK, no custom software.

How does PunchConnect compare to pyzk? pyzk is free but requires LAN access, only supports polling, and breaks with firmware updates. PunchConnect is $200/device, works over the internet, supports real-time webhooks, and handles device protocol differences automatically.

Start Connecting in 15 Minutes

Start your free 7-day trial — no credit card. Register your ZKTeco device, configure it through the dashboard, and run the sync script above. Your biometric attendance data will be flowing into Odoo before lunch.

Need help with your specific setup? Contact us — we have experience with every ZKTeco firmware variant and every Odoo deployment model.