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:
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:
- 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.
- 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.
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.
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:
- 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:
- 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}.
