oneapi
Autentificare
Locations v1 / Validare adrese

Reconciliază text ↔ structurat

Primește DOUĂ reprezentări ale aceleiași adrese — un string liber q ȘI/SAU câmpuri
structurate — le suprapune câmp cu câmp și RAPORTEAZĂ: unde se completează, unde coincid
și unde intră în conflict. Nu arbitrează (câmpurile în conflict nu intră în reconciliat).
Județul se compară canonic (cod „CJ" ≡ nume „Cluj").

GET
https://oneapi.ro/api/locations/v1/validare/reconciliere

Parametri de interogare

NumeTipDescriereValori acceptate
qopțional string | null Adresă ca text liber (ex. „Str. Memorandumului 28, Cluj-Napoca"). max 255 car.
judetopțional string | null Județul din formular (cod „CJ" sau nume „Cluj"). max 100 car.
localitateopțional string | null Localitatea din formular. max 150 car.
stradaopțional string | null Strada din formular. max 200 car.
numaropțional string | null Numărul din formular. max 30 car.
cod_postalopțional string | null Codul poștal din formular. max 10 car.

Cum se comportă

  • Primește DOUĂ reprezentări ale aceleiași adrese — un string liber q ȘI/SAU câmpuri structurate (judet/localitate/strada/numar/cod_postal) — și le suprapune câmp cu câmp.
  • RAPORTEAZĂ, nu arbitrează: concordanta[camp].stare ∈ {doar_q, doar_structural, concorda, conflict}. Câmpurile în conflict NU intră în reconciliat — apar doar în conflicte; clientul decide cine câștigă.
  • Județul se compară canonic: „CJ" (cod) și „Cluj" (nume) coincid, nu dau conflict fals. Numărul rămas la coada străzii din q („Memorandumului 28") e mutat automat în numar.

La ce folosește

  • Ecommerce cu dropdown-uri ȘI câmp liber: compari ce a ales userul (județ/localitate din dropdown) cu ce a scris în text și semnalezi când bat cap în cap.
  • Detectare de greșeli la checkout: userul a ales „Cluj" din dropdown dar a scris o adresă din București → prinzi conflictul înainte de livrare greșită.
  • Completare încrucișată: dropdown-ul dă județ+localitate, textul dă strada+numărul → le combini automat într-o adresă completă (câmpurile fără conflict intră în reconciliat).

Structura răspunsului

CâmpTipDescriere
data.reconciliat object Adresa pe care cele două surse o susțin (fără câmpurile în conflict).
data.concordanta object Per câmp: {stare, valoare} sau {stare:conflict, structural, din_q}.
data.conflicte[] object Câmpurile în care textul liber și cel structurat spun lucruri diferite.
data.are_conflicte boolean true dacă există cel puțin un conflict.
data.reconciliat.judet string Județul rezultat după suprapunerea textului liber peste câmpurile structurate.
data.reconciliat.localitate string Localitatea rezultată.
data.reconciliat.strada string Strada rezultată.
data.concordanta.*.stare Per câmp: concordanta, conflict, sau doar dintr-o singură sursă. Ruta e un RAPORT, nu un arbitru — nu decide ea care sursă are dreptate.
data.concordanta.*.valoare Valoarea reținută pentru câmpul respectiv.
meta.actualizat object Când a fost actualizat ultima dată nomenclatorul administrativ.

Exemple de răspuns

Structuratul dă județ+localitate, q dă strada+numărul.

GEThttps://oneapi.ro/api/locations/v1/validare/reconciliere?judet=CJ&localitate=Cluj-Napoca&q=Strada%20Memorandumului%2028
{
    "data": {
        "reconciliat": {
            "judet": "CJ",
            "localitate": "Cluj-Napoca",
            "strada": "Memorandumului",
            "numar": "28"
        },
        "concordanta": {
            "judet": {
                "stare": "doar_structural",
                "valoare": "CJ"
            },
            "localitate": {
                "stare": "doar_structural",
                "valoare": "Cluj-Napoca"
            },
            "strada": {
                "stare": "doar_q",
                "valoare": "Memorandumului"
            },
            "numar": {
                "stare": "doar_q",
                "valoare": "28"
            }
        },
        "conflicte": [],
        "are_conflicte": false
    },
    "meta": {
        "actualizat": {
            "administrativ": "2026-08-15T16: 39: 14+03: 00"
        }
    }
}

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 (q, judet, localitate, strada, numar, cod_postal). 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 (q, judet, localitate, strada, numar, cod_postal). Câmpul vinovat e în detalii.",
        "detalii": {
            "q": [
                "Valoarea trimisă nu respectă regula parametrului."
            ]
        }
    }
}