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.ro 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.SIRUTA — de ce contează
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.ro 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. - Coduri dezafectate: Poșta Română a rearanjat periodic codurile. posty.ro marchează codurile istorice cu status: "inactive" și sugerează succesorul unde îl cunoaște. - Cutii poștale: intervalul 999xxx este rezervat cutiilor poștale și nu corespunde unor adrese fizice.