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 limita primești 429 rate_limited împreună cu un header Retry-After. Respectă-l și reîncearcă cu exponential backoff.
| Header | Descriere |
|---|---|
X-RateLimit-Limit | Numărul maxim de cereri permise în fereastra curentă. |
X-RateLimit-Remaining | Câte cereri îți mai rămân în fereastra curentă. |
X-RateLimit-Reset | Timestamp Unix la care fereastra se resetează. |
Retry-After | Secunde 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
{
"code": "rate_limited",
"message": "You exceeded the per-minute request rate.",
"request_id": "req_01J9Z8H..."
}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" }'