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; зачекайте кілька хвилин.