Locations v1 / Proximitate & zone

Livrezi aici?

⭐ Verifică dacă o locație (punct lat/lng sau cod_postal) cade într-o zonă de
livrare definită de un UAT (uat=cod_siruta) ± vecinii lui. Când e în afară, întoarce
cel mai apropiat UAT din zonă + distanța.

GET

https://oneapi.ro/api/locations/v1/acoperim

Parametri de interogare

NumeTipDescriereValori acceptate

latopțional number | null Latitudinea locației (sau cod_postal). -90 – 90

lngopțional number | null Longitudinea locației. -180 – 180

cod_postalopțional string | null Cod poștal (alternativă la lat/lng). ex. 400001

uatobligatoriu integer cod_siruta al UAT-ului zonei. ex. 54975ex. 179132ex. 114319

include_veciniopțional boolean | null Extinde zona la vecini. 01

Cum se comportă

Locația (punct lat/lng sau cod_postal) cade în zona unui UAT (± vecini)?
Când e în afară, întoarce cel_mai_apropiat UAT din zonă + distanța.

La ce folosește

Buton „Livrăm la tine?" în pagina de produs sau checkout, verificat pe cod poștal sau pin.
Filtrare a comenzilor în afara zonei unui magazin înainte de a le accepta.
Sugerarea celui mai apropiat punct de ridicare/UAT când adresa clientului cade în afara zonei.

Structura răspunsului

CâmpTipDescriere

data.acoperit boolean true dacă locația cade în zona UAT-ului (± vecini când include_vecini=1).

data.uat object UAT-ul din zonă în care cade punctul; null când locația e în afara zonei.

data.uat.cod_siruta integer Codul SIRUTA al UAT-ului — chainable spre /uat/{cod}.

data.uat.nume string Denumirea UAT-ului.

data.uat.tip string Tipul UAT-ului (municipiu/oraș/comună).

data.cel_mai_apropiat object Prezent doar când acoperit=false: cel mai apropiat UAT din zonă.

data.cel_mai_apropiat.cod_siruta integer Codul SIRUTA al celui mai apropiat UAT acoperit, când punctul cade în afară.

data.cel_mai_apropiat.nume string Denumirea celui mai apropiat UAT acoperit.

data.cel_mai_apropiat.distanta_m integer Distanța (metri) până la marginea celui mai apropiat UAT din zonă.

meta.actualizat object Prospețimea datelor pe domenii (dată ISO 8601).

Exemple de răspuns

GEThttps://oneapi.ro/api/locations/v1/acoperim?lat=46.77&lng=23.59&uat=54975

{
    "data": {
        "acoperit": true,
        "uat": {
            "cod_siruta": 54975,
            "nume": "Cluj-Napoca",
            "tip": "municipiu"
        }
    },
    "meta": {
        "actualizat": {
            "administrativ": "2026-08-15T16: 39: 14+03: 00",
            "geo": "2026-09-04T21: 24: 20+03: 00"
        }
    }
}

GEThttps://oneapi.ro/api/locations/v1/acoperim?lat=44.43&lng=26.10&uat=179132

{
    "data": {
        "acoperit": true,
        "uat": {
            "cod_siruta": 179132,
            "nume": "București",
            "tip": "municipiu"
        }
    },
    "meta": {
        "actualizat": {
            "administrativ": "2026-08-15T16: 39: 14+03: 00",
            "geo": "2026-09-04T21: 24: 20+03: 00"
        }
    }
}

GEThttps://oneapi.ro/api/locations/v1/acoperim?lat=46.54&lng=24.56&uat=114319

{
    "data": {
        "acoperit": true,
        "uat": {
            "cod_siruta": 114319,
            "nume": "Târgu Mureș",
            "tip": "municipiu"
        }
    },
    "meta": {
        "actualizat": {
            "administrativ": "2026-08-15T16: 39: 14+03: 00",
            "geo": "2026-09-04T21: 24: 20+03: 00"
        }
    }
}

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	UAT-ul zonei sau codul poștal nu există.
422	validare	Un parametru nu a trecut validarea (`lat`, `lng`, `cod_postal` ş.a.); `detalii` spune care şi de ce.
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": "Un parametru nu a trecut validarea (lat, lng, cod_postal ş.a.); detalii spune care şi de ce.",
        "detalii": {
            "lat": [
                "Valoarea trimisă nu respectă regula parametrului."
            ]
        }
    }
}