Agențiile partenere

O agenție poate vinde apartamente sau case din ansamblul unui dezvoltator. Publică fiecare unitate drept anunț propriu și o leagă de ansamblu, iar unitatea apare pe pagina ansamblului, lângă unitățile dezvoltatorului. Anunțul rămâne al agenției: cererile clienților ajung la agenție, iar dezvoltatorul vede doar câte au fost, fără datele de contact.

Parteneriatul

Parteneriatul se cere și se decide din portalul Housera sau prin API, cu aceleași reguli. Fiecare parte primește notificarea din portal și evenimentul partnership.* care o privește.

Agenția cere

Titularul sau un administrator al agenției cere parteneriatul, cu un mesaj opțional. Cererea se poate face pentru ansamblul activ al oricărei firme aprobate care are un titular sau un administrator.

Firma ansamblului decide

Titularul, un administrator sau managerul proiectului din firma ansamblului aprobă ori respinge cererea. Firma ansamblului e dezvoltatorul sau agenția care comercializează ansamblul cu mandat. Cât timp nu s-a decis, agenția își poate retrage cererea.

Agenția leagă unitățile

După aprobare, oricare membru al agenției leagă unități de ansamblu, din portal sau prin API.

Parteneriatele prin API

Citirea cere dreptul listings:read, iar cererea și deciziile cer listings:write. GET /account/partnerships întoarce parteneriatele firmei cheii, cele mai noi primele, pe ambele părți: cele cerute de agenția ta (side: agency) și cele de pe ansamblurile firmei tale (side: developer). Le poți restrânge cu side, cu status și cu complex, codul ansamblului. id-ul unui parteneriat e cel din evenimentele partnership.*. Parteneriatele cerute de agenție le citește orice membru al firmei. Pe cele de pe ansambluri le citesc doar proprietarul firmei, administratorii și managerul proiectului, pentru proiectele lui. Pentru ceilalți membri, lista nu le cuprinde.

{
  "data": [
    {
      "id": 42, "side": "agency", "status": "approved", "note": "Avem clienți pentru două camere.",
      "created_at": "2026-11-04T09:12:00+00:00", "decided_at": "2026-11-04T11:30:00+00:00", "ended_at": null,
      "complex": { "code": "HEWPUTA8", "title": "Copou Park", "url": "https://housera.ro/anunt/hewputa8/iasi/copou-park" },
      "developer": { "name": "Dezvoltator Nord" }, "agency": { "name": "Casa Bună" },
      "units": { "linked": 3, "active": 2 }, "leads": null
    }
  ]
}

status e pending, approved, rejected, withdrawn, revoked sau ended. note e mesajul agenției. Când dezvoltatorul respinge sau revocă cu un motiv, note devine motivul lui. units numără anunțurile agenției legate de ansamblu. leads e numărul cererilor de clienți aduse de ele și apare doar pe partea dezvoltatorului. Datele clienților rămân la agenție.

Partea agenției

Cu cheia titularului sau a unui administrator al agenției:

GET /partnerships/developments?q=copou caută ansamblurile pentru care poți cere, după nume (cel puțin 2 caractere, cel mult 20 de rezultate). Fiecare rezultat are code, title, url, localitatea, dezvoltatorul și, în partnership, cererea sau parteneriatul pe care îl ai deja.
POST /partnerships cere parteneriatul, cu complex (codul ansamblului) și un note opțional, de cel mult 500 de caractere. Răspunsul e 201, cu parteneriatul în pending.
POST /partnerships/{id}/withdraw retrage o cerere care încă așteaptă.

O cerere refuzată primește 409, cu motivul în code: partnership_unavailable (ansamblul nu primește cereri acum sau e chiar al firmei tale), partnership_already_open (ai deja o cerere în așteptare), partnership_already_partner (ești deja partener), partnership_paused (dezvoltatorul ți-a respins recent mai multe cereri; încearcă mai târziu) sau partnership_too_many (ai prea multe cereri în așteptare). Un cod de ansamblu necunoscut primește 422 complex_not_found.

Partea dezvoltatorului

Cu cheia titularului, a unui administrator sau a managerului proiectului:

POST /partnerships/{id}/approve aprobă cererea.
POST /partnerships/{id}/reject respinge cererea, cu un note opțional pe care agenția îl citește.
POST /partnerships/{id}/revoke încheie un parteneriat aprobat. Toate unitățile agenției ies din ansamblu și rămân publicate ca anunțuri obișnuite. Revocarea nu se poate anula. De aceea, ca în portal, o confirmi cu numele agenției în confirm, scris exact ca în agency.name. Un alt nume primește 422 partnership_confirm_mismatch pe /confirm.

curl -X POST "https://housera.ro/api/v1/partnerships/42/revoke" \
  -H "Authorization: Bearer $HOUSERA_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "confirm": "Casa Bună", "note": "Încheiem colaborarea pe acest proiect." }'

Fiecare acțiune răspunde cu parteneriatul actualizat. Dacă între timp s-a răspuns la cerere sau parteneriatul s-a încheiat, primești 409 partnership_closed. La aprobare, 409 partnership_unavailable înseamnă că ansamblul nu mai e activ sau agenția nu mai e aprobată. Cine nu poate decide pe acel parteneriat primește 404. Unitățile unui partener le scoți una câte una din proiect.

Legarea prin API

Cu cheia agenției trimiți complex, codul ansamblului, și unit_ref, identificatorul unității, la POST /listings, PUT /listings/ref/{ref} sau PATCH /listings/{code}. La unitatea unei agenții partenere, unit_ref e obligatoriu: fără el primești unit_ref_required pe /unit_ref.

curl -X PATCH "https://housera.ro/api/v1/listings/K3TQ8WZA" \
  -H "Authorization: Bearer $HOUSERA_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "complex": "HEWPUTA8", "unit_ref": "B2-14" }'

Răspunsul arată legătura în complex, cu linked_by: "partner", și identificatorul normalizat în unit_ref. Pe un anunț activ, o cerere care schimbă doar legătura primește 200: legătura se aplică pe loc și nimic nu ajunge la moderare. Fără parteneriat aprobat, ansamblul altei firme răspunde complex_not_linkable, iar un ansamblu pe care cheia nu îl vede, complex_not_found. Regulile complete sunt în Unitățile ansamblului. Cheia leagă în firma ei, firma contului care a făcut-o. Vezi Ce anunțuri vede fiecare cheie.

Anunțurile importate dintr-un CRM

Anunțurile pe care Housera le preia din CRM-ul agenției se editează doar în CRM. Legătura cu un ansamblu și unit_ref nu țin însă de conținutul anunțului. Le schimbi prin API cu un PATCH /listings/{code} care trimite doar complex și unit_ref, ca Leagă de ansamblu din portal:

curl -X PATCH "https://housera.ro/api/v1/listings/R7MXQ2PL" \
  -H "Authorization: Bearer $HOUSERA_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "complex": "HEWPUTA8", "unit_ref": "B2-14" }'

Legătura se aplică pe loc, cu aceleași reguli ca pe un anunț publicat direct, și răspunsul e 200 cu anunțul. Importurile următoare nu o ating. Un PATCH care trimite și alt câmp primește 403 forbidden și nu se salvează nimic. Dacă legătura vine din import, ea și unit_ref se schimbă doar din CRM: primești 422 complex_link_from_import. Vezi Pentru CRM-uri.

Ce vede cheia agenției

Cheia agenției nu citește ansamblul dezvoltatorului și nici inventarul lui. GET /listings și GET /listings/{code} fac parte din catalogul platformei și cer dreptul catalog:read, deci primești 403 missing_ability. GET /account/listings/{code} întoarce doar anunțurile agenției, așa că pe codul ansamblului răspunde 404. Agenția își citește unitățile pe care le-a legat, cu GET /account/listings?complex={code}. Fiecare unitate are câmpul complex, cu code, title, url și linked_by. Codul ansamblului îl afli din GET /partnerships/developments, din GET /account/partnerships sau din portal, unde e în adresa paginii ansamblului, imediat după /anunt/. În https://housera.ro/anunt/hewputa8/iasi/..., codul e hewputa8. API-ul îl acceptă cu litere mici sau mari.

Scoaterea din ansamblu

O unitate iese din ansamblu în cinci feluri:

agenția trimite complex: null sau o scoate din portal;
dezvoltatorul scoate unitatea din ansamblu, din portal sau prin API;
dezvoltatorul revocă parteneriatul, din portal sau prin API, iar toate unitățile agenției ies din ansamblu;
Housera încheie parteneriatul de exemplu fiindcă ansamblul nu mai e activ;
mandatul agenției care comercializa ansamblul s-a încheiat: dezvoltatorul l-a revocat sau a preluat ansamblul și a scos unitățile agenției (reason: mandate_revoked).

Anunțul rămâne publicat și își pierde doar legătura și unit_ref-ul. În afară de cazul în care chiar tu ai trimis complex: null, primești listing.complex_unlinked, cu motivul în reason și noul etag.

Webhook-urile

Eveniment	Cine îl primește
`partnership.requested`	firma ansamblului
`partnership.withdrawn`	firma ansamblului
`partnership.approved`, `partnership.rejected`	agenția
`partnership.revoked`, `partnership.ended`	agenția și firma ansamblului
`listing.complex_linked`, `listing.complex_unlinked`	firma care a publicat unitatea
`complex.mandate_confirmed`, `complex.mandate_ended`	agenția care comercializează ansamblul
`complex.taken_over`	agenția și dezvoltatorul

Evenimentele parteneriatului ajung la titularul și administratorii firmei, prin cheile legate de acea firmă și cu dreptul listings:read. Forma lor e în Webhook-uri.

Început

Concepte

Ghiduri

Referință

Mai multe