Vizionările

Ce faci prin API

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

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ă.
• 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

{
  "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. Pentru celelalte chei e null. O rezervare aduce și o cerere nouă, cu source: viewing_request.

Setările

{ "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ă

{ "slots": ["2026-11-12T10:00", "2026-11-12T10:30", "2026-11-12T11:00"], "duration_min": 30 }

{ "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.

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.

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.