Questa pagina non è ancora tradotta, quindi stai leggendo la versione inglese.
Attendance machines
Send punches from any attendance machine or its software to ChatBeds with the Attendance API. Each punch becomes a staff member's clock-in or clock-out at the minute it happened.
A hotel keeps its own attendance machines: fingerprint, face, card or PIN, of any brand. ChatBeds turns each punch into a clock-in or clock-out on the hotel's time sheet, matched to the rota and counted for payroll.
This page is for the companies that make attendance software, and for the IT companies that connect a hotel's machines.
Ways to connect
| How | |
|---|---|
| The Attendance API (this page) | Your program sends punches to ChatBeds with the machine's key |
| File upload | The hotel uploads the machine's USB export on the Machines page (ZKTeco attlog, or any CSV or Excel file) |
| ZKTeco Push (ADMS) | ZKTeco and eSSL machines send punches to attendance.chatbeds.app themselves (below) |
| The Attendance Bridge | ChatBeds' program on a computer at the hotel reads older ZKTeco and eSSL machines on port 4370 (below) |
| Coming | Hikvision's event listener, and the brands' own software (BioTime, CrossChex Cloud, BioStar 2, HikCentral) |
The key
The hotel adds the machine in Staff → Machines → Add a machine, chooses Attendance API, and copies the key shown (it starts with cbat_ and is shown once). One key per machine. A new key stops the old one at once.
Sending punches
POST https://api.chatbeds.app/public/v1/attendance/punches
Authorization: Bearer cbat_...
Content-Type: application/json
{
"punches": [
{"employee": "1042", "time": "2026-11-03T07:58:12", "status": "in", "verified_by": "fingerprint"},
{"employee": "1042", "time": "2026-11-03T17:01:40", "status": "out", "verified_by": "face"}
]
}| Field | ||
|---|---|---|
employee | required | The person's ID on the machine (their attendance ID in ChatBeds, or their employee number), up to 32 letters or numbers |
time | required | When it happened. With a time zone, or without one for the hotel's own time |
status | optional | in, out, break_out, break_in, ot_in, ot_out. Used when the hotel reads punches by the machine's keys; otherwise the first punch starts the shift and the next ends it |
verified_by | optional | fingerprint, face, card, pin, palm, other. Shown on the time sheet |
Up to 500 punches in one call, in any order: ChatBeds sorts them. Send fingerprint or face data never: ChatBeds doesn't take it.
The answer
{
"received": 2, "recorded": 2, "duplicates": 0,
"outcomes": {"IN": 1, "OUT": 1},
"punches": [
{"employee": "1042", "at": "2026-11-03T02:58:12+00:00", "local": "2026-11-03 07:58", "outcome": "IN", "note": null, "...": "..."}
]
}Each punch is kept once: the same employee and time from the same machine again is a duplicate, so you can safely send everything again after a failure.
| Outcome | Meaning |
|---|---|
IN, OUT | The shift started or ended at the punch's time |
BREAK_OUT, BREAK_IN | A break started or ended |
PAST | An older shift, put in its place between shifts already recorded |
DOUBLE | A second press within 2 minutes, or an out too soon after the in |
INSIDE | Inside a shift already recorded (for example by WhatsApp) |
UNKNOWN_ID | Nobody on the staff list has this ID. Kept; the hotel sets the person's attendance ID |
OFF | The machine, or clocking in by machine for this person, is switched off |
HELD | Kept for the hotel's manager, with the reason in note: an out with no in, a time in the future, refused by the hotel's clock-in rules |
Errors
| Code | When |
|---|---|
401 | Unknown or removed key, or a key replaced by a new one |
402 | The hotel's plan doesn't include attendance (Pro) |
422 | A punch is missing employee or time, or a field has an unknown value |
429 | More than 600 calls a minute for one machine. Wait for Retry-After |
Events
Each punch is also an attendance.punch event for the hotel's agents and their webhooks, with the machine, the ID, the time, the outcome and the person.
ZKTeco machines that send punches themselves
ZKTeco's Push protocol (ADMS, "iClock"), spoken by ZKTeco and eSSL machines with the cloud server setting. The hotel adds the machine with its serial number; the machine is set to attendance.chatbeds.app (port 443 with HTTPS, or 80 without on older firmware).
| The machine | ChatBeds |
|---|---|
GET /iclock/cdata?SN=…&options=all | Its settings: send punches as they happen, from the last stamp received; the hotel's time zone |
POST /iclock/cdata?SN=…&table=ATTLOG&Stamp=… | Punches, one a line: PIN<TAB>2026-11-03 07:58:12<TAB>status<TAB>verify…. Answered OK: <n> |
POST /iclock/cdata?SN=…&table=OPERLOG | Users and enrolments. ChatBeds keeps who is enrolled with what; templates (FP, FACE, BIOPHOTO…) are thrown away |
POST /iclock/cdata?SN=…&table=ATTPHOTO | Not kept |
GET /iclock/getrequest?SN=…&INFO=… | Its heartbeat: OK, or waiting commands C:<n>:<line> |
POST /iclock/devicecmd?SN=… | ID=<n>&Return=<code>&CMD=…: what a command did |
Only serials a hotel added are answered (404 otherwise), and a machine is paired by its first contact within 24 hours of being added (403 after, until the hotel presses Pair again). Punches from a different internet address than the one it was paired from are held for the hotel unless it trusts the new one.
Users. ChatBeds keeps the machine's user list in step with the hotel's staff, with commands on the same queue:
DATA UPDATE USERINFO PIN=<id>\tName=<name>\tPri=0 when someone is added, gets a new ID or a new name (normal users
only, name and ID only), DATA DELETE USERINFO PIN=<id> when they leave, and DATA QUERY USERINFO once a day, whose
answer comes back as OPERLOG. Users ChatBeds didn't add are never deleted.
The protocol's command lines are checked against each tested firmware; a machine's firmware is shown on its card.
The Attendance Bridge
For older ZKTeco and eSSL machines that talk only on the local network (port 4370, TCP or UDP). The Bridge is tools/attendance-bridge from ChatBeds (also downloadable from Staff → Machines): Python 3.9 or later, nothing else to install, outgoing HTTPS only. It never reads fingerprint templates or face data, and never clears a machine's punches.
python3 bridge.py --check 192.168.1.201 --key 1234 # test a machine from this computer
python3 bridge.py --pair ABCD-EFGH # once: the code from the Machines page (24 hours, works once)
python3 bridge.py # then every minuteIt calls ChatBeds with Authorization: Bridge cabr_... (the token it got when paired):
| Call | What |
|---|---|
POST /api/v1/attendance-bridge/pair | {"code", "computer", "version"} → {"token", "hotel", "every_seconds"}. Pairing another computer stops the one before |
GET /api/v1/attendance-bridge/config | The hotel's machines on the Bridge (address, port, comm_key), since (send punches from this time, the machine's clock), the commands waiting for each, and utc_offset_minutes |
POST /api/v1/attendance-bridge/machines/{id}/punches | {"punches": [{"pin", "at": "2026-11-03 07:58:12", "state", "verify"}]}, at most 2,000 a call; state and verify are the machine's own codes (as in ATTLOG). Kept once |
POST /api/v1/attendance-bridge/machines/{id}/report | {"ok", "error", "serial", "firmware", "platform", "counts", "clock", "clock_age", "commands": [{"number", "ok", "error"}], "users": [{"pin", "name", "admin", "card"}]} |
The commands are the same lines as for Push machines: DATA UPDATE USERINFO PIN=..\tName=..\tPri=0 (the Bridge keeps a card, password or admin rights set at the machine), DATA DELETE USERINFO PIN=.., DATA QUERY USERINFO (answered with users: never passwords), DATA QUERY ATTLOG StartTime=..\tEndTime=.. (those punches are sent again) and SET TIME (the hotel's time, from utc_offset_minutes). A machine that can't be reached is reported with ok: false and the reason; its commands wait for the next round.
Stai creando qualcosa?
Key cards
Connect a hotel's key-card system to ChatBeds. ChatBeds asks it for a guest's key at check-in and cancels the key at check-out, through an https address or the bridge on the desk computer.
Negotiation for AI assistants
An open protocol for travellers' AI assistants to find independent hotels, ask them for private offers on a traveller's dates, counter, and book, with payment by the traveller. REST and MCP, signed quotes, no key needed.