API-referencia

Base URL https://api.operex.eu · szerződés-verzió v1. A kulcsot így küldd: Authorization: Bearer <key>.

A mező-, enum- és jel-nevek a SZERZŐDÉS részei, minden nyelven angolul maradnak; csak a próza fordul. A sémák a szállított motort követik (apps/shift-engine).

⬇ OpenAPI spec (JSON)OpenAPI specifikáció ↓

Végpontok

Hitelesítés

Minden kérés egy API-kulcsot visz bearer-tokenként: Authorization: Bearer <key>. A kulcsok fiókonkéntiek és rotálhatók. A GET /health nem igényel kulcsot.

POST /v1/schedule:build

Egy telephely egy hónapját építi fel, és ha az evaluate igaz, lefuttatja a megfelelőség-kiértékelőt.

POST /v1/schedule:build
Authorization: Bearer sk_…
Content-Type: application/json

{
  "site": {
    "site_id": "plant-01",
    "shift_pattern_key": "12h-2-2-4",
    "anchor": "2022-08-09",
    "n_crews": 4,
    "dayworker_anchor": "2022-08-08",
    "min_headcount": { "safety_total": 8 },
    "employees": [
      { "staff_id": "1000001", "name": "…", "role": "Operator", "kind": "shift", "crew": 0 },
      { "staff_id": "9000001", "name": "…", "role": "Engineer", "kind": "dayworker" }
    ]
  },
  "year": 2025,
  "month": 12,
  "evaluate": true
}

Kérés — felső szint

Site

Employee

MinHeadcount

Válasz

{
  "engine_version": "0.6.2",
  "schedule": {
    "site_id": "plant-01", "year": 2025, "month": 12,
    "days": [ "2025-12-01", … ],
    "rows": { "1000001": [ "É","É","-","-", … ], "9000001": [ "N","N", …, "Üp","Üp" ] },
    "coverage": [ { "day": "2025-12-01", "morning": 1, "afternoon": 0, "night": 1, "dayworker": 1, "understaffed": [] }, … ],
    "statistics": { "1000001": { "worked_hours": 192, "night_count": 8, "shift_count": 16, "vacation_days": 0, "flex_days": 0, "holiday_rest_days": 0, "expected_hours": 176, "balance": 16 }, … }
  },
  "compliance": {
    "rulebook_version": "2026-09-03-draft",
    "violations": [],
    "notes": [ "This report signals and justifies; it does not guarantee compliance. …" ],
    "any_needs_review": false
  }
}

Felső szint: engine_version, schedule, és compliance (null, ha az evaluate false).

schedule

coverage[]

statistics (PersonStats)

POST /v1/schedule:build-range

Ugyanaz, mint a POST /v1/schedule:build, de egy hónap helyett tetszőleges, inkluzív dátumtartományra — egy hívás egy két hétre, egy negyedévre vagy egy egész évre. A rotáció, az ünnepnapok, a rule_overrides és a cellánkénti assignments azonosan viselkedik; a megfelelőség gördülő ablakai a TELJES tartományon futnak, a statistics pedig a tartományra összesít. A schedule egy RangeSchedule: ugyanaz az alak, mint a schedule, de year/month helyett start és end horgonyozza.

Kérés — felső szint

Műszakjelek

A rows minden cellája egy jel:

Dolgozó-típusok

Megfelelőségi jelentés

Ha az evaluate igaz, a compliance tartalmazza a jelzéseket. Jelez és indokol; nem garantál megfelelőséget. Minden sértés citálja a paragrafusát; a piszkozat-szabály jelzései needs_review: true értékkel jönnek. Ellenőrzött szabályok: napi pihenő, napi és heti max óra, éjszakai korlát, heti pihenőnap.

violation

GET /v1/patterns

Az elérhető műszak-mintákat listázza: key, name, hours, cycle_length. Egy key-t shift_pattern_key-ként vagy dayworker_pattern_key-ként használj.

GET /v1/holidays?year=

Egy év alap ünnepnapjait adja vissza (fix dátumok + húsvéthoz kötött mozgó ünnepek). Ez a szerkesztő alapadata: írd felül (átnevezés, hozzáadás, törlés), és a tényleges halmazt a build kérés holidays mezőjében küldd vissza. A motor csak az alaphalmazt számolja; szerkesztést nem tárol.

GET /v1/rules

Az alap megfelelőségi szabályokat adja vissza a szerkeszthető küszöbökkel. Ez a jogi-megfelelőségi szerkesztő alapadata: állítsd a számszerű küszöböket (min. pihenőóra, max. óra…) és a be-ki kapcsolót, majd a különbségeket a build kérés rule_overrides mezőjében küldd vissza. Hogy MELY szabályok léteznek és a paragrafus-hivatkozásaik: motor-tulajdon, nem szerkeszthető.

GET /v1/version

A motor- és szabály-verziókat adja vissza. Rögzítsd őket egy beosztás reprodukálásához.

{
  "engine_version": "0.6.2",
  "pattern_library_version": "2026-08-28",
  "rulebook_version": "2026-09-03-draft",
  "shift_times_version": "2026-08-28"
}

Determinizmus, időzónák és verziózás

Ugyanaz a kérés + ugyanaz az engine_version és rulebook_version mindig ugyanazt a beosztást adja. A rotáció a dátum tiszta függvénye a telephely anchor-jához képest; nincs rejtett állapot, nincs véletlen. A munkaórák időzóna-tudatosak (a telephely IANA-zónája, alapból Europe/Budapest): egy óraátállításon átnyúló éjszakai műszak a valós 11 órának (tavasz) vagy 13 órának (ősz) mérődik, és az őszi 13 órás éjszaka megszólaltatja a napi-óra szabályt. A szabály-adat (minták, óraidők, ünnepnapok, munkajogi szabálykönyv) verziózott és kérésenként felülírható, így egy beosztás később reprodukálható és auditálható.

Hibák

OpenAPI specifikáció

A teljes gépi szerződés a /engine/shift-scheduling/openapi.json-on (OpenAPI 3.1). A hosztolt motor a /openapi.json-on is kiszolgálja, interaktív dokumentációval a /docs-on.

/engine/shift-scheduling/openapi.json ↗