Salt la conținutul principal

​
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, 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.