> ## Documentation Index
> Fetch the complete documentation index at: https://api.housera.ro/llms.txt
> Use this file to discover all available pages before exploring further.

# Versiuni și noutăți

> Cum evoluează API-ul fără să-ți strice integrarea, și ce s-a schimbat în fiecare versiune.

## Versionarea

Versiunea face parte din adresă: `/api/v1`. În interiorul unei versiuni, API-ul evoluează doar **compatibil**:

* **câmpurile se adaugă**, nu se redenumesc, nu dispar și nu își schimbă tipul;
* **endpointurile se adaugă**, cele existente își păstrează comportamentul;
* **codurile nu dispar niciodată**: un cod schimbat rămâne acceptat și apare în `retired` din [vocabular](/ro/vocabulary), cu succesorul lui;
* **valori noi** pot apărea în listele de coduri (un subtip, o dotare, un tip de eveniment).

Ca integrarea ta să reziste, ignoră câmpurile pe care nu le cunoști și tratează un cod necunoscut (de exemplu un tip de eveniment nou) fără să te oprești.

O schimbare incompatibilă înseamnă o versiune nouă, `/api/v2`, care rulează **în paralel** cu `/api/v1`. Retragerea unei versiuni se anunță cu **cel puțin 6 luni înainte**, pe pagina aceasta și prin antetele `Deprecation` și `Sunset` pe răspunsurile versiunii vechi.

## 1.0.0 — octombrie 2026

Prima versiune publică a API-ului de scriere.

**Anunțurile tale**

* Crearea (`POST /listings`, cu `Idempotency-Key`), validarea fără scriere (`POST /listings/validate`), editarea ca JSON Merge Patch (`PATCH /listings/{code}`) și ștergerea (`DELETE /listings/{code}`).
* Crearea sau actualizarea după id-ul tău: `PUT /listings/ref/{ref}` și `GET /account/listings/ref/{ref}`.
* Tranzițiile: `POST /listings/{code}/pause`, `/resume`, `/sold`.
* Lista și detaliul anunțurilor tale, în orice stare: `GET /account/listings` (cu `status`, `fields` pentru reconciliere și paginare prin cursor) și `GET /account/listings/{code}`.
* Versiunile anunțului cu `ETag` și `If-Match`, cu `412` pe o versiune veche.
* Avertismentele `warnings[]` pentru câmpurile și dotările care nu există pentru tip și tranzacție.

**Pozele**

* Lista completă a pozelor, din URL-uri sau din uploaduri directe: `PUT /listings/{code}/photos`.
* Upload direct prin URL presemnat: `POST /uploads`.

**Evenimente și webhook-uri**

* Webhook-uri semnate după Standard Webhooks, configurabile din Setări → API, cu test, rotirea secretului și jurnalul livrărilor.
* Evenimentele `listing.published`, `listing.rejected`, `listing.paused`, `listing.reactivated`, `listing.sold`, `listing.withdrawn`, `listing.edited_in_portal`, `media.failed`, `webhook.test`.
* Recuperarea evenimentelor din ultimele 35 de zile: `GET /events`.

**Erori, chei și jurnal**

* Erori în format RFC 9457, cu coduri stabile pe fiecare câmp.
* Chei create din cont, cu drepturi (`listings:read`, `listings:write`, `media:write`), prefixe `hsr_test_` și `hsr_live_` și expirare obligatorie.
* Jurnalul API în Setări → API → Jurnal, cu `X-Request-Id` pe fiecare răspuns.
* Sandbox pe `https://staging.housera.ro/api/v1`.

**Citire și vocabular**

* Catalogul public de anunțuri active: `GET /listings` și `GET /listings/{code}`.
* Vocabularul public, cu tipul și unitatea fiecărui câmp: `GET /schema`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.