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

# Proiectele dezvoltatorului

> Cum citești proiectele firmei, cum schimbi biroul de vânzări și echipa unui proiect și cum scoți din proiect unitatea unei agenții partenere.

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](#proiectele-unei-agentii)); 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:

```json theme={null}
{
  "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](https://api.housera.ro/ro/guides/leads.md)).

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

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

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

```json theme={null}
{
  "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](https://api.housera.ro/ro/guides/partners.md).

## Vizionările proiectului

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

```json theme={null}
"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](https://api.housera.ro/ro/guides/open-house.md#ziua-de-vizită-a-unui-proiect).

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

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


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