> ## 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.

# Editarea

> JSON Merge Patch, versiunile cu ETag și If-Match, și actualizarea după id-ul tău.

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.

```bash theme={null}
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`.

<Warning>
  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.
</Warning>

## 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.

1. Când citești anunțul, primești versiunea în antetul `ETag` și în câmpul `etag`.
2. Când editezi, o trimiți înapoi în antetul `If-Match`.
3. 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.

```json theme={null}
{
  "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`.

<Tip>
  `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”.
</Tip>

## `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:

```http theme={null}
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:

```json theme={null}
{
  "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](/ro/vocabulary).

## 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ă.


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