Munkaszüneti napok API

Egyszerű munkaszüneti napok lekérdezése bármelyik évre, kiegészítve a plusz munkanapokkal.

dokumentáció

Leírás

Az api célja, hogy fejlesztőknek, ügyintézőknek a munkanapokat ne kelljen egyesével felvinni a projektjeikbe, hanem egy egyszerű lekérdezéssel egy adott évre az összes napot megkapják automatikusan, számítógépeknek érthető módon és máris foglalkozhatnak izgalmasabb feladatokkal.

Kezdés

Először regisztrálni kell az oldalra ahol az API kulcsot megkapja.

FIGYELEM! Az API kulcsra nagyon kell vigyázni, mivel ha más is használja, könnyen átlépheti a lekérdezési határt!

GET

Az API kulcs megszerzése után a https://szunetnapok.hu/api/{kulcs}/{év}/{(típus)}/{(paraméterek)} oldalon már le is kérheti a kívánt évet.

Itt egyértelmű, hogy ki kell cserélni a {} közötti szövegeket a megfelelő értékekre, különben hibát kap vissza. A {kulcs} az API kulcs amit az előbb megkapott. Az {év} helyére az adott évet kell megadni aminek a munkaszüneti napjaira kíváncsi. A {típus} nem kötelezően kitöltendő, json vagy xml-t fogad el, nem dob hibát ha hibásan van kitöltve. A {paraméterek} kitöltése nem kötelező, működése ugyan az mint a POST-ban.

Példa: Az API kulcs, amit a rendszertől kapott: A1B2C3D4E5F6G7H8I9 és a 2024-es év munkaszüneti napjait szeretné megismerni akkor a következő módon kell megformázni az URL-t: https://szunetnapok.hu/api/A1B2C3D4E5F6G7H8I9/2024/json/tn

POST

Abban az esetben ha POST-al szeretne kommunikálni a rendszerrel, a következő paramétereket kell megadni:

api_key: a regisztrálás után megszerzett api kulcs
year: a kívánt év amit le szeretne kérdezni
(type): nem szükséges kitölteni, de abban az esetben ha xml formátumban szeretné visszakapni az információkat, annyit kell ide beírni, hogy "xml"
(param): nem szükséges kitölteni, de abban az esetben ha további paraméterekkel szeretne lekérdezni (példa jQuery-ben). Nem kell sorrendet megadni.
(param (t)): a dátumokat UNIX timestamp formátumban adja vissza
(param (n)): a saját dátumokat nem listázza
(param (s)): a világnapok és nemzetközi akciónapok listáját is visszakapjuk
(param (d)): a névnapokat listázza napokra indexelve

Példa:

Másolás vágólapra


        $.post("https://szunetnapok.hu/api/",{"year":2024, "api_key": "A1B2C3D4E5F6G7H8I9", "type":"json", "param":"nt"}, function(cb){
            console.debug(cb);
        }, "json");


        $ch = curl_init();
        

        curl_setopt($ch, CURLOPT_URL, "https://szunetnapok.hu/api/");
        curl_setopt($ch, CURLOPT_POST, 1);
        curl_setopt($ch, CURLOPT_POSTFIELDS, "year=2024&api_key=A1B2C3D4E5F6G7H8I9");
        

        // Inkább így ajánlom:
        // curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query(array('year' => '2024', 'api_key' => 'A1B2C3D4E5F6G7H8I9')));
        

        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        

        $server_output = curl_exec($ch); 
        

        curl_close ($ch);


        https://github.com/huszerldani/laravel-szunetnapok-api


        curl -X POST --http2 -d '{"year":"2024","api_key":"A1B2C3D4E5F6G7H8I9","param":"nt"}' https://szunetnapok.hu/api/
        # A --http2 paraméter nem feltétlenül szükséges
        # A -d paraméterben nem lehet szünet (alulvonásnak fogja értelmezni)



        import io.ktor.client.*
        import io.ktor.client.call.*
        import io.ktor.client.engine.cio.*
        

        val client = HttpClient(CIO) {
            expectSuccess = false
            io.ktor.client.features.observer.ResponseObserver { response ->
            println("HTTP status: ${response.status.value}")
            }
            install(JsonFeature) {
            serializer = KotlinxSerializer(kotlinx.serialization.json.Json {
                prettyPrint = true
                isLenient = true
            })
            }
        }
        val response: io.ktor.client.statement.HttpResponse =
        client.get("https://szunetnapok.hu/api/A1B2C3D4E5F6G7H8I9/2024") {
        
        }

        val stringBody: String = response.receive()

Komplex lekérdezések

Lehetőség van egyedileg meghatározott lekérdezéseket létrehozni amik jobban szigorítják az intervallumot.

Mind a POST, mind a GET {year} változójába lehet intervallumot írni, aminek a formátuma a következő: ééééhh(nn)-ééééhh(nn)

Példa: Csak 2024 január 05 és május 17 közötti időpontokat szeretnénk lekérni: https://szunetnapok.hu/api/A1B2C3D4E5F6G7H8I9/20240105-20240517

A két év nem különbözhet, különben hibát fog dobni.

Zárójelben van a nap, mivel az sem kötelező. Ha ezek nincsenek megadva, a hónap első napját és az intervallum jobb oldalának a hónap utolsó napját fogja automatikusan behelyettesíteni a program.

Példa: Csak 2024 január és május közötti időpontokat szeretnénk lekérni: https://szunetnapok.hu/api/A1B2C3D4E5F6G7H8I9/202401-202405

A két dátum formátumának azonosnak kell lenni, pl. ha az egyikben csak év-hónap és a másikban év-hónap-nap van, a program hibát fog dobni.

Továbbá, lehetőség van csak egy adott év-hónapra lekérdezni, aminek a formátuma: ééééhh.

Példa: Csak 2024 májusát szeretnénk lekérni: https://szunetnapok.hu/api/A1B2C3D4E5F6G7H8I9/202405

Válasz

Két formátum közül kaphat választ a lekérdezésére: JSON és XML.

Ha sikertelen a lekérdezésünk, az api minden esetben egy UTF-8 kódolású, JSON formátumú szöveget ad vissza válaszként. Ha nem ez történik, kérjük ellenőrízze le a beírt címet, illetve a hálózati beállítások is, mivel ezek - esetekben - is gondot okozhatnak.

JSON
XML

Sikeres lekérdezéskor az api a következő JSON szöveget adja válaszként:
{ "response": "OK", "year": 2024, "days": [{ "date": "2024-01-01", "name": "Új Év napja", "type": 1, "weekday": 5 }, { "date": "2024-01-01", "name": "Áthelyezett munkanap", "type": 2, "weekday": 6 }]}

Magyarázat

Sikeres válasz esetén a korábban megkapott JSON szöveget fel kell dolgoznia valamilyen módszerrel. A következő táblázat a JSON szövegben található objektumokat igyekszik elmagyarázni.

Kulcs	Típus	Érték
response	string	Ellenőrző szöveg, hogy sikeres-e a lekérdezés, amennyiben ez nem "OK", hiba történt a lekérdezésben (a többi változó nem jelenik meg ilyenkor).
comment	(string)	Kiegészítő szöveg, nem minden esetben jelenik meg.
year	integer	Ellenőrző dátum, hogy valóban a megfelelő évet kérdezte-e le.
days	array	Ez tartalmazza a napokat amik az adott évre érintettek.
date	string	ISO 8601 (amennyiben nincs máshogy paraméterezve) formátumú dátum szöveg, ez az adott nap rekordja.
name	string	Leírás, hogy milyen nap ez.
type	integer	Ez az érték mutatja, hogy milyen fajta napról van szó. Ha az értéke: 1, ez egy munkaszüneti nap 2, ez egy munkanap
weekday	integer	Ez a szám mutatja, hogy a hét hanyadik napjáról van szó ahol az 1 a hétfő és 7 a vasárnap.
user_days	(array)	Amennyiben felvitt saját dátumokat, itt fogja listázni, felépítése ugyan az, mint a "days". Az (n) paraméter hozzáadásával ki lehet kapcsolni.
special_days	(array)	Világnapok és nemzetközi akciónapok listája (nem teljes). Abban különbözik a "days" tömbtől, hogy nincs benne type, helyette description van, ami a nap kiszámolási metódusát adja meg. Az (s) paraméter hozzáadásával lehet lekérdezni.
name_days	(array)	Magyar névnapok listája (nem teljes). A tömb felépítése a következő: az indexben a nap szerepel, ez alatt található a nevek felsorolása. Az (s) paraméter hozzáadásával lehet lekérdezni, a (t) paraméter hatással van erre.

XML lekérdezéshez az URL-t ki kell egészíteni a következő módon: https://szunetnapok.hu/api/A1B2C3D4E5F6G7H8I9/2024/xml

Magyarázat

Sikeres lekérdezés esetén az api egy XML dokumentumot ad vissza aminek a felépítése a következő:

Tag	Típus	Érték
response	string	Ellenőrző szöveg, hogy sikeres-e a lekérdezés, amennyiben ez nem "OK", hiba történt a lekérdezésben (a többi változó nem jelenik meg ilyenkor).
comment	(string)	Kiegészítő szöveg, nem minden esetben jelenik meg.
year	integer	Ellenőrző dátum, hogy valóban a megfelelő évet kérdezte-e le.
days	element	Ez tartalmazza a napokat amik az adott évre érintettek.
date	string	ISO 8601 (amennyiben nincs máshogy paraméterezve) formátumú dátum szöveg, ez az adott nap rekordja.
name	string	Leírás, hogy milyen nap ez.
type	integer	Ez az érték mutatja, hogy milyen fajta napról van szó. Ha az értéke: 1, ez egy munkaszüneti nap 2, ez egy munkanap
weekday	integer	Ez a szám mutatja, hogy a hét hanyadik napjáról van szó ahol az 1 a hétfő és 7 a vasárnap.

A sikertelen lekérdezések abból fakadnak főként, hogy az API kulcs rosszul van kitöltve. Ilyenkor a program a következő hibaüzenetet adja vissza:
{ "response": "Error", "message": "Nincs API kulcs megadva" }

FIGYELEM! A túl sok sikertelen lekérdezést a program támadásként értelmezheti, így ideiglenesen akár a szolgáltatást is megtagadhatja. Kérjük figyeljen arra, hogy helyesen írja be a kért adatokat!

Changelog

Verziózás magyarázata: vX.Y.Z

X: Főverzió. Csakis nagy változtatásnál növekszik, pl. API működésbeli változás

Y: Alverzió. Kisebb, de működést befolyásoló változásnál növekszik

Z: Patch. Kisebb, működést nem befolyásoló változásnál vagy biztonsági frissítésnél növekszik

v1.4.3 - 2024-10-24

Spam felhasználók törlése

v1.4.2 - 2024-04-29

Magyar névnapok listájának lekérdezési lehetőség hozzáadva (nem teljes lista)

v1.4.1 - 2024-04-26

Világnapok és nemzetközi akciónapok listájának lekérdezési lehetőség hozzáadva (nem teljes lista)

v1.4.0 - 2024-04-23

Saját napok rögzítésének lehetősége

v1.3.4 - 2024-03-06

Fejléc helyesen adja vissza a Content-Type-ot, json: application/json, xml: application/xml

v1.3.3 - 2022-06-07

Paraméterezési lehetőség hozzáadása

v1.3.2 - 2021-07-19

Példák kiegészítése több nyelvre
Példák vágólapra másolási lehetősége

v1.3.1 - 2021-06-28

Changelog és Roadmap megjelenítése a főoldalon
Statisztikák megjelenítése a főoldalon

v1.3 - 2021-06-26

Komplex lekérdezések hozzáadva
Statisztikák megjelenítése a főoldalon

v1.2 - 2021-06-23

POST-al is lehetőség van lekérdezni

v1.1 - 2021-06-22

XML válaszok a lekérdezésekre
Facebook oldal létrehozva
Ikonok frissítve

v1.0.1 - 2021-06-11

Kapcsolat felvétel hozzáadva

v1.0 - 2021-06-01

Elindultunk!
Paypal fizetési lehetőség

Roadmap

Ez alatt soroljuk fel a tervezett fejlesztéseket, hogy felhasználóink tisztában legyenek a terveinkkel és betekintést nyerjenek működésünkbe.

Ezek nem ígéretek, illetve idővel változhatnak de törekszünk arra, hogy ezek minél előbb megvalósuljanak.

2024 Q2

Többnyelvűség mind lekérdezéseknél, mind a honlapon

Árak

A szolgáltatás alapvetően ingyenes. Árainkat és határainkat úgy próbáljuk beállítani, hogy minél kielégítőbb szolgáltatást tudjunk nyújtani, közben igazságosak legyünk mindenkivel. Ez alapján a csapat a következő előfizetési lehetőségeket nyújta:

INGYENES

0 Ft / hó

Maximum 1 db lekérdezés / 10 másodperc

Havi maximum 100 db lekérdezés

Maximum 12 "saját nap" rögzítése

PRO

399 Ft / hó

Nincs a lekérdezés időkorlát

Prediktív dátumok (jövőbeli, még nem elfogadott lehetséges munkaszüneti és áthelyezett munkanapok)

Havi maximum 10000 db lekérdezés

Nincs "saját nap" rögzítési korlát

TÁMOGATÓ

Ezt Ön határozza meg

Ez az előfizetés azoknak szól akik szeretnék támogatni a fejlesztői csapatunkat, hogy bővíteni tudjuk a szolgáltatásainkat, egyszerűbbé és élvezhetőbbé tegyük munkáját.

Továbbá, a köszönetek részbe beírjuk a nevét, megjelenítjük logóját, linket adunk a honlapjára.

Az árak bruttóban értendők.

köszönet

Hálás köszönet jár StartERP-nek és ABStudio-nak, mint arany szintű támogatók!

Icons made by Smashicons from www.flaticon.com