# 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](#note-versiune), 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](#api-erori--formatul-rfc-9457-la-cerere) | vine doar când clientul trimite `Accept: application/problem+json`; câmpul `eroare` rămâne |
| [Antetul `Idempotency-Key`](#idempotenta) | este opțional; fără el, ruta merge ca înainte |
| [Cheile API](#chei-api) | un mod nou de autentificare, alături de sesiune; cererile cu cookie merg ca înainte |
| [Webhook-urile](#webhook-uri) | 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](#note-versiune) pentru anunțuri.