Eszköz és kiosz API

Párosítás, be- és kilépés, valamint beosztás-lekérdezés a kioszk-táblagép és a munkavállalói telefonalkalmazások mögött.

Ugyanaz a párosítás + bearer-token minta, mint minden más API esetén itt — egy eszközt egyszer párosítanak, majd ezt követően minden hívásnál a tokenjével hitelesíti magát.

Base URL and format

Every company has its own address: https://<company>.clockeu.eu/api/… (on a custom install: your own domain, plus the base path if any). Send form fields or a JSON body; every answer is JSON with "ok": true or "ok": false and an "error" code. Authenticate with Authorization: Bearer <device_token> (X-Device-Token: <device_token> also works).

Eszköz párosítása

Cserélje ki a párosítási kódot (amely az irányítópulton, az Eszközök oldalon jelenik meg) egy állandó tokenre. Ugyanazt a hívást végzi maga a kioszkalkalmazás is az első indításakor.

curl -X POST https://acme.clockeu.eu/api/pair.php \
  -H "Content-Type: application/json" \
  -d '{"code": "123456"}'
{
  "ok": true,
  "device_token": "a1b2c3...",
  "device_name": "Front door",
  "device_type": "tablet",
  "company_name": "Acme Retail",
  "location_id": 3,
  "location_name": "Main street store",
  "require_photo": false,
  "face_login_enabled": false,
  "locale": "en"
}

GET /api/schedule-today.php

Today's shifts at the device's location (in the location's own timezone) with clock-in/out and break times — what a kiosk shows on its main screen.

curl https://acme.clockeu.eu/api/schedule-today.php \
  -H "Authorization: Bearer <device_token>"
{
  "ok": true,
  "date": "2026-10-20",
  "entries": [
    {
      "id": 118,
      "employee_name": "Marco Rossi",
      "shift_name": "Morning",
      "start_time": "08:00",
      "end_time": "16:00",
      "clock_in": "2026-10-20T08:02:11+02:00",
      "clock_out": null,
      "break_start": null,
      "break_end": null
    }
  ],
  "require_photo": false,
  "face_login_enabled": false,
  "locale": "en"
}

POST /api/clock.php

Be-, kiléptet, vagy elindítja/befejezi egy munkavállaló szünetét, a PIN-je alapján azonosítva. Megköveteli, hogy ennek a munkavállalónak ma legyen beosztott műszakja ennek az eszköznek a telephelyén.

action is "in", "out" or "break" (the first tap starts the break, the next ends it). The PIN is the employee's kiosk PIN from the dashboard. After too many wrong PINs the device is locked out for a few minutes (HTTP 429).

curl -X POST https://acme.clockeu.eu/api/clock.php \
  -H "Authorization: Bearer <device_token>" \
  -d "pin_code=1234&action=in"
{
  "ok": true,
  "action": "in",
  "employee_name": "Marco Rossi",
  "shift_name": "Morning",
  "start_time": "08:00",
  "end_time": "16:00",
  "time": "2026-10-20T08:02:11+02:00"
}

POST /api/device-ping.php

A light heartbeat: marks the device as seen and tells it whether the dashboard asked for a test photo or a screenshot.

curl -X POST https://acme.clockeu.eu/api/device-ping.php \
  -H "Authorization: Bearer <device_token>"

{"ok": true, "test_photo_requested": false, "screenshot_requested": false}

Examples

The full flow — pair once, store the token, then clock people in and out. The same calls in curl, Python and JavaScript.

curl

# 1. once: exchange the pairing code for a token
TOKEN=$(curl -s -X POST https://acme.clockeu.eu/api/pair.php \
  -d "code=123456" | jq -r .device_token)

# 2. who is on shift today
curl -s https://acme.clockeu.eu/api/schedule-today.php \
  -H "Authorization: Bearer $TOKEN" | jq '.entries[] | {employee_name, start_time, clock_in}'

# 3. clock in, start / end a break, clock out
for action in in break break out; do
  curl -s -X POST https://acme.clockeu.eu/api/clock.php \
    -H "Authorization: Bearer $TOKEN" \
    -d "pin_code=1234&action=$action"; echo
done

Python

import requests

BASE = "https://acme.clockeu.eu"

# once: pair, then keep the token (a file, a secret store...)
r = requests.post(f"{BASE}/api/pair.php", json={"code": "123456"}, timeout=15)
r.raise_for_status()
token = r.json()["device_token"]
headers = {"Authorization": f"Bearer {token}"}

def clock(pin, action):
    r = requests.post(f"{BASE}/api/clock.php", headers=headers,
                      data={"pin_code": pin, "action": action}, timeout=15)
    data = r.json()
    if not data.get("ok"):
        raise RuntimeError(f"{r.status_code}: {data.get('error')}")
    return data

print(clock("1234", "in"))

JavaScript

const BASE = "https://acme.clockeu.eu";

async function pair(code) {
  const res = await fetch(`${BASE}/api/pair.php`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ code }),
  });
  const data = await res.json();
  if (!data.ok) throw new Error(data.error);
  return data.device_token;
}

async function clock(token, pin, action) {
  const res = await fetch(`${BASE}/api/clock.php`, {
    method: "POST",
    headers: { Authorization: `Bearer ${token}` },
    body: new URLSearchParams({ pin_code: pin, action }),
  });
  const data = await res.json();
  if (!data.ok) throw new Error(`${res.status} ${data.error}`);
  return data;
}

Errors

Failed calls answer with an HTTP status and {"ok": false, "error": "<code>"}.

  • 401 — invalid_device_token — missing, wrong or revoked token; pair the device again.
  • 404 — invalid_code (pairing), unknown_pin, not_scheduled_here_today — nobody with this PIN, or no shift for them at this location today.
  • 409 — already_clocked_in, not_clocked_in, already_clocked_out, break_in_progress, device_has_no_location.
  • 410 — code_expired — pairing codes are valid for a few minutes; create a new one on the Devices page.
  • 429 — too_many_attempts — wrong PINs; wait a few minutes.