Utile v1 / Adrese

Format poștal

Cum se scrie o adresă într-o ţară: ordinea liniilor, ce câmpuri sunt obligatorii, cum se cheamă subdiviziunea pe limba locului. Pentru formulare care nu presupun forma românească.

GET

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

Parametri de cale

NumeTipDescriereExemplu

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

Parametri de interogare

Ruta nu acceptă parametri de interogare.

Cum se comportă

Șablonul format e păstrat BRUT, așa cum îl dă sursa: %N nume, %O organizație, %A stradă, %C localitate, %S regiune, %Z cod poștal, %n linie nouă. Câmpul campuri îl traduce, ca să nu trebuiască să parsezi tu literele.
54 din cele 252 de țări nu declară un șablon propriu și primesc șablonul implicit al sursei. În cazul lor format_implicit e true — nu e o lipsă de date, e comportamentul documentat al sursei.
70 de țări n-au deloc coduri poștale (Angola, Hong Kong, Panama). Pentru ele cod_postal.exista e false, ceea ce e o informație, nu un gol: înseamnă că nu trebuie să ceri codul în formular.
Etichetele locale contează la interfețe. Un formular care cere „State" unui britanic sau „ZIP" unui român arată ca tradus prost, deși toate câmpurile sunt corecte.

La ce folosește

Generezi dinamic formularul de adresă din checkout, cu câmpurile în ordinea corectă pentru țara aleasă.
Afli dacă țara cere cod poștal și cum arată el, ca să validezi înainte de trimitere.
Etichetezi corect câmpul de regiune: „state" în SUA, „county" în Marea Britanie, „județ" în România.

Structura răspunsului

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

CâmpTipDescriere

tara string Ţara la care se referă valoarea.

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

format string Șablonul brut de așezare a câmpurilor.

format_implicit boolean true dacă țara nu declară un șablon propriu și s-a aplicat cel implicit.

format_local null

campuri[] array Șablonul tradus: fiecare câmp cu cheia, litera, descrierea și dacă e obligatoriu.

campuri[].cheie string

campuri[].litera string

campuri[].descriere string Explicaţia în cuvinte a valorii.

campuri[].obligatoriu boolean

obligatorii array Cheile câmpurilor fără de care adresa e incompletă în țara asta.

majuscule array Câmpurile pe care poșta țării le vrea cu majuscule.

cod_postal.exista boolean Dacă țara folosește coduri poștale.

cod_postal.regex string Tiparul codului, fără ancore — pune-le tu dacă îl folosești direct.

cod_postal.exemple array Coduri reale, utile ca placeholder într-un formular.

cod_postal.eticheta_locala null Cum se numește codul în țara asta (zip, postal, pin).

etichete_locale array Numele locale ale câmpurilor de regiune, localitate și sub-localitate.

url_posta string Pagina oficială de căutare a codurilor poștale, unde sursa o cunoaște.

are_subdiviziuni boolean Dacă țara are o listă de subdiviziuni recunoscute poștal.

observatie null 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.licenta string Licenţa sub care sursa permite reutilizarea.

Exemple de răspuns

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

{
    "data": {
        "tara": "RO",
        "nume": "România",
        "format": "%N%n%O%n%A%n%Z %S %C",
        "format_implicit": false,
        "format_local": null,
        "campuri": [
            {
                "cheie": "nume",
                "litera": "N",
                "descriere": "numele destinatarului",
                "obligatoriu": false
            }
        ],
        "obligatorii": [
            "strada",
            "localitate",
            "cod_postal"
        ],
        "majuscule": [
            "strada",
            "localitate"
        ],
        "cod_postal": {
            "exista": true,
            "regex": "\\d{6}",
            "exemple": [
                "060274",
                "061357",
                "200716"
            ],
            "eticheta_locala": null
        },
        "etichete_locale": [],
        "url_posta": "http://www.posta-romana.ro/zip_codes",
        "are_subdiviziuni": true,
        "observatie": null,
        "sursa": {
            "nume": "Google libaddressinput — metadatele de adresare folosite de Chrome",
            "licenta": "Apache-2.0."
        }
    }
}

GEThttps://oneapi.ro/api/utile/v1/adrese/TZ

{
    "data": {
        "tara": "TZ",
        "nume": "Tanzania",
        "format": "%N%n%O%n%A%n%Z %C",
        "format_implicit": false,
        "format_local": null,
        "campuri": [
            {
                "cheie": "nume",
                "litera": "N",
                "descriere": "numele destinatarului",
                "obligatoriu": false
            }
        ],
        "obligatorii": [],
        "majuscule": [],
        "cod_postal": {
            "exista": true,
            "regex": "\\d{4,5}",
            "exemple": [
                "6090",
                "34413"
            ],
            "eticheta_locala": null
        },
        "etichete_locale": [],
        "url_posta": null,
        "are_subdiviziuni": false,
        "observatie": null,
        "sursa": {
            "nume": "Google libaddressinput — metadatele de adresare folosite de Chrome",
            "licenta": "Apache-2.0."
        }
    }
}

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

{
    "data": {
        "tara": "DE",
        "nume": "Germania",
        "format": "%N%n%O%n%A%n%Z %C",
        "format_implicit": false,
        "format_local": null,
        "campuri": [
            {
                "cheie": "nume",
                "litera": "N",
                "descriere": "numele destinatarului",
                "obligatoriu": false
            }
        ],
        "obligatorii": [
            "strada",
            "localitate",
            "cod_postal"
        ],
        "majuscule": [],
        "cod_postal": {
            "exista": true,
            "regex": "\\d{5}",
            "exemple": [
                "26133",
                "53225"
            ],
            "eticheta_locala": null
        },
        "etichete_locale": [],
        "url_posta": "http://www.postdirekt.de/plzserver/",
        "are_subdiviziuni": false,
        "observatie": null,
        "sursa": {
            "nume": "Google libaddressinput — metadatele de adresare folosite de Chrome",
            "licenta": "Apache-2.0."
        }
    }
}

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	Nu avem reguli de adresare pentru codul dat.
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": "negasit",
        "mesaj": "Nu avem reguli de adresare pentru codul dat."
    }
}