Versiuni API

Ce înseamnă /v1, ce schimbări pot apărea fără o versiune nouă și cum se anunță o versiune care rupe compatibilitatea.

Versiunea de azi

Versiunea curentă este v1 și este singura. Rutele produsului încep cu /v1; excepțiile (5) sunt descoperirea OAuth (/.well-known/…) și verificarea de sănătate (/sanatate). Nu există încă nicio rută /v2.

Regula

/v1 rămâne stabil. O integrare scrisă azi pe /v1 continuă să meargă.
Adăugirile nu schimbă versiunea. O rută nouă, un câmp nou în răspuns sau un antet nou, opțional, apar direct în /v1.
O schimbare care rupe ceva apare doar într-o versiune nouă (/v2). Scoaterea sau redenumirea unei rute ori a unui câmp, schimbarea tipului unui câmp sau un câmp nou obligatoriu în cerere nu se fac în /v1.
Cel puțin 6 luni merg amândouă. Când apare /v2, /v1 rămâne activă alături de ea cel puțin 6 luni.
Orice versiune nouă se anunță în Noutăți, cu data de la care merge și data până la care rămâne activă cea veche.

Adăugiri care au venit deja în `v1`

Schimbările din noiembrie 2026 arată cum arată o adăugire: au intrat în /v1 fără să schimbe ce primește un client existent.

Schimbare	De ce nu rupe nimic
Formatul de eroare RFC 9457	vine doar când clientul trimite `Accept: application/problem+json`; câmpul `eroare` rămâne
Antetul `Idempotency-Key`	este opțional; fără el, ruta merge ca înainte
Cheile API	un mod nou de autentificare, alături de sesiune; cererile cu cookie merg ca înainte
Webhook-urile	rute noi (`/v1/webhookuri`); nimic nu se trimite până nu adaugă un Administrator o destinație

Cum te pregătești

Ignoră câmpurile pe care nu le cunoști în răspunsuri: pot apărea câmpuri noi oricând, fără o versiune nouă.
Nu te baza pe ordinea câmpurilor dintr-un răspuns JSON.
Compară erorile după cod, nu după textul mesajului: în formatul RFC 9457, câmpul cod este stabil.
Urmărește Noutăți pentru anunțuri.

A fost utilă pagina?