API пристроїв і кіоска
Підключення, відмітка приходу/відходу та запит графіка для застосунку-кіоска на планшеті й телефонного застосунку співробітника.
Та сама схема «підключення + bearer-токен», що й у всіх інших API тут — пристрій підключається один раз, а потім автентифікується своїм токеном у кожному наступному запиті.
Базова адреса і формат
У кожної компанії своя адреса: https://<компанія>.clockeu.eu/api/… (на власному встановленні — ваш домен і, якщо є, базовий шлях). Передавайте поля форми або JSON; кожна відповідь — JSON з "ok": true або "ok": false і кодом "error". Автентифікація: Authorization: Bearer <device_token> (також працює X-Device-Token: <device_token>).
Підключення пристрою
Обміняйте код підключення (показаний на панелі, сторінка «Пристрої») на постійний токен. Той самий виклик, який сам застосунок-кіоск робить при першому запуску.
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
Зміни на сьогодні в локації пристрою (за часовим поясом локації) з відмітками приходу/виходу та перерви — це головний екран кіоска.
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
Відмічає прихід, відхід або початок/кінець перерви співробітника за його PIN-кодом. Вимагає, щоб у цього співробітника на сьогодні була запланована зміна в локації цього пристрою.
action — "in", "out" або "break" (перше натискання починає перерву, наступне завершує). PIN — PIN співробітника для кіоска з панелі. Після кількох неправильних PIN пристрій блокується на кілька хвилин (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
Легкий «пульс»: позначає пристрій як активний і повідомляє, чи просила панель тестове фото або знімок екрана.
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}
Приклади
Повний сценарій — підключити один раз, зберегти токен, далі відмічати прихід і вихід. Ті самі виклики в curl, Python та 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;
}
Помилки
Невдалі виклики повертають HTTP-статус і {"ok": false, "error": "<код>"}.
- 401 — invalid_device_token — токена немає, він неправильний або відкликаний; підключіть пристрій знову.
- 404 — invalid_code (підключення), unknown_pin, not_scheduled_here_today — немає співробітника з таким PIN або в нього сьогодні немає зміни в цій локації.
- 409 — already_clocked_in, not_clocked_in, already_clocked_out, break_in_progress, device_has_no_location.
- 410 — code_expired — код підключення діє кілька хвилин; створіть новий на сторінці «Пристрої».
- 429 — too_many_attempts — неправильні PIN; зачекайте кілька хвилин.