Utile v1 / Sarbatori

Sărbătorile unui an ori interval

Sărbătorile unei ţări pe un an ori pe un interval, cu tipul fiecăreia şi cu subdiviziunile în care se aplică, unde nu sunt naţionale.

GET

https://oneapi.ro/api/utile/v1/sarbatori/{tara}

Parametri de cale

NumeTipDescriereExemplu

taraobligatoriu string Codul ISO 3166-1 alpha-2 al ţării (ex. RO).

Parametri de interogare

NumeTipDescriereValori acceptate

anopțional integer | null Anul calendaristic, între 1970 și 2100. Implicit anul curent. Nu se combină cu de_la/pana_la. 1970 – 2100

de_laopțional string | null Opțional, împreună cu pana_la: prima zi a intervalului, inclusiv, AAAA-LL-ZZ. ex. 2026-12-20

pana_laopțional string | null Opțional, împreună cu de_la: ultima zi a intervalului, inclusiv. Intervalul atinge cel mult 3 ani calendaristici. ex. 2027-01-10

limbaopțional string | null Limba numelor, ca ro, de sau de_AT. Implicit ro. Se aplică doar țărilor calculate — pentru România numele vin din lege, în română. max 12 car.

Cum se comportă

Un interval peste granița anilor — „ce sărbători cad între 20 decembrie și 10 ianuarie" — se cere cu de_la și pana_la, într-un singur apel; răspunsul poartă atunci de_la/pana_la în locul lui an. Perioada se cere o singură dată: an împreună cu intervalul dă 422.
O zi poate purta DOUĂ sărbători. În 2026, în România, A doua zi de Rusalii cade pe Ziua Copilului. De aceea răspunsul e o LISTĂ, nu o hartă dată→nume: o hartă ar pierde tăcut una dintre ele.
Pentru țările calculate, tip vine de la bibliotecă: official e, în general, zi nelucrătoare, iar observance sau season sunt zile marcate, nu libere. Câmpul nelucratoare reflectă tipul declarat, NU o verificare făcută de noi față de legislația țării.
verificat e cel mai important câmp din răspuns. Când e false, cifrele sunt bune pentru planificare, dar nu pentru un termen legal — pentru asta ai nevoie de sursa oficială a țării.
Pentru România, ruta e o oglindă a calendarului legal din modulul Financiar (/financiar/v1/sarbatori?an=). Nu sunt două seturi de date, ci același, expus și aici ca să nu trebuiască schimbat modulul când treci de la RO la restul lumii.

La ce folosește

Construiești calendarul de concedii al unei echipe distribuite în mai multe țări.
Marchezi zilele nelucrătoare într-un planificator sau într-un calendar de livrări.
Compari câte zile libere are un an față de altul, pentru planificarea capacității.

Structura răspunsului

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

CâmpTipDescriere

tara string Codul cerut, normalizat cu majuscule.

an integer Anul cerut; lipsește când s-a cerut un interval.

inregistrari integer Câte sărbători sunt în listă.

zile[] array Lista sărbătorilor, ordonată cronologic.

zile[].data string Ziua, AAAA-LL-ZZ.

zile[].nume string Denumirea, în limba cerută.

zile[].cheie string Identificatorul stabil al sărbătorii (craciun_1, goodFriday) — folosește-l la comparații, nu numele, care depinde de limbă.

zile[].mobila boolean Doar la România: dacă data se mută de la an la an (Paștele, Rusaliile).

zile[].nelucratoare boolean Dacă ziua e liberă. La România vine din lege; în rest, din tipul declarat.

sursa string De unde vin zilele, scris explicit.

verificat boolean true doar dacă sursa e textul legii.

temei string Actul normativ, unde există.

observatie string Precizare despre cum se citeşte răspunsul: o convenţie de calcul sau o limită a datelor.

de_la string Prima zi a intervalului cerut; doar la de_la/pana_la.

pana_la string Ultima zi a intervalului cerut; doar la de_la/pana_la.

zile[].tip string Doar la țările calculate: tipul declarat de bibliotecă.

Exemple de răspuns

GEThttps://oneapi.ro/api/utile/v1/sarbatori/RO

{
    "data": {
        "tara": "RO",
        "an": 2026,
        "inregistrari": 16,
        "zile": [
            {
                "data": "2026-01-01",
                "nume": "Anul Nou",
                "cheie": "anul_nou_1",
                "mobila": false,
                "nelucratoare": true
            }
        ],
        "sursa": "art. 139 din Codul Muncii (Legea 53/2003), prin modulul Financiar",
        "verificat": true,
        "temei": "Legea 53/2003, art. 139",
        "observatie": "Zilele vin din textul legii, prin modulul Financiar."
    }
}

GEThttps://oneapi.ro/api/utile/v1/sarbatori/RO?de_la=2026-12-20&pana_la=2027-01-10

{
    "data": {
        "tara": "RO",
        "de_la": "2026-12-20",
        "pana_la": "2027-01-10",
        "inregistrari": 6,
        "zile": [
            {
                "data": "2026-12-25",
                "nume": "Crăciunul",
                "cheie": "craciun_1",
                "mobila": false,
                "nelucratoare": true
            }
        ],
        "sursa": "art. 139 din Codul Muncii (Legea 53/2003), prin modulul Financiar",
        "verificat": true,
        "temei": "Legea 53/2003, art. 139",
        "observatie": "Zilele vin din textul legii, prin modulul Financiar."
    }
}

GEThttps://oneapi.ro/api/utile/v1/sarbatori/DE?an=2027&limba=de

{
    "data": {
        "tara": "DE",
        "an": 2027,
        "inregistrari": 11,
        "zile": [
            {
                "data": "2027-01-01",
                "nume": "Neujahr",
                "cheie": "newYearsDay",
                "tip": "official",
                "nelucratoare": true
            }
        ],
        "sursa": "Yasumi (MIT) — calculat algoritmic",
        "verificat": false,
        "temei": null,
        "observatie": "Zilele sunt CALCULATE de Yasumi, nu confruntate cu legislația țării. `nelucratoare` reflectă tipul declarat de bibliotecă (`official`), nu o verificare făcută de noi."
    }
}

GEThttps://oneapi.ro/api/utile/v1/sarbatori/DE

{
    "data": {
        "tara": "DE",
        "an": 2026,
        "inregistrari": 11,
        "zile": [
            {
                "data": "2026-01-01",
                "nume": "Anul Nou",
                "cheie": "newYearsDay",
                "tip": "official",
                "nelucratoare": true
            }
        ],
        "sursa": "Yasumi (MIT) — calculat algoritmic",
        "verificat": false,
        "temei": null,
        "observatie": "Zilele sunt CALCULATE de Yasumi, nu confruntate cu legislația țării. `nelucratoare` reflectă tipul declarat de bibliotecă (`official`), nu o verificare făcută de noi."
    }
}

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ă. Lista completă e la `/utile/v1/sarbatori/tari`.
422	validare	Anul ori intervalul e în afara lui 1970–2100, intervalul e incomplet, depășește 3 ani calendaristici ori e combinat cu `an`.
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": "Anul ori intervalul e în afara lui 1970–2100, intervalul e incomplet, depășește 3 ani calendaristici ori e combinat cu an.",
        "detalii": {
            "tara": [
                "Valoarea trimisă nu respectă regula parametrului."
            ]
        }
    }
}