Editarea

Editezi un anunț cu PATCH /listings/{code} sau, dacă lucrezi cu id-urile tale, cu PUT /listings/ref/{ref}. Ambele trimit doar ce s-a schimbat și ambele te feresc să suprascrii o modificare făcută între timp în portal.

JSON Merge Patch

Corpul unui PATCH urmează regulile JSON Merge Patch (RFC 7386):

un câmp trimis își înlocuiește valoarea;
un câmp trimis cu null se golește;
un câmp netrimis rămâne cum era.

curl -X PATCH https://housera.ro/api/v1/listings/HEWPUTA8 \
  -H "Authorization: Bearer $HOUSERA_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H 'If-Match: "9b2f6c1e4a7d3b8f0c5e2a1d6f4b7c9e"' \
  -d '{ "price": 94500, "negotiable": false, "year_built": null }'

Aici prețul devine 94.500 EUR, anunțul nu mai e negociabil, anul construcției se golește, iar restul rămâne neatins. Listele (features, heating_types, orientations) se înlocuiesc în întregime. Ca să adaugi o dotare, trimiți lista completă, cu dotarea nouă inclusă. După combinare, anunțul rezultat trece prin aceleași reguli ca o editare din formular. Un PATCH nu poate goli un câmp obligatoriu: {"street": null} primește 422 cu required pe /street.

Tipul (type) și tranzacția (transaction) unui anunț nu se schimbă după creare. Un apartament de vânzare scos la închiriat e un anunț nou.

Ce răspuns primești

Starea anunțului	Ce se întâmplă	Status
`pending`	Modificarea se aplică pe loc, anunțul rămâne în moderare.	`200`
`rejected` sau `draft`	Modificarea se aplică și anunțul e (re)trimis la moderare: devine `pending`.	`200`
`active`, `paused`, `unconfirmed`	Versiunea publică rămâne, modificarea așteaptă moderarea (`moderation.edit_pending: true`).	`202`
`sold`, `hidden`	Anunțul nu se mai editează.	`404`

Corpul răspunsului e anunțul, plus warnings[] (vezi mai jos). La 202, anunțul din răspuns are încă valorile publice: modificarea ta se vede după aprobare.

Versiunile: `ETag` și `If-Match`

Un anunț trimis prin API rămâne editabil și din portal: agentul poate corecta un preț direct pe housera.ro. Ca o sincronizare automată să nu șteargă pe tăcute o astfel de corectură, fiecare anunț are o versiune.

Când citești anunțul, primești versiunea în antetul ETag și în câmpul etag.
Când editezi, o trimiți înapoi în antetul If-Match.
Dacă anunțul s-a schimbat între timp (o editare în portal, o altă cerere), primești 412 Precondition Failed și nu se scrie nimic.

{
  "type": "https://housera.ro/problems/listing_changed_meanwhile",
  "title": "Anunțul a fost modificat între timp, din altă parte. Redeschide-l ca să vezi versiunea curentă — altfel ai suprascrie modificarea celuilalt.",
  "status": 412,
  "code": "listing_changed_meanwhile",
  "detail": "Anunțul a fost modificat între timp, din altă parte. Redeschide-l ca să vezi versiunea curentă — altfel ai suprascrie modificarea celuilalt."
}

La 412, citești din nou anunțul (GET /account/listings/{code}), decizi ce versiune câștigă și retrimiți cu noul ETag. Versiunea se schimbă când se schimbă conținutul anunțului, inclusiv o editare care așteaptă moderarea. Când cineva editează anunțul în portal, primești și webhook-ul listing.edited_in_portal, cu noul etag.

If-Match e opțional. Fără el, editarea se aplică peste orice versiune. Îl recomandăm pentru orice sincronizare automată: e diferența dintre „am actualizat prețul” și „am șters corectura agentului”.

`PUT /listings/ref/{ref}` se aplică tot ca un patch

Pe un id pe care Housera îl cunoaște deja, PUT /listings/ref/{ref} nu înlocuiește anunțul întreg, ci se comportă ca un PATCH:

câmpurile pe care le trimiți se actualizează;
câmpurile pe care nu le trimiți își păstrează valoarea, nu se golesc niciodată;
un câmp trimis explicit cu null se golește;
If-Match e respectat la fel, cu 412 pe o versiune veche.

Așa, un CRM care nu cunoaște un câmp (de exemplu, unul adăugat ulterior în API) nu-l golește din greșeală la fiecare sincronizare.

Corp identic: `X-Housera-Unchanged`

Dacă trimiți la PUT /listings/ref/{ref} exact același corp ca la ultima scriere reușită, Housera nu scrie nimic și nu trimite nimic la moderare. Primești 200 cu anunțul curent și antetul:

X-Housera-Unchanged: true

Poți deci să-ți resincronizezi tot stocul fără grijă: doar anunțurile chiar schimbate ajung la moderare. Comparația se face pe octeții corpului, așa că păstrează aceeași ordine a câmpurilor și același format al numerelor de la o sincronizare la alta.

Avertismentele: `warnings[]`

Orice răspuns reușit la o scriere (POST, PUT, PATCH) conține lista warnings[], cu ce ai trimis și nu a fost luat:

{
  "data": { "code": "HEWPUTA8", "status": "pending" },
  "warnings": [
    { "pointer": "/deposit_months", "code": "not_for_transaction" },
    { "pointer": "/features/loading_dock", "code": "not_for_type" }
  ]
}

Cod	Ce înseamnă
`not_for_type`	Câmpul sau dotarea nu există pentru tipul anunțului (de exemplu, o rampă de încărcare la un apartament).
`not_for_transaction`	Câmpul nu există pentru tranzacție (de exemplu, garanția în luni la o vânzare).
`unknown_feature`	Codul de dotare nu e în catalog.

Un avertisment nu blochează scrierea, dar îți spune că maparea ta trimite ceva inutil. Lista câmpurilor și a dotărilor permise pentru fiecare tip și tranzacție e în vocabular.

Conflicte de concurență

Dacă două scrieri ajung în același timp pe același anunț, a doua poate primi 409 listing_busy. Nu s-a scris nimic: reîncerci după o secundă sau două.

Început

Concepte

Ghiduri

Referință

Mai departe

JSON Merge Patch

Ce răspuns primești

Versiunile: `ETag` și `If-Match`

`PUT /listings/ref/{ref}` se aplică tot ca un patch

Corp identic: `X-Housera-Unchanged`

Avertismentele: `warnings[]`

Conflicte de concurență

​JSON Merge Patch

​Ce răspuns primești

​Versiunile: ETag și If-Match

​PUT /listings/ref/{ref} se aplică tot ca un patch

​Corp identic: X-Housera-Unchanged

​Avertismentele: warnings[]

​Conflicte de concurență

JSON Merge Patch

Ce răspuns primești

Versiunile: `ETag` și `If-Match`

`PUT /listings/ref/{ref}` se aplică tot ca un patch

Corp identic: `X-Housera-Unchanged`

Avertismentele: `warnings[]`

Conflicte de concurență