munkanAPI.hu — dokumentáció

REST API magyar munkanap és munkaszüneti nap lekérdezéshez. A válaszok mindig JSON formátumban érkeznek (kivéve az iCal feed-et). Minden időpont magyar polgári naptár szerint értelmezendő, időzóna: Europe/Budapest.

Alap URL: https://munkanapi.hu/api/v1

Authentikáció

Minden végpont API kulcsot kér. A kulcsot kétféleképp küldheted:

• Header (ajánlott): Authorization: Bearer <kulcs>
• Query paraméter: ?key=<kulcs>

Új kulcsot a dashboardon tudsz generálni.

Dátum formátum

Rugalmas bemenet — a következőket mind elfogadja, belül mindegyik YYYY-MM-DD-re normalizálódik:

Végpontok

curl -H "Authorization: Bearer KEY" \
  https://munkanapi.hu/api/v1/day/2026-04-15

{
  "date":      "2026-04-15",
  "weekday":   "szerda",
  "type":      "workday",
  "isWorkday": true,
  "isHoliday": false,
  "predicted": false,
  "name":      null
}

curl -H "Authorization: Bearer KEY" https://munkanapi.hu/api/v1/day/2026
{
  "scope":    "year",
  "year":     2026,
  "from":     "2026-01-01",
  "to":       "2026-12-31",
  "count":    13,
  "holidays": [
    { "date":"2026-01-01", "weekday":"csütörtök", "name":"Újév" },
    { "date":"2026-03-15", "weekday":"vasárnap",  "name":"Nemzeti ünnep" },
    ...
  ],
  "warnings": [ "..." ]
}

curl -H "Authorization: Bearer KEY" \
  "https://munkanapi.hu/api/v1/range?from=2026-03-13&to=2026-03-17"

{
  "from": "2026-03-13", "to": "2026-03-17",
  "count": 5,
  "hasHoliday":   true,
  "holidayCount": 1,
  "workdayCount": 2,
  "days": [ /* minden nap részletesen */ ]
}

{
  "from":"2026-04-01", "to":"2026-04-30",
  "totalDays": 30,
  "workdays":  20,
  "holidays":  3,
  "restDays":  7
}

GET /api/v1/next-workday/2026-04-02
→ { "date": "2026-04-07", ... }   # nagypéntek + húsvét miatt

curl -H "Authorization: Bearer KEY" \
  -H "Content-Type: application/json" \
  -d '["2026-04-15","08-20","12-25"]' \
  https://munkanapi.hu/api/v1/days

https://munkanapi.hu/api/v1/calendar.ics?key=YOUR_KEY

Rate limit

Alapértelmezetten 60 kérés / perc és 10 000 kérés / nap API kulcsonként.

Minden válasz tartalmazza:

X-RateLimit-Limit-Minute:     60
X-RateLimit-Remaining-Minute: 58
X-RateLimit-Reset-Minute:     1776193980
X-RateLimit-Limit-Day:        10000
X-RateLimit-Remaining-Day:    9994
X-RateLimit-Reset-Day:        1776297600

Túllépéskor 429 Too Many Requests + Retry-After másodpercben.

Cache / ETag

Minden GET válasz ETag-et ad vissza. Ha változatlan, küldd vissza If-None-Match fejléccel:

GET /api/v1/day/2026-04-15
If-None-Match: "465362565f8acc88ddbe0fbdc4a89612"

→ 304 Not Modified

HEAD method ugyanazokkal a fejlécekkel válaszol, body nélkül — olcsó meta-lekérdezés.

Figyelmeztetések (warnings)

Ha az adott évben még vannak valószínűsített (nem véglegesített) áthelyezett munkanapok / pihenőnapok, a válaszhoz egy figyelmeztető üzenet is jár. Két megjelenési formája van:

• Egydátumos válaszok (/day/*, /next-workday/*): a warning mező a válaszban (üres / hiányzik, ha az év véglegesített).
• Tartomány- és bulk válaszok (/range, /workdays, /days): a warnings mező egy stringtömb, minden érintett évhez egy bejegyzés.

Lehetséges üzenetek:

• Aktuális év: „A {year}. évi áthelyezett napok még nem véglegesítettek (admin megerősítésre várunk)."
• Jövőbeli év: „A {year}. évi áthelyezett napok még nem véglegesítettek (hivatalos kormányrendeletre várunk)."
• Múltbeli év: „A {year}. év áthelyezett napjai nincsenek véglegesítve."

Ha a warning(s) üres / hiányzik, az év munkarendje végleges (vagy az adott évben nincs is áthelyezés).

Tipp: ha banki / bérügyi rendszerbe építed be, érdemes ezt a mezőt vizsgálni és a felhasználót értesíteni, ha az adat még nem hivatalos.

Hibakódok

Minden hiba JSON: {"error":"leírás"}.