The mistake you pay for with a fork
It's the typical evolution: the first customer has model A and your SaaS supports it fine. The second has model B — and suddenly your backend has if model == "B" scattered everywhere. By the third model, the feature that was "integrate time clocks" has become "maintain three adapters", and every release is a risk snake.
The root cause: the software coupled to the model when it should have coupled to the contract. Terminals are heterogeneous hardware — models, firmwares, peripherals — but your business logic only needs one contract: "something happened, with this person, with this method, at this time, on this terminal". Designing for that contract is what makes software model-agnostic.
Principle 1: the serial is the key, not the model
Everything you consume from a terminal — reports, events, users, credentials — should be addressed by its serial number, never by its model. The serial is stable, unique and doesn't change when the firmware is updated.
In API Connect, the serial addresses every endpoint: /report/{serial}, user management, credentials, groups. Your SaaS doesn't need to know (nor benefits from knowing) whether the terminal is a desktop device or a face-scanning one.
Principle 2: the terminal is a black box
Your SaaS shouldn't model the device's internals (templates, firmware, memory) but its contract surface: what events it emits and what management it accepts. When the hardware layer is maintained by an API like API Connect, that surface stays defined and stable — even if models and firmwares change underneath.
Coupling test: if tomorrow your customer swaps a terminal for a different model, does your SaaS need a release? If the answer is yes, there's coupling to the model. With the right abstraction, the answer is: register the new serial and you're done.
Principle 3: your data model is not the terminal's
The terminal has "people with PINs"; your SaaS has employees, residents or members with their own lifecycle. Keep that boundary: your people table maps to the terminal's via PIN/card, and the lifecycle (add, change, remove) is orchestrated by your software via API — not by a manual import on the device's menu.
Credential flows per serial (add with PIN and card, assign to access groups, remove) let you orchestrate without touching the hardware and without duplicating its internal model.
Principle 4: normalize the events
The same access can arrive via fingerprint, card, PIN or face. Your business logic — attendance, notifications, headcounts — should consume a normalized record:
- Person (PIN/card) and verification method.
- Exact date/time of the event.
- Originating terminal (serial) and direction (entry/exit, door).
- Result: granted or denied, with its cause.
With that contract, it doesn't matter which model produced the event: payroll calculates hours, the front desk gets notified and the audit logs — all with the same code flow.
What layers a good hardware API should abstract
| Layer | If the API abstracts it | If your SaaS handles it |
|---|---|---|
| Device protocol | Uniform REST/JSON | Adapter per model/firmware |
| Connectivity (customer's network) | Push mode: the device reaches the cloud | Static IP, ports, VPN per site |
| Model variety | Serial as the single key | if model branches |
| Real-time events | Normalized webhook/stream | Polling and your own queue engineering |
| Biometric templates | Managed by device/platform | Risk and compliance in your DB |
How to test the multi-model design
The practical check: mix models in testing. With API Connect you register terminals of different models in the same account (and simulate variety from the sandbox/trial), then verify that your SaaS — reports, notifications, reconciliation — works without changing a line. If any flow breaks, there's hidden coupling; better to catch it in testing than at the customer's site.
Frequently asked questions
Should my SaaS know the terminal model?
No: your software works with serials and events. Supporting a new model means registering the device, not writing code.
How do I normalize different verification methods?
With one record per event: person, method, date/time, terminal and result. Your logic consumes that contract, not the model that produced it.
What if the customer mixes old and new models?
The platform manages the variety: all terminals are consumed through the same API. Your fleet can mix generations without your code noticing.
Test your architecture with real and virtual devices
Register terminals of different models and verify your SaaS doesn't change. 14 days free, no credit card.