Utile v1 / Sarbatori

Țări cu sărbători

Ţările pentru care avem calendarul sărbătorilor, cu marcajul dacă a fost verificat pe actul oficial şi dacă are subdiviziuni cu zile libere proprii.

GET

https://oneapi.ro/api/utile/v1/sarbatori/tari

Parametri de interogare

Ruta nu acceptă parametri de interogare.

Cum se comportă

Ruta există tocmai ca limita să fie vizibilă. Nu acoperim toată lumea: motorul are 47 de țări plus subdiviziunile lor. Cine întreabă de o țară neacoperită trebuie să afle asta dintr-o listă, nu dintr-un răspuns gol care seamănă cu „țara aia n-are sărbători".
Doar România e verificată. Zilele ei vin din art. 139 din Codul Muncii, prin modulul Financiar. Verificarea a fost necesară: comparând ieșirea bibliotecii cu legea, îi lipsea Vinerea Mare — zi liberă din 2018 — și adăuga Ziua Constantin Brâncuși, care e zi de sărbătoare dar NU zi nelucrătoare. Două erori pe singura țară pe care o putem confrunta autoritar.
Subdiviziunile au coduri compuse (DE-BY pentru Bavaria, US-CA pentru California) și se cer la fel ca țările. Sunt utile acolo unde sărbătorile diferă în interiorul țării.

La ce folosește

Verifici dacă țara clientului tău e acoperită înainte de a construi ceva peste rută.
Populezi un selector de țări într-o interfață de calcul al termenelor.
Afli care țări sunt confruntate cu legislația și care sunt doar calculate.

Structura răspunsului

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

CâmpTipDescriere

tari[] array Țările acoperite: {cod, nume, verificat}.

tari[].cod string Codul din nomenclatorul sursei — cheia pe care se filtrează.

tari[].nume string Numele, aşa cum îl publică sursa.

tari[].verificat boolean true doar acolo unde zilele vin din textul legii, nu dintr-un calcul.

subdiviziuni array Codurile compuse ale subdiviziunilor cu calendar propriu.

observatie string Rezumatul acoperirii și al limitei de verificare.

sursa.romania string

sursa.restul string

sursa.de_ce_nu_altceva string

Exemple de răspuns

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

{
    "data": {
        "tari": [
            {
                "cod": "AD",
                "nume": "Andorra",
                "verificat": false
            }
        ],
        "subdiviziuni": [
            "AT-1",
            "AT-2",
            "AT-3",
            "AT-4",
            "AT-5",
            "AT-6",
            "AT-7",
            "AT-8",
            "AT-9",
            "AU-ACT",
            "AU-NSW",
            "AU-NT",
            "AU-QLD",
            "AU-QLD-BRI",
            "AU-SA",
            "AU-TAS",
            "AU-TAS-CN",
            "AU-TAS-FI",
            "AU-TAS-KI",
            "AU-TAS-NE",
            "AU-TAS-NW",
            "AU-TAS-NW-CH",
            "AU-TAS-SOU",
            "AU-TAS-SOU-SE",
            "AU-VIC",
            "AU-WA",
            "CA-AB",
            "CA-BC",
            "CA-MB",
            "CA-NB",
            "CA-NL",
            "CA-NS",
            "CA-NT",
            "CA-NU",
            "CA-ON",
            "CA-PE",
            "CA-QC",
            "CA-SK",
            "CA-YT",
            "CH-AG",
            "CH-AI",
            "CH-AR",
            "CH-BE",
            "CH-BL",
            "CH-BS",
            "CH-FR",
            "CH-GE",
            "CH-GL",
            "CH-GR",
            "CH-JU",
            "CH-LU",
            "CH-NE",
            "CH-NW",
            "CH-OW",
            "CH-SG",
            "CH-SH",
            "CH-SO",
            "CH-SZ",
            "CH-TG",
            "CH-TI",
            "CH-UR",
            "CH-VD",
            "CH-VS",
            "CH-ZG",
            "CH-ZH",
            "DE-BB",
            "DE-BE",
            "DE-BW",
            "DE-BY",
            "DE-HB",
            "DE-HE",
            "DE-HH",
            "DE-MV",
            "DE-NI",
            "DE-NW",
            "DE-RP",
            "DE-SH",
            "DE-SL",
            "DE-SN",
            "DE-ST",
            "DE-TH",
            "ES-AN",
            "ES-AR",
            "ES-AS",
            "ES-CB",
            "ES-CE",
            "ES-CL",
            "ES-CM",
            "ES-CN",
            "ES-CT",
            "ES-EX",
            "ES-GA",
            "ES-IB",
            "ES-MC",
            "ES-MD",
            "ES-ML",
            "ES-NC",
            "ES-PV",
            "ES-RI",
            "ES-VC",
            "FR-57",
            "FR-67",
            "FR-68",
            "GB-ENG",
            "GB-NIR",
            "GB-SCT",
            "GB-WLS",
            "US-NYSE"
        ],
        "observatie": "Acoperim 49 de țări și 108 de subdiviziuni. Doar România e verificată față de legislație (art. 139 Codul Muncii); restul se calculează cu Yasumi și nu sunt confruntate cu textul de lege al fiecărei țări.",
        "sursa": {
            "romania": "art. 139 din Codul Muncii (Legea 53/2003), prin modulul Financiar — verificat",
            "restul": "Yasumi 2.x (MIT) — calculat algoritmic, neconfruntat cu legislația fiecărei țări",
            "de_ce_nu_altceva": "API-ul Nager.Date, alternativa cu cea mai largă acoperire, interzice în termenii lui folosirea datelor pentru „a publica sau opera un portal propriu de sărbători\" și cere sponsorizare pentru uz comercial."
        }
    }
}

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.
422	validare	Ruta nu primeşte parametri, în afară de `lang`: orice alt parametru dă 422, nu e ignorat.
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": "Ruta nu primeşte parametri, în afară de lang: orice alt parametru dă 422, nu e ignorat."
    }
}