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

# Identificatori

> Codul Housera, id-ul tău, cheia de idempotență și reconcilierea.

Un anunț are două identități: codul pe care i-l dă Housera și, opțional, id-ul din sistemul tău. Le poți folosi pe amândouă.

## `code`, codul Housera

Fiecare anunț primește la creare un cod public de 8 caractere, de exemplu `HEWPUTA8`. E același cod care apare în adresa anunțului de pe site și nu se schimbă niciodată.

Îl folosești în toate rutele care se referă la un anunț anume:

```http theme={null}
GET    /account/listings/HEWPUTA8
PATCH  /listings/HEWPUTA8
POST   /listings/HEWPUTA8/pause
PUT    /listings/HEWPUTA8/photos
```

Codul nu ține cont de majuscule: `hewputa8` și `HEWPUTA8` duc la același anunț. În răspunsuri vine mereu cu majuscule.

## `external_ref`, id-ul tău

Dacă sistemul tău are deja un id pentru fiecare proprietate, nu e nevoie să păstrezi și codul Housera. Publici și actualizezi direct după id-ul tău:

```http theme={null}
PUT /listings/ref/CRM-10293
```

* **Prima dată** când trimiți un id, anunțul se creează, ca la `POST /listings`, și primești `201`.
* **Următoarele dăți**, corpul se aplică pe anunțul existent, ca o editare. Vezi [Editarea](/ro/concepts/editing).
* **Citirea** după id-ul tău: `GET /account/listings/ref/CRM-10293`.

Id-ul apare în fiecare anunț și în fiecare eveniment, în câmpul `external_ref` (`null` pentru anunțurile create altfel decât prin `PUT /listings/ref/{ref}`).

Reguli pentru id:

* între 1 și 100 de caractere: litere, cifre și `.` `_` `:` `/` `-`;
* e unic **în agenția ta** (sau în contul tău, dacă nu faci parte dintr-o agenție). Două agenții diferite pot folosi amândouă `123` fără conflict;
* un id cu alte caractere primește `404`.

<Tip>
  Folosește un id care nu se schimbă niciodată în sistemul tău, nu un număr de ordine dintr-o listă. Dacă id-ul se schimbă, Housera vede un anunț nou.
</Tip>

## `Idempotency-Key`, cererile repetate

O rețea instabilă poate pierde răspunsul unei cereri care a reușit. Dacă repeți orbește un `POST /listings`, riști două anunțuri identice. Antetul `Idempotency-Key` previne asta:

```http theme={null}
POST /listings
Idempotency-Key: 6f1c2b0e-8a4d-4c3e-9b7a-2d5f1e0c9a11
```

* O cerere repetată cu aceeași cheie, în următoarele **10 minute**, întoarce anunțul creat de prima, fără să creeze altul.
* Cheia e a contului tău: altcineva care folosește aceeași valoare nu-ți atinge anunțurile.
* Lungimea maximă e de 64 de caractere. Un UUID generat pentru fiecare anunț nou e alegerea potrivită.
* Generezi cheia **o dată per operație** și o refolosești doar la reîncercările acelei operații.

`PUT /listings/ref/{ref}` nu are nevoie de `Idempotency-Key`: id-ul tău joacă deja acest rol. Același id trimis de două ori nu creează niciodată două anunțuri.

## Reconcilierea

Webhook-urile și evenimentele îți spun ce s-a schimbat. O dată pe zi merită totuși să compari tot ce ai cu ce e pe Housera, ca să prinzi orice diferență. `GET /account/listings` acceptă parametrul `fields`, care îți întoarce doar câmpurile de comparat:

```bash theme={null}
curl "https://housera.ro/api/v1/account/listings?fields=code,external_ref,etag,updated_at,status&per_page=100" \
  -H "Authorization: Bearer $HOUSERA_KEY" \
  -H "Accept: application/json"
```

```json theme={null}
{
  "data": [
    { "code": "HEWPUTA8", "external_ref": "CRM-10293", "etag": "\"9b2f6c1e4a7d3b8f0c5e2a1d6f4b7c9e\"", "updated_at": "2026-10-19T09:12:44+03:00", "status": "active" },
    { "code": "K7RM2QXP", "external_ref": "CRM-10301", "etag": "\"41d8cd98f00b204e9800998ecf8427e1\"", "updated_at": "2026-10-19T09:40:03+03:00", "status": "pending" }
  ],
  "links": { "first": null, "last": null, "prev": null, "next": "https://housera.ro/api/v1/account/listings?cursor=eyJ1cGRhdGVkX2F0Ijoi..." },
  "meta": { "path": "https://housera.ro/api/v1/account/listings", "per_page": 100, "next_cursor": "eyJ1cGRhdGVkX2F0Ijoi...", "prev_cursor": null }
}
```

* Lista conține anunțurile tale în **orice stare** (iar dacă ești owner sau admin al agenției, și pe ale colegilor), ordonate după `updated_at`.
* Mergi la pagina următoare cu `cursor` din `meta.next_cursor`, până când acesta e `null`.
* `per_page` merge de la 1 la 100 (implicit 50). Poți filtra după stare cu `status`, de exemplu `status=active`.

Ce compari:

* **un `etag` diferit** de cel pe care îl știi înseamnă că anunțul s-a schimbat pe Housera (o editare în portal, o moderare): îl citești întreg cu `GET /account/listings/{code}`;
* **un anunț care lipsește** din listă a fost șters;
* **un `external_ref` pe care nu-l găsești** pe Housera înseamnă că anunțul n-a ajuns: îl trimiți din nou cu `PUT /listings/ref/{ref}`.


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