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

# Vizionările

> Ce poți face prin API cu vizionările, de la programul săptămânal la raportul pentru proprietar, cu ce drepturi și ce rămâne doar în aplicație.

Pe un anunț publicat poți oferi ore de vizionare, pe care vizitatorii le rezervă din pagina anunțului, și zile de vizită liberă (open house), în care oricine vine fără programare. Prin API faci tot ce face în aplicație cel care publică anunțul, cu aceleași reguli: orele, agenda, open house-ul, foaia de prezență, rapoartele și vizionările proiectelor. Operațiile de bază pe agenda unui anunț sunt descrise mai jos, iar restul în ghidurile din tabel.

## Ce faci prin API

| În aplicație | Prin API | Ghidul |
| - | - | - |
| „Programul meu” și programul fiecărui anunț | `GET`/`PATCH /account/viewing-schedule`, `GET /account/listings/{code}/viewing-schedule`, `PATCH /listings/{code}/viewing-schedule`, `POST /account/viewing-schedule/apply` | [Programul săptămânal](https://api.housera.ro/ro/guides/viewing-schedule.md) |
| Agenda peste toate anunțurile și foaia unei vizionări | `GET /account/viewings`, `GET /viewings/{id}` | [Agenda de vizionări](https://api.housera.ro/ro/guides/viewing-agenda.md) |
| Agenda unui anunț: ore, ferestre, cereri, rezervări | `GET /account/listings/{code}/viewings` și operațiile de mai jos | pagina aceasta |
| Clientul care a sunat, altă oră, anularea cu notă, „Cum a fost?” | `POST /listings/{code}/viewings/clients`, `POST /viewings/{id}/proposal`, `POST /viewings/{id}/cancel`, `PUT /viewings/{id}/outcome` | [Agenda de vizionări](https://api.housera.ro/ro/guides/viewing-agenda.md) |
| Open house cu notă, înscriere și locuri, anunțarea celor care au salvat anunțul | `POST /listings/{code}/open-house`, `PATCH /viewings/{id}/open-house`, `POST /viewings/{id}/open-house/announce` | [Open house](https://api.housera.ro/ro/guides/open-house.md) |
| Foaia de prezență | `GET`/`POST /viewings/{id}/attendees` și operațiile pe `/open-house-attendees/{id}` | [Foaia de prezență](https://api.housera.ro/ro/guides/open-house.md#foaia-de-prezență) |
| Raportul anunțului și linkul pentru proprietar | `GET /account/listings/{code}/viewing-report`, `POST`/`DELETE /listings/{code}/viewing-report/link`, `POST /listings/{code}/viewing-report/send` | [Rapoartele vizionărilor](https://api.housera.ro/ro/guides/viewing-reports.md) |
| Vizionările proiectelor dezvoltatorului | câmpul `viewings` pe proiect, `POST /projects/{code}/flat-viewings`, `GET /account/projects/{code}/viewing-report` | [Vizionările proiectului](https://api.housera.ro/ro/guides/projects.md#vizionările-proiectului) |
| Ce se întâmplă fără tine (clientul rezervă, confirmă, răspunde la altă oră) | evenimentele `viewing.*` și `open_house.attendee_*` | [Evenimentele vizionărilor](https://api.housera.ro/ro/webhooks.md#evenimentele-vizionărilor) |

## Drepturile

* Orele, programul, open house-ul, rapoartele și proiectele cer `listings:read` pentru citire și `listings:write` pentru schimbări.
* Tot ce privește o persoană cere în plus drepturile cererilor: `leads:read` ca să vezi clientul care a rezervat (`visitor`), clientul adăugat de mână, participanții la un open house și nota de la „Cum a fost?”, iar `leads:write` ca să adaugi un client sau un participant, să lucrezi pe foaia de prezență și să spui cum a fost vizionarea. O cheie fără `leads:read` primește `visitor: null` și nu vede foaia de prezență. Raportul anunțului nu conține persoane, deci îl citește orice cheie cu `listings:read`.
* O cheie vede vizionările pe care contul ei le conduce în aplicație: anunțurile pe care le gestionează, cele ale căror vizionări i-au fost date și, la un dezvoltator, programările ajunse la el ca consultant. În afara lor, răspunsul e `404`.

## Cât păstrăm datele

Datele citite prin API au aceleași termene ca în aplicație. Numele și telefonul unui client adăugat de mână se șterg din vizionare la 90 de zile. Rândurile foii de prezență se șterg la 90 de zile după open house, iar fereastra rămâne. Rezultatul de la „Cum a fost?” și nota lui se șterg după 24 de luni. Un link pentru proprietar merge cel mult 90 de zile. Contactul pe care îl păstrezi în cereri are termenul lui. Dacă păstrezi aceste date în sistemul tău, le ștergi la aceleași termene.

## Ce rămâne doar în aplicație

* Partea clientului: rezervarea, ținerea orei cât intră în cont, anularea și mutarea făcute de el, „Vin și eu” la un open house, formularul de la ușă, nota lui privată, „Vizionările mele”, fișierul de calendar și linkul „Încă vii?” din email. Cheia ta lucrează pentru cel care publică anunțul și nu poate acționa în numele clientului. Ce face clientul afli din evenimente. Pentru clientul care te-a sunat folosești [clientul adăugat de mână](https://api.housera.ro/ro/guides/viewing-agenda.md#clientul-care-a-sunat).
* Mesajele către oameni: confirmările, mementourile și agenda zilei le trimite aplicația, și când acțiunea vine prin API.
* Afișul printabil al open house-ului. API-ul îți dă linkul foii de la ușă, iar codul QR îl desenezi tu.

## Agenda

`GET /account/listings/{code}/viewings` întoarce setările, plus orele și ferestrele care n-au trecut încă:

```json theme={null}
{
  "data": {
    "code": "HEWPUTA8",
    "duration_min": 30,
    "confirmation": "manual",
    "slots": [
      { "id": 9182, "kind": "viewing", "starts_at": "2026-11-12T10:00:00+00:00", "ends_at": "2026-11-12T10:30:00+00:00",
        "status": "pending", "request_expires_at": "2026-11-11T09:14:00+00:00",
        "visitor": { "name": "Ana Popescu", "email": "ana@exemplu.ro", "phone": "+40740123456" } },
      { "id": 9190, "kind": "open_house", "starts_at": "2026-11-15T08:00:00+00:00", "ends_at": "2026-11-15T12:00:00+00:00",
        "status": "available", "request_expires_at": null, "visitor": null }
    ]
  }
}
```

* `kind` e `viewing` (o oră pe care o rezervă un singur vizitator) sau `open_house` (o fereastră de vizită liberă, fără rezervare).
* `status` e `available` (liber), `pending` (cerut de un vizitator, așteaptă răspunsul tău) sau `booked` (rezervat).
* `request_expires_at` e momentul până la care răspunzi unei cereri. După el, cererea expiră și ora se eliberează.
* `visitor` are numele, emailul și telefonul celui care a rezervat sau a cerut ora. Îl primește doar o cheie cu dreptul `leads:read`, fiindcă sunt aceleași date ca într-o [cerere](https://api.housera.ro/ro/guides/leads.md). Pentru celelalte chei e `null`. O rezervare aduce și o cerere nouă, cu `source: viewing_request`.

Fiecare oră are și câmpuri care spun de unde vine și ce s-a întâmplat cu ea (`source`, `bookable`, `outcome`, `agent`, `open_house` și altele). Sunt descrise în [Agenda de vizionări](https://api.housera.ro/ro/guides/viewing-agenda.md). Pe acest endpoint `status` rămâne `available`, `pending` sau `booked`, iar o oră care a trecut nu mai apare.

Orice schimbare de mai jos răspunde cu agenda actualizată, în aceeași formă.

## Setările

`PATCH /listings/{code}/viewings` schimbă una sau amândouă setările:

```json theme={null}
{ "duration_min": 45, "confirmation": "auto" }
```

* `duration_min` e durata unei vizionări, în minute: 15, 30, 45, 60 sau 90. Orele deja publicate își păstrează durata.
* `confirmation` e `auto` (o rezervare e confirmată pe loc) sau `manual` (vizitatorul trimite o cerere, iar tu o accepți sau o refuzi).

## Orele și zilele de vizită liberă

`POST /listings/{code}/viewings` publică ore de vizionare, cel mult 400 într-o cerere:

```json theme={null}
{ "slots": ["2026-11-12T10:00", "2026-11-12T10:30", "2026-11-12T11:00"], "duration_min": 30 }
```

`POST /listings/{code}/open-house` publică ferestre de vizită liberă, cel mult 60 într-o cerere:

```json theme={null}
{ "windows": [ { "starts_at": "2026-11-15T10:00", "ends_at": "2026-11-15T14:00" } ] }
```

* O oră fără fus orar (`2026-11-12T10:00`) e citită pe ceasul locului anunțului, cum o vede vizitatorul. Poți trimite și un moment cu fus (`2026-11-12T08:00:00Z`). O oră care nu există sau apare de două ori la schimbarea orei e refuzată.
* Orele trebuie să fie în viitor, iar sfârșitul unei ferestre vine după început.
* Orele de vizionare nu se suprapun între ele și nici cu o fereastră de vizită liberă. O oră deja publicată e sărită, deci aceeași listă trimisă de două ori nu adaugă nimic.
* `duration_min` trimis la publicare devine durata anunțului. Cu `"set_listing_duration": false`, orele se publică cu durata lor, iar durata anunțului rămâne cea de dinainte.
* Agenda se schimbă doar pe un anunț `active`. Pe alt anunț, răspunsul e `409 listing_action_refused`.

`PATCH /viewings/{id}` mută o oră de vizionare sau o fereastră (`starts_at`, plus `ends_at` la o fereastră). O oră rezervată de un client cu cont nu se mută: îi propui altă oră ([Agenda de vizionări](https://api.housera.ro/ro/guides/viewing-agenda.md#altă-oră-pentru-un-client-cu-cont)), o anulezi sau răspunzi cererii. Vizionarea unui client fără cont, adăugat de mână, se mută direct, fiindcă noua oră ați stabilit-o împreună.

`DELETE /viewings/{id}` retrage o oră sau o fereastră (`204`). Dacă ora era rezervată sau cerută, vizitatorul primește vestea. `POST /listings/{code}/viewings/withdraw` cu `{"slot_ids": [9182, 9183]}` retrage mai multe ore libere deodată. Cele rezervate sau cerute rămân și le retragi pe rând.

## Cererile și rezervările

* `POST /viewings/{id}/accept` acceptă o cerere: ora devine `booked`, iar vizitatorul primește confirmarea.
* `POST /viewings/{id}/decline` refuză o cerere: ora redevine liberă, iar vizitatorul află că cererea a fost refuzată.
* `POST /viewings/{id}/cancel` anulează o rezervare sau o cerere: ora rămâne publicată și liberă, iar vizitatorul primește vestea. Cu `note` (cel mult 300 de caractere), nota ajunge în mesajul către el, dacă are cont.

O cerere la care s-a răspuns deja primește `409 listing_action_refused`. O oră a unui anunț pe care cheia nu îl vede răspunde `404`.

Consultantul unui dezvoltator răspunde la fel programărilor ajunse la el pe un proiect. Răspunsul e agenda anunțului cu orele pe care le vede el în aplicație: clienții lui și zilele de vizită. Agenda întreagă (`GET /account/listings/{code}/viewings`), mutarea și retragerea orelor rămân ale celui care conduce vizionările anunțului. Orele lui le găsește în `GET /account/viewings`.

## Evenimentele

* `viewing.booked`: un vizitator a rezervat sau a cerut o oră. `data` are `slot_id`, `starts_at` și `slot_status` (`booked` sau `pending`).
* `viewing.cancelled`: o rezervare sau o cerere s-a anulat fără tine. `data` are `slot_id`, `starts_at` și `by`: `visitor` când a anulat vizitatorul, `expired` când cererea a expirat fără răspuns.

Le primești ca pe celelalte evenimente ale anunțului, cu dreptul `listings:read`. Din ziua pe care ți-o anunțăm primești și evenimentele pentru ce face colegul tău în aplicație (confirmă, refuză, anulează, mută, propune altă oră, spune cum a fost) și pentru foaia de prezență. Vezi [Evenimentele vizionărilor](https://api.housera.ro/ro/webhooks.md#evenimentele-vizionărilor).


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