oneapi
Autentificare
Utile v1 / Coduri

Coduri de țară

Lista ISO 3166-1 a ţărilor, cu alpha-2, alpha-3, codul numeric şi denumirea în română şi engleză. Baza pentru orice câmp de ţară.

GET
https://oneapi.ro/api/utile/v1/coduri/tari

Parametri de interogare

NumeTipDescriereValori acceptate
continentopțional string | null Filtrează: Africa, America, Asia, Europa, Oceania, Antarctica. AfricaAmericaAsiaEuropaOceaniaAntarctica
valutaopțional string | null Filtrează la țările care folosesc valuta dată (cod ISO 4217, ex. EUR). max 3 car.

Cum se comportă

  • Lista conține și XK (Kosovo), care e cod de uz privat, nu ISO 3166-1 oficial, dar e folosit peste tot în practică. Codurile ieșite din uz (SU, YU, ZR, DD) și grupările care nu sunt țări (EU, ZZ) sunt excluse.
  • Weekendul nu e sâmbătă+duminică peste tot. În Arabia Saudită și Israel e vineri+sâmbătă; în India e doar duminica. weekend și prima_zi_saptamana vin din CLDR și sunt exact ce folosește zona de sărbători la calculul zilelor lucrătoare.
  • Numerele zilelor sunt ISO 8601: 1 = luni, 7 = duminică. CLDR le numără de la duminică; traducerea e făcută aici, ca să nu circule două convenții.
  • Datele vin din ICU/CLDR, care e în runtime. Se actualizează la un upgrade de imagine, nu printr-un import — de aceea versiunea CLDR e în răspuns.

La ce folosește

  • Populezi un selector de țări cu numele în română, nu în engleză.
  • Traduci între alpha-2, alpha-3 și codul numeric, când integrezi două sisteme care folosesc forme diferite.
  • Afli ce zile sunt weekend într-o țară, înainte de a programa livrări sau ture.

Structura răspunsului

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

CâmpTipDescriere
inregistrari integer Câte înregistrări are răspunsul.
tari[].alpha_2 string Codul de două litere (RO).
tari[].alpha_3 string Codul de trei litere (ROU).
tari[].numeric string Codul numeric (642).
tari[].nume string Numele în română.
tari[].nume_en string Numele în engleză.
tari[].continent string Continentul, din arborele UN M49.
tari[].valuta string Codul valutei oficiale, sau null la teritoriile fără monedă proprie.
tari[].prima_zi_saptamana integer Cu ce zi începe săptămâna, ISO 8601 (1 în România, 7 în SUA).
tari[].weekend array Zilele de weekend, ca numere ISO.
observatie string Precizare despre cum se citeşte răspunsul: o convenţie de calcul sau o limită a datelor.
sursa.nume string Denumirea sursei oficiale.
sursa.versiune string Versiunea setului de date sau a artefactului din care vin valorile.
sursa.licenta string Licenţa sub care sursa permite reutilizarea.
sursa.observatie string Ce trebuie ştiut despre sursă înainte de a folosi datele.

Exemple de răspuns

GEThttps://oneapi.ro/api/utile/v1/coduri/tari
{
    "data": {
        "inregistrari": 251,
        "tari": [
            {
                "alpha_2": "AD",
                "alpha_3": "AND",
                "numeric": "020",
                "nume": "Andorra",
                "nume_en": "Andorra",
                "continent": "Europa",
                "valuta": "EUR",
                "prima_zi_saptamana": 1,
                "weekend": [
                    6,
                    7
                ]
            }
        ],
        "observatie": "Lista conține și XK (Kosovo), care e cod de uz privat, nu ISO 3166-1 oficial, dar e folosit peste tot în practică. Codurile ieșite din uz (SU, YU, ZR) sunt excluse.",
        "sursa": {
            "nume": "ICU / CLDR (Unicode Common Locale Data Repository), prin runtime-ul PHP",
            "versiune": "76.1",
            "licenta": "Unicode License.",
            "observatie": "Se actualizează la un upgrade de imagine, nu printr-un import — de aceea versiunea CLDR e în răspuns."
        }
    }
}

Coduri de eroare

CodSlugCând apare
401neautentificatToken lipsă, invalid, expirat sau revocat.
403feature_indisponibilPlanul curent nu include funcţia de care ţine ruta.
422validareUn parametru nedeclarat ori o valoare care nu trece validarea (continent, valuta). Câmpul vinovat e în detalii.
429cota_depasitaCota 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 nedeclarat ori o valoare care nu trece validarea (continent, valuta). Câmpul vinovat e în detalii.",
        "detalii": {
            "continent": [
                "Valoarea trimisă nu respectă regula parametrului."
            ]
        }
    }
}