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

# Mandatele de comercializare

> Cum citești mandatele de comercializare ale firmei, ca agenție sau ca dezvoltator, și ce evenimente primești când un mandat îți cere un pas.

Un ansamblu rezidențial publicat de o agenție are nevoie de un mandat de comercializare confirmat de dezvoltator. Prin API citești mandatele firmei tale, cu aceleași reguli ca ecranul Mandate din portal: agenția vede mandatele pe care le-a cerut, iar dezvoltatorul pe cele care îl numesc, inclusiv ansamblurile lui comercializate de o agenție.

Prin API doar citești. Declararea mandatului cu contractul, confirmarea, refuzul, verificarea unei reînnoiri, revocarea și preluarea ansamblului se fac în portal. Contractul nu se citește prin API. Când un mandat îți cere un pas, primești un eveniment (vezi [Evenimentele mandatelor](#evenimentele-mandatelor)).

Mandatele le citesc doar titularul și administratorii firmei, cu o cheie legată de firmă care are dreptul `listings:read`. Altă cheie primește `403 forbidden` la listă și `404` la un mandat.

## Lista mandatelor

`GET /account/mandates` întoarce mandatele firmei, cu paginare prin cursor, de la cel mai vechi. Cu `status` primești doar mandatele în așteptare (`requested`), pe cele confirmate (`confirmed`) sau istoricul (`closed`: refuzate, retrase, revocate și expirate).

```json theme={null}
{
  "data": [
    {
      "id": 812,
      "side": "agency",
      "status": "confirmed",
      "step": "confirmed",
      "legacy": false,
      "complex": { "code": "K7Q2M9PA", "title": "Copou Park", "url": "https://housera.ro/anunt/k7q2m9pa/iasi/copou-park" },
      "agency": { "id": 47, "name": "Casa Bună" },
      "developer": { "name": "Construct Nord", "legal_name": "Construct Nord SRL", "tax_id": "87654321", "on_platform": true },
      "valid_until": "2027-06-30",
      "decided_via": "developer",
      "created_at": "2026-10-02T08:00:00+00:00",
      "decided_at": "2026-10-03T11:20:00+00:00",
      "ended_at": null
    }
  ],
  "meta": { "next_cursor": null }
}
```

`GET /account/mandates/{id}` întoarce un singur mandat, în aceeași formă. Un mandat pe care cheia nu îl vede primește `404`, ca unul care nu există.

| Câmp | Ce conține |
| - | - |
| `side` | De ce parte e firma ta: `agency` (agenția care comercializează ansamblul) sau `developer` (dezvoltatorul lui). |
| `status` | `requested` (în așteptare), `confirmed`, `refused`, `withdrawn` (retras de agenție), `revoked` sau `expired`. |
| `step` | Unde a ajuns mandatul acum (vezi mai jos). |
| `legacy` | `true` pentru un mandat de dinainte de regulile de acum, pe care agenția trebuie să-l declare cu dezvoltatorul și contractul. |
| `complex` | Ansamblul, cu `code`, `title` și `url`. |
| `agency` | Agenția care comercializează ansamblul, cu `id` și `name`. |
| `developer` | Dezvoltatorul: `name`, denumirea din registru, codul fiscal (doar la o persoană juridică verificată în registru, altfel `null`) și `on_platform`, `true` când dezvoltatorul are firma lui pe Housera și decide el cererea. |
| `valid_until` | Ziua în care se încheie contractul. `null` dacă nu are o dată de sfârșit. |
| `decided_via` | Cine a decis: `developer`, `moderator` (moderarea Housera) sau `legacy`. `null` cât timp cererea așteaptă. |
| `decided_at`, `ended_at` | Când a fost confirmat sau refuzat mandatul și când s-a încheiat. |

Valorile lui `step`:

* `awaiting_developer`: cererea așteaptă răspunsul dezvoltatorului;
* `awaiting_moderation`: cererea o decide moderarea Housera, de exemplu fiindcă dezvoltatorul nu e pe Housera sau n-a răspuns la timp;
* `better_contract_requested`: agenției i s-a cerut un contract mai bun;
* `to_declare`: un mandat de dinainte, pe care agenția trebuie să-l declare;
* `renewal_to_check`: agenția a trimis un contract reînnoit, pe care dezvoltatorul trebuie să-l verifice;
* `confirmed`: mandatul e confirmat și nu așteaptă nimic;
* `ended`: mandatul s-a încheiat.

## Evenimentele mandatelor

Când un mandat îți cere un pas, primești un eveniment, pe webhook și în `GET /events`. Pornesc din portal, de la moderarea Housera sau de la verificarea zilnică a termenelor, la fel ca notificările pe care le primesc titularul și administratorii.

| Eveniment | Cine îl primește | Când | Câmpuri în plus în `data` |
| - | - | - | - |
| `complex.mandate_requested` | dezvoltatorul | O agenție a cerut mandatul pe un ansamblu al lui. | `agency` (`id`, `name`) |
| `complex.mandate_withdrawn` | dezvoltatorul | Agenția și-a retras cererea. | – |
| `complex.mandate_renewal_due` | dezvoltatorul | Agenția a trimis un contract reînnoit, de verificat. | – |
| `complex.mandate_expiring` | agenția | Contractul se încheie în curând: cu 30 de zile și apoi cu 7 zile înainte. | `valid_until` |
| `complex.mandate_better_contract_requested` | agenția | Dezvoltatorul sau moderarea a cerut un contract mai bun. | `note` (ce s-a cerut) |
| `complex.mandate_restricted` | agenția | Moderarea a oprit pentru o vreme cererile de mandat ale agenției. | `until` |

Toate au `mandate_id`, `complex` (`code`, `title`, `url`) și `status`, starea mandatului în momentul evenimentului, în afară de `complex.mandate_restricted`, care privește agenția, nu un mandat, și are doar `until`. Cu `mandate_id` citești mandatul cu `GET /account/mandates/{id}`.

Evenimentele ajung la titularul și administratorii firmei, prin cheile legate de firmă cu dreptul `listings:read`, iar la un integrator doar dacă legătura lui e pe acea firmă. Un webhook care primește `complex.mandate_confirmed` le primește și pe ele, fără să le bifezi.

`complex.mandate_confirmed`, `complex.mandate_ended` și `complex.taken_over` rămân cum erau. Le găsești î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.