Shift Scheduling Engine
FOR DEVELOPERS & INTEGRATORSA deterministic, compliance-aware shift scheduling engine over HTTP. Generate continuous-operation crew rosters, overlay national public holidays, and get every roster checked against an itemised labour-law rulebook — with the exact statute reference on every finding.
API reference → · one engine, two ways to buy: this API, or the OPEREX Shift Scheduler UI module.
Why build on it
The same input plus the same engine and rule versions always returns the same roster — reproducibly, for a legal or payroll audit. No hidden randomness, no drift.
Every generated roster is checked against a national, itemised labour-law rulebook and reported with the exact statute reference. It signals and justifies — it does not guarantee.
Shift patterns, rotation phases, the holiday set and the labour-law thresholds are versioned data, separate from the engine. A changed statute is a data edit, never a code change.
What the engine does
Generate any cyclic shift rotation — 8h three-shift, 12h two-shift, 2-2-3, custom — for any date range, from a fortnight to a full year. Patterns are versioned data, not code.
Each crew runs its own phase of the rotation; per-person overrides (dayworker, standby, LEAN) resolve on top. Solver-free, deterministic — reproduces the reference plant’s real crews exactly.
Morning/afternoon/night 8h and day/night 12h shifts coexist in one site, alongside dayworkers and standby — a mixed shift model, not a single fixed grid.
National public holidays (fixed + Easter-derived) applied automatically: shift crews work through, dayworkers get paid holiday rest (Üp).
Per-day headcount by shift, with the site’s operational safety-minimum surfaced as understaffing flags.
A per-person month summary from the same roster: engine-authoritative worked hours, night count, worked shifts, the day-off codes (vacation Sz, flex CS, holiday-rest Üp) and the working-time-frame balance (worked − expected, Mt. 93–94. §).
Daily rest, daily/weekly maximum hours, night-work limit and weekly rest — each finding cites its statute section. Signals and justifies; does not guarantee.
One call, a full month
A single request builds the month and (optionally) evaluates compliance:
curl https://api.operex.eu/v1/schedule:build \
-H "Authorization: Bearer sk_…" \
-H "Content-Type: application/json" \
-d '{
"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
}'Response (elided):
{
"engine_version": "0.6.0",
"schedule": {
"site_id": "plant-01", "year": 2025, "month": 12,
"days": [ "2025-12-01", "2025-12-02", … ],
"rows": {
"1000001": [ "É","É","-","-","-","-","R","R", … ],
"9000001": [ "N","N","N","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
}
}Symbols: R/É = 12h day/night, r/d/é = 8h morning/afternoon/night, N = dayworker, Üp = paid holiday rest, - = off. Full schema in the reference.
Determinism & versioning
The rotation is anchored on a fixed base date, so the position in the cycle is a pure function of the date. Every response echoes engine_version and rulebook_version; pin them and the same request reproduces the same roster byte-for-byte — the property that makes a schedule auditable and a dispute settleable.
Signals and justifies — does not guarantee
The compliance layer is the differentiator. Each generated roster is measured against a national, itemised labour-law rulebook (daily rest, daily/weekly maximum hours, night-work limit, weekly rest), and every potential breach is reported with its statute_section, the measured value and the threshold. It positions honestly: it flags and explains, it does not certify. Findings from a rule still awaiting legal confirmation carry a needs_review flag.
Status & packaging
Live. The engine runs in production and is validated against real rosters. The labour-law rulebook is maintained under ongoing legal review — breaches from a rule still awaiting confirmation are flagged needs_review — and the hosted API is offered to early-access design partners rather than as a public self-serve service.
Two-lane packaging. Buy the API on its own (monthly, integrate over REST, no UI), or use the OPEREX Shift Scheduler module whose UI runs on the same engine. Early-access design partners welcome.
FAQ
Is the roster deterministic?
Yes. Given the same site configuration and the same engine and rule versions, the engine always produces the same schedule. The response includes the versions so you can pin and reproduce a result later.
Does it guarantee legal compliance?
No — and it says so. The engine signals potential labour-law issues and justifies each one with a statute reference. The rulebook is versioned data that must be confirmed against the current statute; findings from a draft rule are flagged as needing review.
Which optimizer does it use?
None in v1. The reference workflow is deterministic pattern rotation, not combinatorial optimization, so the engine expands the rotation directly. A constraint solver would be introduced only if a future requirement needs true optimization.
Can I build more than one month in a call?
Yes. POST /v1/schedule:build-range takes a start and end date and builds any inclusive span — a fortnight, a quarter, a full year — in one call, with the same rotation, per-cell overrides and compliance as the monthly build (the compliance rolling windows span the whole range, and the statistics aggregate over the span). The monthly POST /v1/schedule:build stays for the common case.
How do I get the UI?
Two ways to consume one engine: buy the API on its own and integrate over REST, or use the OPEREX Shift Scheduler module, whose UI calls the same engine. Talk to us about early access.