QClock Attendance Verification Options Guide

Purpose

QClock records employee check-in and check-out activity. Attendance verification helps the company confirm that the right employee is recording the time from an approved place or approved device.

Verification Options

Choose A Company Policy

Before using attendance verification, decide the rules that employees and managers will follow. Keep the rules simple and write them in the same way employees will hear them during training.

• Choose which employees use QClock, fingerprint devices, face devices, or fallback methods.
• Decide whether employees must use an approved computer or an approved attendance device.
• Decide whether photo evidence is required for any role or location.
• Decide who can approve a new attendance device or unregister an old one.
• Decide what employees should do if they forget to check in or check out.
• Decide what managers must review daily, weekly, and before payroll processing.
• Decide how long attendance evidence should be kept according to company policy.

Manager Setup Checklist

1. Confirm that each employee has the correct QBM employee record and user access.
2. Choose the attendance method for each location: QClock, approved computer, fingerprint device, face device, or fallback.
3. Register or approve the computers and attendance devices that employees are allowed to use.
4. Enroll employees on the attendance device when fingerprint or face confirmation is used.
5. Tell employees exactly where to clock in and clock out.
6. Explain the fallback process before the first workday using the new method.
7. Review the first few days of records daily to catch setup mistakes early.

Daily Employee Use

When Using QClock

1. Open QClock from the company link or shortcut.
2. Confirm that your name and current status are correct.
3. Use Check In when starting work.
4. Use Check Out when leaving work.
5. Enter your password or follow the required confirmation step.
6. Add a short note only when the company asks for one or when something unusual happened.
7. Check today's history to confirm that the time was recorded.

When Using A Fingerprint Or Face Device

1. Go to the approved attendance device at your work location.
2. Follow the device prompt for fingerprint, face, badge, or PIN.
3. Wait for a success message before leaving the device.
4. If the device does not accept the attempt, try again once or use the company fallback process.
5. Tell your manager immediately if the device still cannot record your attendance.

Fingerprint And Face Devices

Fingerprint and face devices are normally used at company-controlled attendance points. The device confirms the employee at the location, then the attendance record can be reviewed by managers in QBM.

For step-by-step instructions on enabling and configuring a biometric device with QBMWServices, see Setting Up A Biometric Device.

Good Device Practices

• Place the device where employees can use it easily at the start and end of the workday.
• Keep the device clean and protected from damage.
• For face devices, avoid strong backlight and very dark corners.
• Enroll each employee carefully and test the first check-in before the employee relies on it.
• Keep a fallback method ready for employees who cannot use the biometric method.
• Remove old employee enrollments when an employee leaves the company.

Setting Up A Biometric Device

QClock does not collect a fingerprint or face image in the browser. Biometric attendance is provided by a physical device at the work location (or by vendor middleware connected to one). The device confirms the employee locally and then sends the attendance event to QBM. QClock receives the event, validates the device and the employee, and saves the check-in or check-out so it appears in Clock Review next to browser punches.

What You Need Before You Start

• A biometric attendance device (fingerprint, face, or combined) or vendor middleware that can send HTTP requests in JSON.
• The QBMWServices URL that QClock uses today (the same service address shown in QClock Settings).
• A QBM user marked as Manager who can register and approve attendance devices.
• A way to map each device user (the employee record on the biometric device) to the QBM employee record. The vendor usually provides an external employee identifier.

Step 1. Enable The Integration On The Server

1. Open QBMWServices\appsettings.json on the QBM service host.
2. Set the integration API key so the external device routes are accepted. Every device must send this value back in the X-QClock-Integration-Key header on each punch request:

   "QClock": {
     "ExternalIntegrations": {
       "ApiKey": "<a long random secret known only to QBM and the device installer>",
       "SignatureSecret": "",
       "RequireSignature": false,
       "RequireDeviceHeaders": true,
       "SignatureToleranceMinutes": 5,
       "MaxBatchSize": 100,
       "MaxEventAgeHours": 24,
       "MaxFutureMinutes": 5,
       "FileInbox": {
         "Enabled": false,
         "Path": "",
         "PollSeconds": 10
       }
     }
   }

3. Restart QBMWServices so the new configuration is loaded.

The other knobs are usually left at their defaults. RequireDeviceHeaders keeps the device-code and event-id headers strict. RequireSignature becomes effectively true as soon as a device has its own signing secret (the normal case for a registered biometric device). SignatureToleranceMinutes rejects replays older than the window. MaxBatchSize, MaxEventAgeHours, and MaxFutureMinutes protect against runaway batches and clock-skewed events.

Step 2. Register The Device In QBM

A manager registers each physical device once. Registration assigns the device a code and a per-device signing secret. Save the secret with the device installer; QBM returns it only at registration (and on rotation) and stores it hashed afterwards.

1. Sign in as a QBM Manager and capture the bearer token used by QClock (the same one the web app uses). The registration endpoint requires manager permission.
2. Call the registration endpoint on QBMWServices:

   POST /api/qclock/integrations/devices/register
   Authorization: Bearer <manager token>
   Content-Type: application/json
   
   {
     "deviceCode": "frontdoor-1",
     "deviceName": "Front Door Fingerprint",
     "vendor": "ZKTeco",
     "model": "K40",
     "locationCode": "HQ-LOBBY",
     "timeZone": "Asia/Dubai",
     "integrationMode": "Push",
     "approveImmediately": false,
     "rotateSecret": false
   }

3. Save these fields from the response and keep them with the device installer:
   • deviceId - QBM's internal device id used in approve/disable URLs.
   • deviceCode - the short code the device sends in X-QClock-Device-Code.
   • secret - the per-device signing secret used to compute X-QClock-Signature.
   • approvalStatus - Approved when approveImmediately was true; otherwise the device is staged until you approve it in Step 3.
4. About the optional fields:
   • vendor defaults to "Generic"; set it to the actual device maker so the audit can group reports.
   • integrationMode defaults to "Push" (the device or middleware calls QBM). Use "Pull" or "FileInbox" only if the integration notes for your vendor say so.
   • approveImmediately: true skips Step 3 and makes the device usable right away. Useful for one-shot installs; leave it false when you want a manager to review before go-live.
   • rotateSecret: true against an existing deviceCode issues a new signing secret and invalidates the old one. Use it if a secret was leaked.

Step 3. Approve The Device

A registered device cannot save attendance until a manager approves it. Approval is a separate step so newly added devices do not silently create attendance during testing.

1. List the registered devices to confirm the new entry:

   GET /api/qclock/integrations/devices
   Authorization: Bearer <manager token>

2. Approve the new device by id:

   POST /api/qclock/integrations/devices/<deviceId>/approve
   Authorization: Bearer <manager token>

3. If you ever need to stop a device immediately, disable it. Past attendance is preserved; future events from that device are rejected:

   POST /api/qclock/integrations/devices/<deviceId>/disable
   Authorization: Bearer <manager token>

Step 4. Enroll Employees On The Device

1. Enroll each employee on the biometric device using the vendor's enrollment software (finger placement, face capture, or badge/PIN).
2. For every enrolled person, write down the device's external employee identifier and the matching QBM EmployeeID.
3. Configure the device or vendor middleware to send the external employee id with each attendance event. QClock uses it to find the QBM employee. Events without a known mapping are queued for manager review rather than saved as attendance.

Step 5. Send Attendance Events From The Device

Each check-in or check-out from the biometric device is one HTTP request to QBMWServices. The device (or the middleware that forwards device events) is responsible for building the request, signing it, and retrying on transient failures.

Endpoints

POST /api/qclock/integrations/device-events/punch

For high-volume devices, send several events at once instead of one-by-one:

POST /api/qclock/integrations/device-events/punch-batch

Required Headers

• X-QClock-Integration-Key - the same value set in QClock:ExternalIntegrations:ApiKey. Requests without it return 403 "external integration key is missing"; requests with the wrong value return 403 "external integration key is invalid". This header is mandatory on every punch.
• X-QClock-Device-Code - the device code from registration. Must equal the deviceCode in the body or the request is rejected.
• X-QClock-Event-Id - a unique id for this single event. Must equal the externalEventId in the body. A duplicate id is rejected so QBM never double-saves the same punch.
• X-QClock-Timestamp - the time the device built the request, as Unix seconds or an ISO timestamp.
• X-QClock-Signature - sha256=<lowercase-hex of HMAC-SHA256(signing-secret, timestamp + "." + raw-json-body)>. The bare lowercase hex (without the sha256= prefix) is also accepted. Signing is mandatory for any device that has a per-device secret (the normal registered-device case).

QBMWServices rejects requests whose timestamp is more than five minutes outside the server clock (configurable through SignatureToleranceMinutes), so the device and the server must keep close enough time.

The signed string is the concatenation timestamp + "." + raw-json-body. The body bytes used to compute the signature must be exactly the bytes sent on the wire (no pretty-printing, no extra whitespace after the device hashes it). Compute the signature last, then send the request.

Payload

{
  "deviceCode": "frontdoor-1",
  "externalEventId": "frontdoor-1-1716033600-001",
  "externalEmployeeId": "1042",
  "direction": "Auto",
  "verificationMethodName": "FingerprintTerminal",
  "sourceVendor": "ZKTeco",
  "sourceModel": "K40",
  "locationCode": "HQ-LOBBY"
}

• direction may be CheckIn, CheckOut, or Auto. With Auto, QBM chooses the legal direction from the employee's current open attendance.
• verificationMethodName describes how the device confirmed the employee: FingerprintTerminal, FaceTerminal, Badge, Pin, or PhotoEvidence.
• The same fields are accepted under the generic aliases used by some middleware vendors: deviceCode, externalEventId, externalEmployeeId, direction, eventType, verificationMethodName, sourceVendor, sourceModel, locationCode, plus a non-biometric rawPayload field for diagnostic vendor data.

Step 6. Confirm That The First Punches Are Saved

1. Send one test event from the device and ask the test employee to wait for the device's success message.
2. Open Clock Review in QClock with a QBM Manager login. Filter by the test employee and today's date.
3. The new row should show the verification method (FingerprintTerminal or the value the device sent) and the device's location code. If the row is missing, look in the QBMWServices pending events journal for events that did not match a QBM employee.

Optional: File Inbox Mode

Some older biometric systems can only drop attendance files in a shared folder. QClock supports a file inbox path for those devices. It is disabled by default. To enable it, set QClock:ExternalIntegrations:FileInbox:Enabled to true in QBMWServices and configure the inbox path according to the integration notes shipped with the QBM update.

Common Setup Problems

• "QClock external device integration is not enabled" (403): QClock:ExternalIntegrations:ApiKey is blank or the service was not restarted after the change.
• "QClock external integration key is missing/invalid" (403): the X-QClock-Integration-Key header was omitted or does not match the configured ApiKey.
• "X-QClock-Device-Code does not match the payload device code" (400): the header and body must carry the same deviceCode. The same rule applies to X-QClock-Event-Id and externalEventId.
• Device routes return 403 "device is not approved": the device was registered without approveImmediately: true and has not been approved (Step 3).
• Signature is rejected: the device clock is more than five minutes off, the timestamp/body used to compute the signature does not match the body actually sent, or the signature is not lowercase hex. The signed string is timestamp + "." + raw-json-body and the secret is the per-device signing secret returned at registration.
• Event is accepted but no attendance is saved: the external employee id is not yet mapped to a QBM EmployeeID. The event is held in the QBMWServices pending journal until a manager confirms the mapping.
• Duplicate event id error: the device retried after the first request actually succeeded. This is by design so retries do not double-punch. Use a fresh externalEventId for a new attempt.
• Event time outside the allowed window: MaxEventAgeHours (default 24) and MaxFutureMinutes (default 5) reject very old or future-dated events. Confirm the device clock and the chosen EventTime.

Fallbacks And Exceptions

A fallback is not a failure of the system. It is the approved way to keep attendance accurate when the normal method cannot be used.

Manager Review

Managers should review attendance records regularly, especially during the first weeks after enabling a new verification method.

• Check missing check-ins and missing check-outs.
• Review warnings from unapproved computers or unexpected locations.
• Review duplicate or repeated attempts from attendance devices.
• Review fallback punches and confirm that the employee followed company policy.
• Correct approved exceptions before payroll work starts.
• Keep notes short, factual, and related to attendance.

Privacy And Employee Communication

Fingerprint and face attendance should be introduced clearly. Employees should know what method is being used, why it is used, who can review attendance, and what fallback is available.

• Tell employees which attendance method applies to their location or role.
• Explain that the company controls whether fingerprint, face, photo, badge, PIN, or password confirmation is used.
• Give employees a fallback process before the first day of use.
• Limit attendance review access to authorized managers.
• Follow local laws, employment rules, and company policy before enabling biometric attendance.

Simple Staff Instructions

For Employees Using QClock

Open QClock, confirm your name, choose Check In when you start work, choose Check Out when you leave, complete the required confirmation, and check today's history before you close the screen.

For Employees Using A Device

Use the approved attendance device at your work location, wait for a success message, and tell your manager immediately if the device cannot record your attendance.

For Managers

Review attendance warnings, missing punches, fallback use, and device issues every day during rollout. Correct only records that match company policy and keep the correction note clear.

Related Guides

• QClock Employee Clock Guide - Daily check-in, check-out, approved computer use, and manager review.
• Employees Attendance Guide - Review attendance records and employee activity.
• Time Clock Time In And Out Guide - Record time clock entries in QBM.
• User Management Guide - Prepare users and permissions for employees and managers.