Utile v1 / Sarbatori

E zi liberă?

Dacă o zi anume e liberă într-o ţară, şi de ce: weekend, sărbătoare legală, sau zi liberă doar într-o subdiviziune.

GET

https://oneapi.ro/api/utile/v1/sarbatori/este-sarbatoare

Parametri de interogare

NumeTipDescriereValori acceptate

taraobligatoriu string OBLIGATORIU. Codul țării sau al subdiviziunii. max 12 car.

dataopțional string | null Ziua verificată, AAAA-LL-ZZ. Implicit azi (ora României). ex. 2026-12-25ex. 2026-12-24ex. 2026-09-11

Cum se comportă

Trei stări diferite, ținute separat înadins: o zi poate fi sărbătoare DAR lucrătoare (o zi marcată, nu liberă), sau liberă fiindcă e weekend, fără să fie sărbătoare. Un singur câmp „liber/nu" ar ascunde care din ele e cazul.
Weekendul nu e sâmbătă+duminică peste tot. Dintre țările cu sărbători acoperite, Iranul are weekend de o singură zi, vinerea. Zilele efectiv folosite sunt în zile_weekend, luate din CLDR — nu presupuse. Convențiile de săptămână există pentru TOATE țările, prin /utile/v1/coduri/tari, chiar și acolo unde nu avem sărbători.
Câmpul se numește zi, nu data, deși parametrul e data: un câmp numit data la primul nivel ar intra în coliziune cu învelișul JSON al platformei.

La ce folosește

Decizi dacă un curier poate livra mâine în țara destinatarului.
Verifici, într-un formular de programare, dacă data aleasă e o zi lucrătoare.
Afli dacă un ordin de plată trimis azi va fi procesat sau va aștepta.

Structura răspunsului

Toate câmpurile de mai jos sunt în data.

CâmpTipDescriere

tara string Ţara la care se referă valoarea.

zi string Ziua verificată.

zi_saptamana integer Ziua săptămânii, ISO 8601 (1 = luni … 7 = duminică).

weekend boolean Dacă ziua cade în weekendul țării respective.

sarbatoare boolean Dacă e marcată ca sărbătoare, indiferent dacă e liberă.

nelucratoare boolean Concluzia practică: weekend SAU sărbătoare nelucrătoare.

zile array Sărbătorile care cad în ziua asta (poate fi mai mult de una).

zile_weekend array Ce zile sunt weekend în țara asta, ca numere ISO.

sursa string De unde vin zilele, scris explicit.

verificat boolean true doar dacă sursa e textul legii.

Exemple de răspuns

GEThttps://oneapi.ro/api/utile/v1/sarbatori/este-sarbatoare?tara=RO

{
    "data": {
        "tara": "RO",
        "zi": "2026-10-06",
        "zi_saptamana": 2,
        "weekend": false,
        "sarbatoare": false,
        "nelucratoare": false,
        "zile": [],
        "zile_weekend": [
            6,
            7
        ],
        "sursa": "art. 139 din Codul Muncii (Legea 53/2003), prin modulul Financiar",
        "verificat": true
    }
}

GEThttps://oneapi.ro/api/utile/v1/sarbatori/este-sarbatoare?tara=RO&data=2026-12-25

{
    "data": {
        "tara": "RO",
        "zi": "2026-12-25",
        "zi_saptamana": 5,
        "weekend": false,
        "sarbatoare": true,
        "nelucratoare": true,
        "zile": [
            {
                "data": "2026-12-25",
                "nume": "Crăciunul",
                "cheie": "craciun_1",
                "mobila": false,
                "nelucratoare": true
            }
        ],
        "zile_weekend": [
            6,
            7
        ],
        "sursa": "art. 139 din Codul Muncii (Legea 53/2003), prin modulul Financiar",
        "verificat": true
    }
}

GEThttps://oneapi.ro/api/utile/v1/sarbatori/este-sarbatoare?tara=DE&data=2026-12-24

{
    "data": {
        "tara": "DE",
        "zi": "2026-12-24",
        "zi_saptamana": 4,
        "weekend": false,
        "sarbatoare": false,
        "nelucratoare": false,
        "zile": [],
        "zile_weekend": [
            6,
            7
        ],
        "sursa": "Yasumi (MIT) — calculat algoritmic",
        "verificat": false
    }
}

GEThttps://oneapi.ro/api/utile/v1/sarbatori/este-sarbatoare?tara=IR&data=2026-09-11

{
    "data": {
        "tara": "IR",
        "zi": "2026-09-11",
        "zi_saptamana": 5,
        "weekend": true,
        "sarbatoare": false,
        "nelucratoare": true,
        "zile": [],
        "zile_weekend": [
            5
        ],
        "sursa": "Yasumi (MIT) — calculat algoritmic",
        "verificat": false
    }
}

Coduri de eroare

Cod	Slug	Când apare
401	neautentificat	Token lipsă, invalid, expirat sau revocat.
403	feature_indisponibil	Planul curent nu include funcţia de care ţine ruta.
404	negasit	Țara nu e acoperită.
422	validare	Un parametru nu a trecut validarea (`tara`, `data`); `detalii` spune care şi de ce.
429	cota_depasita	Cota lunară a planului a fost depăşită (vezi `Retry-After`).

Toate erorile au aceeași formă. eroare.cod e stabil și e cel după care trebuie să ramifici în cod — nu după textul din mesaj, care se poate schimba.

{
    "eroare": {
        "cod": "validare",
        "mesaj": "Un parametru nu a trecut validarea (tara, data); detalii spune care şi de ce.",
        "detalii": {
            "tara": [
                "Valoarea trimisă nu respectă regula parametrului."
            ]
        }
    }
}