Verifică o adresă

Corpul cererii

Se trimite ca JSON, în corpul cererii (Content-Type: application/json) — nu în şirul de interogare.

{
    "tara": "RO",
    "nume": "Ion Popescu",
    "strada": "Str. Memorandumului 28",
    "localitate": "Cluj-Napoca",
    "cod_postal": "400114"
}

{
    "tara": "RO",
    "strada": "x",
    "localitate": "Cluj-Napoca",
    "cod_postal": "4001"
}

{
    "tara": "DE",
    "strada": "Unter den Linden 1",
    "localitate": "Berlin",
    "cod_postal": "10117"
}

Parametri de interogare

Cum se comportă

• POST, cu adresa în corp (JSON): tara (obligatoriu, ISO alpha-2), nume, organizatie, strada, subzona (cartier, sector), localitate, regiune (județ, stat, provincie), cod_postal, cod_sortare (CEDEX în Franța). Numele destinatarului și adresa sunt date personale: într-un URL ar ajunge în logurile de acces, în cache și în refererul oricărei pagini care cheamă ruta — de aceea un GET primește 405 metoda_nepotrivita. Nimic nu se reține.
• Verificarea e de FORMĂ, nu de existență. Confirmă că sunt completate câmpurile cerute de țară, că tiparul codului poștal se potrivește și că regiunea e una recunoscută. NU confirmă că adresa există la fața locului — pentru asta ar trebui registrul poștal al fiecărei țări.
• Tiparul codului poștal e ancorat înainte de comparație. Sursa îl dă fără ancore, iar folosit așa, 12 ar trece pentru România, fiindcă s-ar potrivi în interiorul unui șir mai lung.
• Regiunea se compară fără diacritice: „Timis" găsește „Timiș". Verifică doar că e o subdiviziune REALĂ a țării, nu că se potrivește cu localitatea — pentru asta ar trebui maparea localitate→județ, pe care sursa n-o are.
• Pentru România, dacă ai nevoie de verificare pe date reale — că strada există în localitatea aia, cu codul poștal acela — folosește /locations/v1/validare/adresa, care se sprijină pe nomenclatorul oficial.
• adresa_formatata se întoarce chiar și când adresa e invalidă, ca să vezi cum ar arăta. Câmpurile lipsă lasă linii goale, care se elimină, iar separatorii orfani (virgule rămase singure) se curăță.

La ce folosește

• Verifici la checkout dacă adresa introdusă e completă pentru țara aleasă, înainte de a accepta comanda.
• Cureți un import de adrese, marcând rândurile cu cod poștal care nu se potrivește cu tiparul țării.
• Compui adresa formatată pentru etichetă, în ordinea corectă a țării.

Structura răspunsului

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

Exemple de răspuns

{
    "data": {
        "tara": "RO",
        "valida": true,
        "probleme": [],
        "adresa_formatata": [
            "Ion Popescu",
            "STR. MEMORANDUMULUI 28",
            "400114 CLUJ-NAPOCA"
        ],
        "observatie": "Verificarea e de FORMĂ: câmpuri cerute, tiparul codului poștal, subdiviziune recunoscută. NU confirmă că adresa există la fața locului.",
        "sursa": {
            "nume": "Google libaddressinput — metadatele de adresare folosite de Chrome",
            "licenta": "Apache-2.0."
        }
    }
}

{
    "data": {
        "tara": "RO",
        "valida": false,
        "probleme": [
            {
                "camp": "cod_postal",
                "problema": "nu se potrivește cu tiparul țării",
                "tipar": "\\d{6}",
                "exemple": [
                    "060274",
                    "061357",
                    "200716"
                ]
            }
        ],
        "adresa_formatata": [
            "X",
            "4001 CLUJ-NAPOCA"
        ],
        "observatie": "Verificarea e de FORMĂ: câmpuri cerute, tiparul codului poștal, subdiviziune recunoscută. NU confirmă că adresa există la fața locului.",
        "sursa": {
            "nume": "Google libaddressinput — metadatele de adresare folosite de Chrome",
            "licenta": "Apache-2.0."
        }
    }
}

{
    "data": {
        "tara": "DE",
        "valida": true,
        "probleme": [],
        "adresa_formatata": [
            "Unter den Linden 1",
            "10117 Berlin"
        ],
        "observatie": "Verificarea e de FORMĂ: câmpuri cerute, tiparul codului poștal, subdiviziune recunoscută. NU confirmă că adresa există la fața locului.",
        "sursa": {
            "nume": "Google libaddressinput — metadatele de adresare folosite de Chrome",
            "licenta": "Apache-2.0."
        }
    }
}

Coduri de eroare

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": "Lipsește tara ori un câmp depășește lungimea maximă."
    }
}