Înapoi la blog

Referință

Coduri poștale și SIRUTA: un ghid practic

Structura codurilor poștale din România, ce întoarce GET /v1/postal-codes/{code} și cum folosești codul SIRUTA ca să legi datele de cele INS.

5 min citire

Ce este un cod poștal românesc?

România folosește coduri poștale de șase cifre, introduse de Poșta Română. Structura este:

  • Primele două cifre: județul (ex. 40xxxx = Cluj, 01xxxx = București S1)
  • Cifrele 3–6: zona de distribuție și punctul de livrare

Un cod poștal nu identifică o singură stradă. Poate acoperi mai multe străzi dintr-un cartier. Prin SIRUTA, fiecare cod este legat de o unitate administrativ-teritorială (UAT): comună, oraș sau municipiu.

Endpoint-ul de lookup

GET /v1/postal-codes/{code} returnează tot ce știe Posty despre un cod poștal:

curl https://api.posty.ro/v1/postal-codes/400151 \
  -H "Authorization: Bearer psk_live_xxx"

Răspuns:

{
  "code": "400151",
  "localities": [
    { "name": "Cluj-Napoca", "type": "municipiu", "siruta": 54975, "county_code": "CJ" }
  ],
  "streets": [
    { "name": "Strada Mihai Viteazu" },
    { "name": "Strada Alexandru Vaida-Voevod" }
  ]
}

Cazuri de utilizare frecvente

Pre-completare la checkout

Când userul introduce codul poștal, pre-completezi câmpurile de județ și localitate. Reduci frecarea și elimini o clasă întreagă de erori de scriere.

Validare batch la import

Dacă imporți o listă de clienți sau adrese, faci un lookup pentru fiecare cod poștal înainte de a salva. Adresele cu cod inexistent sau incompatibil cu județul declarat sunt marcate pentru review.

Geocoding indirect

Dacă nu ai nevoie de coordonate exacte dar vrei să plasezi comenzile pe o hartă județeană, codul poștal + SIRUTA îți dau UAT-ul, care are centroid publicat de INS.

De ce contează SIRUTA

SIRUTA (Sistemul Informatic al Registrului Unităților Teritorial-Administrative) este nomenclatorul oficial al INS. Fiecare UAT din România are un cod unic SIRUTA stabil, indiferent de redenumiri sau reorganizări administrative.

Posty include câmpul siruta (integer) în fiecare intrare din localities[], acolo unde este cunoscut. Dacă lucrezi cu date INS sau cu API-uri guvernamentale, acesta este identificatorul pe care îl folosești pentru JOIN cu seturile de date INS.

Edge case-uri de știut

  • Coduri rurale: un sat mic poate fi acoperit de codul poștal al comunei. Câmpul locality reflectă UAT-ul, nu neapărat satul.
  • Ediția datelor: codurile vin din ediția Infocod din mai 2016. Codurile introduse sau schimbate de Poșta Română după aceea pot lipsi.