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

# Agențiile partenere

> Cum vinde o agenție unitățile din ansamblul unui dezvoltator: parteneriatul, legarea prin API și ce se întâmplă când parteneriatul se încheie.

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.

**1. 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.

**2. 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.

**3. 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.

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

```bash theme={null}
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](https://api.housera.ro/ro/guides/projects.md#scoaterea-unei-unități-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`.

```bash theme={null}
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](https://api.housera.ro/ro/guides/complex.md#unitățile-ansamblului).

Cheia leagă în firma ei, firma contului care a făcut-o. Vezi [Ce anunțuri vede fiecare cheie](https://api.housera.ro/ro/concepts/access.md).

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

```bash theme={null}
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](https://api.housera.ro/ro/crm.md#ansamblurile).

## 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](https://api.housera.ro/ro/webhooks.md).


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