ChatBedsDesenvolvedores
Attendance machines

Esta página ainda não foi traduzida, então você está lendo a versão em inglês.

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 uploadThe 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 BridgeChatBeds' program on a computer at the hotel reads older ZKTeco and eSSL machines on port 4370 (below)
ComingHikvision'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

Punches from one machine
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
employeerequiredThe person's ID on the machine (their attendance ID in ChatBeds, or their employee number), up to 32 letters or numbers
timerequiredWhen it happened. With a time zone, or without one for the hotel's own time
statusoptionalin, 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_byoptionalfingerprint, 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

What was done
{
  "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.

OutcomeMeaning
IN, OUTThe shift started or ended at the punch's time
BREAK_OUT, BREAK_INA break started or ended
PASTAn older shift, put in its place between shifts already recorded
DOUBLEA second press within 2 minutes, or an out too soon after the in
INSIDEInside a shift already recorded (for example by WhatsApp)
UNKNOWN_IDNobody on the staff list has this ID. Kept; the hotel sets the person's attendance ID
OFFThe machine, or clocking in by machine for this person, is switched off
HELDKept 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

CodeWhen
401Unknown or removed key, or a key replaced by a new one
402The hotel's plan doesn't include attendance (Pro)
422A punch is missing employee or time, or a field has an unknown value
429More 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 machineChatBeds
GET /iclock/cdata?SN=…&options=allIts 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=OPERLOGUsers and enrolments. ChatBeds keeps who is enrolled with what; templates (FP, FACE, BIOPHOTO…) are thrown away
POST /iclock/cdata?SN=…&table=ATTPHOTONot 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 minute

It calls ChatBeds with Authorization: Bridge cabr_... (the token it got when paired):

CallWhat
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/configThe 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.

Criando algo?

Nesta página