Proiectele dezvoltatorului

Pentru o firmă de dezvoltator, fiecare ansamblu rezidențial e un proiect, cu biroul lui de vânzări și cu echipa lui. Prin API citești proiectele și unitățile lor, le schimbi biroul de vânzări și echipa și scoți din proiect unitățile partenerilor, cu regulile paginii Proiecte din contul firmei. Citirea cere dreptul listings:read, iar schimbările cer listings:write. Unitățile și ansamblul însuși se editează ca orice anunț, prin PATCH /listings/{code}. Ce vede cheia depinde de rolul contului în firmă:

Rol	Ce poate face
titularul sau un administrator	vede toate proiectele, le schimbă biroul de vânzări, alege echipa și scoate unitățile agențiilor partenere
managerul unui proiect	vede proiectele pe care lucrează, le schimbă biroul de vânzări și scoate unitățile partenerilor
agentul	vede proiectele pe care lucrează

Un proiect pe care contul nu îl vede răspunde 404, la fel ca unul care nu există. O agenție are proiecte doar când comercializează ansambluri sub mandat (vezi Proiectele unei agenții); altfel lista vine goală.

Proiectele

GET /account/projects întoarce proiectele pe care le vede cheia, cu paginare prin cursor. Ca în lista din portal, q caută în titlu, în stradă și în zonă, iar stage păstrează doar un stadiu. GET /account/projects/{code} întoarce un proiect după codul ansamblului:

{
  "data": {
    "code": "HEWPUTA8",
    "title": "Copou Park",
    "url": "https://housera.ro/anunt/hewputa8/iasi/copou-park",
    "status": "active",
    "stage": "under_construction",
    "address": "Str. Copou 12, Copou, Iași",
    "delivery": { "quarter": 4, "year": 2027 },
    "price_from": { "amount": 89000, "currency": "EUR" },
    "partners": { "active": 3, "pending": 1 },
    "requests": { "total": 27, "unassigned": 4 },
    "manages": true,
    "sales_office": {
      "address": "Bd. Carol I 1, Iași",
      "phone": "+40740123456",
      "email": "vanzari@exemplu.ro",
      "opening_hours": { "mon": { "from": "09:00", "to": "18:00" } }
    },
    "team": [
      { "name": "Andrei Ionescu", "email": "andrei@exemplu.ro", "role": "owner", "all_projects": true },
      { "name": "Maria Popa", "email": "maria@exemplu.ro", "role": "manager", "all_projects": false }
    ],
    "units": { "available": 42, "reserved": 3, "sold": 12 }
  }
}

manages spune dacă contul cheii conduce proiectul, adică dacă îi poate schimba biroul de vânzări și scoate unitățile partenerilor.
team începe cu titularul și administratorii, care sunt pe toate proiectele (all_projects: true), apoi colegii aleși pentru proiect.
team[].email îl primesc doar cheile titularului, ale administratorilor și ale managerilor, ca pe pagina Echipa din portal. Un manager primește emailurile colegilor de pe proiectele lui, nu și pe ale titularului și administratorilor. Cheia unui agent primește doar emailul lui, iar la colegi email e null.
units numără unitățile publice ale proiectului, ca pe pagina ansamblului.
partners și requests sunt coloanele din lista Proiecte: parteneriatele active și cererile de parteneriat care așteaptă, apoi cererile clienților și câte dintre ele n-a preluat nimeni. Sunt doar cifre; cererile le citești cu leads:read (vezi Cererile clienților).

Proiectele unei agenții

O agenție care comercializează un ansamblu sub un mandat cerut sau confirmat îl are în Proiecte, ca în portal. Lista o văd doar titularul și administratorii agenției, care și conduc aceste proiecte. Cheia unui manager sau a unui agent al agenției primește lista goală. Pe proiectul unei agenții:

manages e true: titularul și administratorii schimbă biroul de vânzări, citesc unitățile și scot unitățile partenerilor, la fel ca la un dezvoltator;
mandate arată mandatul deschis: status (requested sau confirmed), decided_via (developer, moderator sau legacy), valid_until (sfârșitul contractului) și renewal_pending (un contract nou așteaptă confirmarea dezvoltatorului);
developer e dezvoltatorul ansamblului, ca pe anunț;
echipa proiectului o alege dezvoltatorul, deci PATCH /projects/{code} cu team primește 403 forbidden;
viewings e null.

Pe proiectele unui dezvoltator, mandate e null.

Biroul de vânzări și echipa

PATCH /projects/{code} schimbă câmpurile pe care le trimiți. Un câmp trimis cu null se golește.

{
  "address": "Bd. Carol I 1, Iași",
  "phone": "0740123456",
  "email": "vanzari@exemplu.ro",
  "opening_hours": { "mon": { "from": "09:00", "to": "18:00" }, "sat": { "from": "10:00", "to": "14:00" } }
}

opening_hours are câte un interval pe zi, pentru zilele de la mon la sun. O zi lipsă sau cu null e închisă. from vine înainte de to, iar 24:00 înseamnă sfârșitul zilei. Telefonul se salvează în format internațional. Echipa o alegi trimițând emailurile colegilor, doar cu cheia titularului sau a unui administrator:

{ "team": ["maria@exemplu.ro", "dan@exemplu.ro"] }

Lista înlocuiește echipa proiectului. Un email care nu e al unui coleg care lucrează acum în firmă primește team_not_member, pe poziția lui din listă (/team/1), și nu se salvează nimic. Cheia unui manager care trimite team primește 403 forbidden. Răspunsul conține proiectul actualizat.

Unitățile proiectului

GET /account/projects/{code}/units întoarce toate anunțurile legate de proiect, doar pentru cine conduce proiectul. Unitățile firmei vin în orice stare, iar ale agențiilor partenere vin după ce ies din ciornă. publisher=firm sau publisher=partner le restrânge după cine le-a publicat, publisher=<id> la o singură agenție parteneră, iar status după stare.

{
  "data": [
    {
      "code": "K3TQ8WZA", "title": "Apartament 2 camere, B2-14", "type": "apartment", "transaction": "sale",
      "status": "active", "reserved": false, "unit_ref": "B2-14", "price": 96000, "currency": "EUR",
      "subtype": "standard", "rooms": 2, "unit_kind": "apartment",
      "linked_by": "partner", "publisher": { "own": false, "name": "Casa Bună", "agency_id": 318 },
      "url": "https://housera.ro/anunt/k3tq8wza/iasi/apartament-2-camere"
    }
  ]
}

linked_by spune cine a legat unitatea: firm (firma ta), partner (o agenție parteneră) sau import (feed-ul unui CRM). unit_kind e tipul unității în matricea ansamblului, cu aceleași coduri ca unit_types[].kind pe ansamblu. publisher.agency_id e id-ul firmei care a publicat unitatea, același cu agency.id din GET /account/partnerships. Numele unei firme se poate schimba, id-ul nu, așa că după el grupezi unitățile pe agenții.

Scoaterea unei unități din proiect

POST /projects/{code}/units/{unit}/detach scoate din proiect unitatea unei agenții partenere, ca butonul Scoate din proiect din portal. {unit} e codul anunțului. Răspunsul e 204. Anunțul rămâne publicat ca anunț obișnuit și își pierde unit_ref-ul. Agenția primește o notificare și evenimentul listing.complex_unlinked, cu reason: developer_removed. Cât timp parteneriatul durează, agenția poate lega unitatea din nou. Doar unitățile cu linked_by: partner se scot așa. Pe o unitate a firmei tale, sau pe una care nu mai e în proiect, primești 404. Unitățile firmei le scoți editând anunțul, cu complex: null. Vezi Agențiile partenere.

Vizionările proiectului

Fiecare proiect are câmpul viewings, null la o firmă care nu e dezvoltator:

"viewings": {
  "offer": { "places": [ { "place": "office", "rooms": null }, { "place": "show_flat", "rooms": null } ],
             "open_house": false, "site_visit": true, "flat_viewings": false, "needs_start": false },
  "flat_viewings_started_at": null,
  "consultants": [ { "name": "Maria Popa", "email": "maria@exemplu.ro", "role": "manager" } ],
  "next_viewing": "2026-11-13T08:00:00+00:00",
  "next_open_house": "2026-11-15T08:00:00+00:00"
}

Stadiul decide ce pot programa clienții (offer), ca în portal:

Stadiu	Unde se văd clienții (`places`)	Open house
Lansare sau fără stadiu	la biroul de vânzări (`office`)	doar zi de vizită cu locuri (`site_visit: true`)
În construcție	la birou sau la apartamentul-martor (`show_flat`)	doar zi de vizită cu locuri (`site_visit: true`)
Finalizat	la birou, până pornești vizionările la apartamente (`needs_start: true`); apoi la apartamente (`unit`), câte o alegere pentru fiecare număr de camere (`rooms`)	da
Mixt	la apartamente și la birou	da

O zi de vizită cu locuri se publică prin POST /listings/{code}/open-house, cu capacity pe fereastră. Vezi Open house. consultants sunt colegii aleși în echipa proiectului care lucrează acum în firmă, managerii întâi. Ei se întâlnesc cu clienții, iar o oră liberă are câte un loc pentru fiecare. Echipa o alegi cu PATCH /projects/{code} (team). Când lista e goală, vizionările le face cel care conduce anunțul. next_viewing e următoarea vizionare rezervată sau cerută la ansamblu, iar next_open_house următorul open house al ansamblului care n-a trecut. Vizionările la apartamente le citești pe fiecare unitate.

Pornirea vizionărilor la apartamente

POST /projects/{code}/flat-viewings pornește vizionările la apartamentele unui proiect Finalizat, ca butonul „Pornește vizionările” din portal. Apartamentele primesc ore din programul lor, iar clienții aleg un apartament de văzut în loc de o întâlnire la birou. Răspunsul e proiectul, cu viewings.flat_viewings_started_at completat. A doua cerere nu mai schimbă nimic. Le pornește titularul, un administrator sau managerul proiectului; pentru oricine altcineva proiectul nu există (404). Un proiect care nu e Finalizat primește 422 stage_not_finished pe /stage.

Raportul proiectului

GET /account/projects/{code}/viewing-report dă raportul vizionărilor din ultimele 14 zile, pentru ansamblu și unitățile lui împreună, doar celui care conduce proiectul:

{ "data": { "from": "2026-10-29", "to": "2026-11-12",
  "funnel": { "bookings": 31, "came": 19, "again": 6, "offers": 2 },
  "consultants": [ { "name": "Maria Popa", "bookings": 18, "came": 12, "offers": 1 } ] } }

Raportul nu are numele clienților. Consultanții apar cu numele lor de echipă. open_houses adaugă, ca în portal, open house-urile și zilele de vizită din perioadă, cu code (anunțul), came și interested; pâlnia numără doar vizionările programate.

Început

Concepte

Ghiduri

Referință

Mai multe