Adrese

Validare adresă

Checkout-ul colectează ce scrie clientul. Fiecare curier așteaptă altceva, mai strict — și fiecare altfel. Trimite adresa pe care o ai și primești singura formă pe care o acceptă toți.

Unde se pierde coletul

Un API de curierat nu negociază: compară localitatea și județul cu propriul nomenclator, exact. Un caracter greșit și expedierea este refuzată — sau, mai rău, acceptată și trimisă în alt oraș.

Bucureşti · Sectorul 3 · —

Diacritice, sector scris cum se vorbește, fără cod poștal.

Brebu Mânăstirei · PH · 100127

Județ ca cod. Codul poștal este al unei străzi din Ploiești, la 30 km.

Str. Florica nr. 22, bl. A2, ap. 12

Stradă, număr, bloc și apartament într-un singur câmp.

Toate trei trec validarea din checkout, și niciuna nu este ceva ce poți cere clientului să repare. Un singur apel le aduce la forma pe care o recunosc DPD, Sameday, Cargus, FAN Courier, GLS și Curiera.

Măsurat pe cele 24.928 de adrese ajunse la Livrǎria în cele 90 de zile până la 28 octombrie 2026.

Cât de des	Ce se întâmplă
1 din 14	Fără cod poștal. 1.801 adrese au venit cu câmpul gol. Fără el, localitatea trebuie să se potrivească exact cu tabelul curierului — iar când nu se potrivește, ridicarea de la adresă este refuzată.
`PH`	Două formate, un magazin. WooCommerce ține județul ca cod ISO. Citești câmpul brut și trimiți `PH`; citești eticheta și trimiți `Prahova`. Tabelul curierului are `PRAHOVA`.
`Vâlcea`	Diacritice și cvasi-potriviri. `Bucureşti`, `Sectorul 3`, `Miercurea-Ciuc`, o localitate cu comuna în paranteză. Toate reale, toate corecte pentru un om, niciuna o potrivire.
30 km	Un cod poștal care se potrivește altundeva. Cel greșit dar valid este cel periculos: expedierea este acceptată, iar coletul pleacă spre orașul căruia aparține codul.

Apelul

POST/address/validateBearer JWT120 cereri/minut

Trimite câmpurile pe care le ai, oricum le numește platforma ta. Nimic nu este obligatoriu: o adresă incompletă primește un răspuns parțial și avertismente, nu o eroare.

Apelul nu creează și nu modifică nimic, deci poate fi făcut la fiecare coș.

Corpul cererii

Câmp	Tip	Cerut	Descriere
`county`	string	opțional	Județul. Un cod de două litere (`PH`), diacritice (`Vâlcea`) sau litere mici sunt toate acceptate. Sinonim: `state`.
`city`	string	opțional	Localitatea sau sectorul, oricum e scris. Poate veni cu comuna în paranteză: `PLOPENI (DUMBRAVESTI)`.
`postcode`	string	opțional	Cod poștal, șase cifre. Dezambiguizează localități cu același nume, dar nu învinge niciodată localitatea trimisă.
`street`	string	opțional	Strada. Poate fi toată adresa într-un singur text — numărul, blocul, scara, etajul și apartamentul sunt extrase pentru tine. Sinonim: `address`.
`streetNumber, block, staircase, floor, apartment`	string	opțional	Trimise separat, câștigă întotdeauna față de ce s-ar extrage din textul străzii.
`country`	string	opțional	Implicit România. Orice altă țară este returnată neschimbată, cu un avertisment `COUNTRY_NOT_SUPPORTED`.

Cerere

bash

curl -X POST "https://www.api.livraria.ro/address/validate" \
  -H "Authorization: Bearer <accessToken>" \
  -H "Content-Type: application/json" \
  -d '{
    "state":    "PH",
    "city":     "Brebu Mânăstirei",
    "postcode": "100127",
    "address":  "Str. Florica nr. 22, ap. 12"
  }'

Răspuns 200

JSON

{
  "status": "CORRECTED",
  "address": {
    "country":          "Romania",
    "county":           "PRAHOVA",
    "city":             "BREBU MANASTIREI",
    "postcode":         "107105",
    "street":           "Str. Florica",
    "streetNumber":     "22",
    "apartment":        "12",
    "localityPostcode": "107105"
  },
  "corrections": [
    { "field": "county",   "from": "PH",     "to": "PRAHOVA", "code": "COUNTY_CODE_EXPANDED" },
    { "field": "postcode", "from": "100127", "to": "107105",  "code": "POSTCODE_FROM_LOCALITY" }
  ],
  "warnings": [
    {
      "code": "POSTCODE_LOCALITY_MISMATCH",
      "field": "postcode",
      "message": "Postcode 100127 belongs to PLOIESTI (PRAHOVA), not BREBU MANASTIREI (PRAHOVA); the city was kept and the postcode replaced."
    }
  ],
  "locality": {
    "name":         "BREBU MANASTIREI",
    "county":       "PRAHOVA",
    "postcode":     "107105",
    "municipality": "COM. BREBU"
  }
}

Acesta este cazul real din spatele rutei: 100127 este un cod de stradă din Ploiești, tastat pentru un sat la 30 km. Localitatea trimisă câștigă, codul este înlocuit, iar neconcordanța este raportată.

status

Valoare	Ce faci
`VALID`	Adresa este deja canonică. Nimic de făcut.
`CORRECTED`	Utilizabilă. Expediază adresa returnată, nu cea trimisă — fiecare schimbare este listată în `corrections`.
`UNRESOLVED`	Nicio localitate din România nu se potrivește. Întreabă clientul înainte să plece un colet.

Coduri de corecție

Fiecare intrare din corrections are field, from, to și un code stabil, pe care îl poți înregistra sau ramifica. Citite în timp, ele îți spun ce greșește constant checkout-ul tău — și poți repara acolo, la sursă.

Cod	Ce înseamnă
`COUNTY_CODE_EXPANDED`	Codul de două litere a fost extins: PH → PRAHOVA.
`NORMALIZED_SPELLING`	Doar diacritice și/sau majuscule: Bucureşti → BUCURESTI.
`COUNTY_DERIVED_FROM_CITY`	Județul lipsea și o singură localitate are acest nume.
`COUNTY_DERIVED_FROM_POSTCODE`	Județul lipsea și codul poștal trimis l-a indicat.
`CITY_COUNTY_SWAPPED`	Localitatea și județul au venit inversate.
`CITY_DERIVED_FROM_POSTCODE`	Localitatea lipsea și codul poștal trimis a indicat-o.
`BUCHAREST_SECTOR_CANONICALIZED`	Sectorul a fost adus la forma SECTOR N.
`CITY_MATCHED_NOMENCLATURE`	Localitatea s-a potrivit cu o grafie diferită din nomenclator.
`POSTCODE_FROM_STREET`	Codul poștal vine din nomenclatorul de străzi, pe intervalul de numere.
`POSTCODE_FROM_LOCALITY`	Codul poștal vine din localitate, în lipsa unuia mai precis.
`PARSED_FROM_STREET_LINE`	Componentă extrasă din adresa scrisă într-un singur câmp.

Coduri de avertisment

Un avertisment nu este o eroare. STREET_NOT_FOUND apare doar pentru o localitate pe care nomenclatorul o acoperă stradă cu stradă, deci înseamnă de obicei o grafie greșită — expedierea se face în continuare pe codul localității. Doar LOCALITY_NOT_FOUND pune destinația la îndoială.

Cod	Ce înseamnă
`LOCALITY_NOT_FOUND`	Nicio localitate din România nu se potrivește. Destinația ar fi o presupunere — întreabă clientul.
`COUNTY_AMBIGUOUS`	Numele localității există în mai multe județe; trimite județul.
`POSTCODE_LOCALITY_MISMATCH`	Codul poștal trimis aparține altei localități. Localitatea a câștigat, codul a fost înlocuit.
`POSTCODE_UNKNOWN`	Nu s-a putut stabili niciun cod poștal.
`STREET_NOT_FOUND`	Strada nu apare în nomenclatorul localității — iar localitatea este una acoperită stradă cu stradă, deci verifică grafia.
`FIELD_TOO_LONG`	Valoarea depășește limita acceptată la creare expediție și ar fi refuzată acolo.
`COUNTRY_NOT_SUPPORTED`	Adresă din afara României; a fost returnată neschimbată.

Erori

Cod	Când
`401`	Token lipsă sau invalid.
`400`	Corp malformat: un câmp care nu este text, sau un câmp nedeclarat.

Dacă preferi căutările una câte una — județe, orașe, coduri poștale — sunt pe pagina Date de referință. Ruta de aici le face pe toate într-un singur apel și, în plus, îți spune ce nu a putut determina.

Ai nevoie de ajutor?

Dacă o adresă reală primește UNRESOLVED și crezi că ar trebui să se potrivească, trimite-ne-o: nomenclatorul se poate completa.

Contactează-ne