ZKTeco Fingerprint Attendance in Odoo, Saudi Arabia: 2 Ways, 7 Checks

There are two ways to connect a ZKTeco fingerprint, face or card terminal to Odoo Attendances. Either Odoo reads the punches from the device over the office network (pull), or the device sends each punch to Odoo the moment it is made (push, called ADMS or Cloud Server on the device). You choose per device, and one database can mix both.

• Pull: Odoo, or a program in the office, connects to the device with the ZK protocol on port 4370 by default (TCP or UDP), using its IP address and communication key, and downloads the punch log on a schedule or on demand. The device must be reachable: same network, a VPN or port forwarding.
• Push (ADMS / Cloud Server): the device calls the server over HTTP or HTTPS each time someone punches, and is recognised by its serial number. It only needs internet access, so it stays behind the office router, and punches arrive in real time.

Which one fits:

• Odoo on a server in your office: both work, and pull suits older terminals.
• Odoo.sh or any hosted Odoo: push. A cloud server cannot reach a device in your office without port forwarding or a VPN.
• Odoo Online: neither directly. A small bridge program on an office computer reads or receives the punches and forwards them, as explained below.
• Several branches: push, so each branch needs only an internet line, not a VPN to head office (on Odoo Online, one bridge per branch).
• A terminal with no Cloud Server or ADMS menu: pull only.

For example, a Riyadh company with a Dammam branch on Odoo.sh sets both terminals to push, and each sends its punches straight to the company's Odoo address. Our Odoo Online vs Odoo.sh guide covers the hosting choice itself.

Either way, whether payroll can trust the result is decided before and after the connection: device checks, matching users to employees, and rules for double punches and forgotten check-outs.

Spend twenty minutes at each terminal before anyone opens Odoo; most failed connections trace back to one of these seven points.

• Push support: open the communication menu (COMM. on many models) and look for Cloud Server Setting, called ADMS on some firmware. No such menu means pull only.
• HTTPS: if your Odoo is served only over HTTPS, the firmware must support it. Odoo.sh always redirects HTTP to HTTPS, so HTTP-only firmware cannot push to it.
• Serial number: under System Info > Device Info, or on the label on the back. Push devices are registered by it.
• Network for pull: a fixed IP address reserved in the router, port 4370 open between the device and the server or bridge, TCP or UDP, and the communication key set on the device (0 if none).
• Clock and time zone: set the device to Saudi time, Asia/Riyadh, which is UTC+3 all year with no daylight saving, and enter the same time zone in your connector. A device left on UTC makes an employee who arrives at 8:00 appear at 5:00.
• User numbers: one number per person, the same on every terminal, so anyone can punch at any entrance. Keep device admin rights with HR.
• Office public IP: push requests identify a device by its serial number, printed on its label, with no password. If devices push straight to Odoo over the internet, ask your internet provider for a fixed public IP, so your connector accepts punches only from the office address.

The template: a spreadsheet with one row per device and these columns.

• Location and entrance
• Model and firmware version
• Serial number
• IP address, port and protocol
• Communication key
• Time zone
• Mode: pull or push
• HTTPS supported: yes or no
• Last test date and result

One legal point: the Personal Data Protection Law (in Arabic), as amended by Royal Decree M/148 of 5/9/1444 AH, lists biometric data that identifies a person as sensitive data. Keep fingerprint and face templates on the devices; Odoo needs only the user number, time and in/out key of each punch. This is a summary, not legal advice.

Odoo Online runs in Odoo's cloud. It cannot open a connection into your office network, and it cannot install modules that contain Python code. So a ZKTeco connection there needs a small bridge program on an office computer that stays on: it reads the devices or receives their pushes, then sends the punches to Odoo over HTTPS through Odoo's external API, which on Odoo Online is part of the Custom plan.

On Odoo.sh or your own server, a Python module installs normally, push devices call Odoo's address directly, and an office server can also pull. Enterprise there is on the Custom plan anyway; the free Community edition on your own server also has Attendances.

Budget for it. At Odoo's Saudi list prices of 17 October 2026, Custom costs US$32 per user a month on yearly billing (SAR 120), against US$16.90 (about SAR 63) on Standard: SAR 1,200 a month for 10 users instead of about SAR 634, before first-year discounts. Odoo also counts employee records with no linked user. On Odoo 20 its agreement bills them as Light Users, listed at US$5.90 a month (about SAR 22) and quoted only by an Odoo Advisor: about SAR 1,330 a month for 60 workers who only punch. On Odoo 19 or older, get Odoo's billing of those records in writing; our Odoo price guide has the details.

Your options:

• A connector from the Odoo Apps Store. One is ZKTeco Biometric Attendance (Online) by METCH, an official Odoo partner in Saudi Arabia: USD 199 (about SAR 746), shipped with the office bridge, in a 19.0 edition for Odoo Online 19.0 to saas~19.3 and a 20.0 edition for saas~19.4 and later. Its edition for Odoo.sh and on-premise (Odoo 18, 19 and 20) needs no bridge but, as of November 2026, is not listed on the Apps Store, so ask for it in your Odoo request. Support depends on each model's firmware, so check yours first, whichever app you choose.
• Odoo's own Attendances kiosk: a tablet or PC browser with badge barcodes, RFID key fobs or name plus PIN, and no IoT box. It works on Standard but is not biometric, and its URL has no access code, so generate a new one if it leaks.
• Odoo 20's direct integration with eSSL and Mantra biometric devices, per its release notes, if you are buying new terminals.

A punch is only a user number and a time until it is matched to an employee. A good connector adds a device user ID to the employee form and downloads the list of people enrolled on a terminal, so you match names instead of typing numbers. Insist on one thing: punches from a number not yet matched must be kept and processed once you match it, not silently dropped.

Then set the rules that turn punches into check-ins and check-outs:

• Punch mode: either punches alternate in and out, so a lunch break gives two attendances, or the in and out keys pressed on the device decide. Article 102 of the Labor Law keeps rest, prayer and meal breaks out of actual working hours, so let breaks show.
• Duplicate window: a second punch within, say, 3 minutes of the first is ignored, not counted as a check-out.
• Maximum shift: if the next punch comes more than, say, 16 hours after a check-in, the check-out is missing. Close that attendance without hours and flag it for HR; never guess. A night shift from 22:00 to 06:00 fits inside the limit.
• Old punches: set a start date, so a device's first upload does not bring in years of history.

Watch two settings in the Attendances documentation. Automatic Check-Out closes open attendances once the working schedule plus a tolerance has passed, possibly before a late device punch arrives, so give it a generous tolerance. Absence Management logs absences not covered by time off, so a terminal that went offline can make a whole shift look absent until its punches arrive.

A weekly 15-minute HR review:

• Unmatched user numbers: usually new joiners.
• Missing check-outs: correct the time with the employee's manager.
• Punches in error, often a clash with an attendance typed by hand.
• Terminals with no contact for more than an hour.
• Manual edits, each with a one-line reason.

Clean punches matter because the Labor Law (in Arabic) prices every extra hour. As of November 2026:

• Article 98: at most 8 actual working hours a day on a daily standard, or 48 a week on a weekly one. In Ramadan, hours for Muslim workers drop to at most 6 a day or 36 a week; Ramadan 1448 is expected to begin around 8 February 2027.
• Article 101: no more than 5 consecutive hours without a break of at least half an hour for rest, prayer and food, and no more than 12 hours at the workplace in a day.
• Article 107: each overtime hour is paid at the hourly wage plus 50% of the basic wage, and all hours worked on holidays and Eids are overtime. Since the amendments of Royal Decree M/44 took effect on 20/8/1446 AH, the employer may, with the worker's consent, give paid compensatory leave instead.

A worked example. Basic wage SAR 6,000 plus housing SAR 1,500. Article 2 defines the wage as the actual wage, meaning the basic wage plus the other increments due, such as allowances, and a month as 30 days unless the contract or work regulations say otherwise. On 30 eight-hour days, SAR 7,500 ÷ 240 = SAR 31.25, plus 50% of SAR 6,000 ÷ 240 = SAR 12.50: SAR 43.75 per overtime hour, or SAR 525 for 12 hours in a month. Confirm the method with your adviser.

In Odoo, overtime rulesets decide which hours count and at what rate; none come preconfigured. Base one rule on hours above the employee's schedule and one on non-working days; Odoo 20 adds public-holiday rates. Give Muslim employees a 6-hour Ramadan schedule, so overtime starts after 6 hours, not 8. Odoo 20's Saudi payroll can deduct for late attendance, but Article 67 allows only penalties set in the law or your work regulations, and Article 93 caps all deductions at half the wage due. Overtime and deductions then flow into your Mudad WPS file. Test the rules on one payslip with your accountant before go-live.