/ docs
Autentificare
Referință

Autentificare

Fiecare cerere către API se autentifică cu o cheie API trimisă ca token Bearer. Cheile sunt legate de organizația ta și pot avea permisiuni restrânse.

Token Bearer

Trimite cheia pe headerul Authorization, prefixată cu Bearer. Cheile live încep cu psk_live_, cele de sandbox cu psk_test_. Cheia apare o singură dată la creare — păstreaz-o într-un secret manager, nu în cod sau în control de versiune.

Authorization: Bearer psk_live_3f9a...

Permisiuni per cheie

Fiecare cheie poartă o listă de permisiuni (allowlist) care limitează endpointurile pe care le poate apela. O cheie fără dreptul necesar primește 403 forbidden. Emite chei cu permisiuni minime pentru fiecare integrare și rotește-le din dashboard dacă au fost expuse.

Limite de rată

Răspunsurile includ headere X-RateLimit-* care descriu fereastra curentă. Când depășești rata permisă pentru cheie primești 429 rate_limit_exceeded împreună cu un header Retry-After: așteaptă atât și reîncearcă. Cota lunară epuizată NU este 429: planurile fără depășire primesc 402 quota_exceeded (cu X-Posty-Period-Resets-At), pe care reîncercarea nu îl rezolvă. Doar apelurile facturabile (lookup, căutare, autocomplete, verify, trimitere batch) consumă din cotă; citirea consumului și interogarea statusului batch nu întorc niciodată 402.

HeaderDescriere
X-RateLimit-LimitNumărul maxim de cereri permise în fereastra curentă.
X-RateLimit-RemainingCâte cereri îți mai rămân în fereastra curentă.
X-RateLimit-ResetTimestamp Unix la care fereastra se resetează.
Retry-AfterSecunde de așteptat înainte de a reîncerca (prezent doar pe 429).
HTTP/1.1 429 Too Many Requests
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1718700000
Retry-After: 12
Content-Type: application/json

{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Rate limit exceeded, please slow down",
    "request_id": "a1b2c3d4e5f6a7b8"
  }
}

Alte headere de răspuns

HeaderDescriere
X-Posty-Request-IdIdentificatorul cererii, pe fiecare răspuns (și error.request_id). Include-l când contactezi suportul.
X-CacheHIT când răspunsul vine din cache, MISS când a fost calculat. Lipsește când cache-ul a fost ocolit. Doar pe 200 (lookup cod poștal, autocomplete).
X-Data-AttributionAtribuirea licenței surselor de date (OGL-ROU-1.0; ODbL-1.0 pentru OpenStreetMap când sursa e activă). Dacă afișezi rezultatele, afișează și acest text.
LinkMereu împreună cu X-Data-Attribution: <https://posty.ro/legal/data-sources>; rel="license".
X-Posty-Period-Resets-AtPe 402 quota_exceeded: momentul (RFC 3339) la care se resetează cota lunară.
X-Posty-Grace-Period-EndsPe 402 payment_required: sfârșitul perioadei de grație pentru plata restantă.

Idempotency-Key

Pentru cereri POST poți trimite un header Idempotency-Key (un UUID) ca să eviți procesarea dublă la reîncercări. Reutilizarea aceleiași chei cu un corp diferit întoarce 409 idempotency_conflict; aceeași cheie cu același corp întoarce răspunsul original.

curl -X POST https://api.posty.ro/v1/addresses/verify \
  -H "Authorization: Bearer psk_live_xxx" \
  -H "Idempotency-Key: 7c1f6e2a-9b3d-4e6f-8a1c-2d4f6e8a0b2c" \
  -H "Content-Type: application/json" \
  -d '{ "freeform": "Str. Mihai Viteazu 12, Cluj" }'

© 2026 posty.ro