API ključevi

Svaki zahtev javnom API-ju nosi ključ u zaglavlju x-api-key:

GET /api/v1/properties HTTP/1.1
Host: app.propertio.rs
x-api-key: pk_ab12cd34.Xk3…

Ključ ima oblik pk_<8 znakova>.<tajni deo>. Prvi deo (pk_ab12cd34) je javni prefiks po kome agencija prepoznaje ključ u aplikaciji. Ceo ključ se prikazuje samo jednom, pri pravljenju; Propertio čuva samo njegov heš. Izgubljen ključ ne može da se pročita, može samo da se napravi novi.

Ko pravi ključ

Ključ pravi agencija u aplikaciji, na stranici Portali i sajt → Vaši sajtovi: dodaje sajt (Dodaj sajt) i za njega pravi ključ (Napravi ključ za ovaj sajt). To mogu vlasnik i menadžeri kada je vlasnik uključio Režim za programere (Podešavanja → Profil agencije → Napredno). Bez režima za programere ključ za agenciju pravi Propertio tim.

Na istoj kartici sajta agencija upisuje adresu sajta i može da uključi automatsko objavljivanje novih oglasa na sajtu (podrazumevano je isključeno: agencija bira oglase).

Jedan ključ, jedan sajt

Agencija može da ima više svojih sajtova, koliko dozvoljava plan:

Plan	Broj sopstvenih sajtova
Standard	1
Large	2
Large+	3
Unlimited	neograničeno

Sajt koji hostuje Propertio (dodatak „Sajt agencije“) se ne računa. Sajt filijale se računa.

Svaki sajt ima svoje ključeve. Ključ pripada tačno jednom sajtu i vidi samo oglase objavljene na tom sajtu:

• dva sajta iste agencije ne vide oglase jedan drugog (oglas koji nije objavljen na sajtu vraća 404);
• nijedan ključ ne vidi oglase objavljene samo na sajtu koji hostuje Propertio;
• kada je sajt isključen, ključ i dalje radi, ali lista oglasa je prazna;
• GET /v1/site broji samo oglase tog sajta;
• upit i zahtev za pokazivanje primaju samo oglase koje sajt prikazuje. Kada agencija ima više sajtova, poruka upita dobija poslednji red Sajt: <naziv sajta>.

Kada agencija obriše sajt, svi njegovi ključevi odmah prestaju da važe (401), a oglasi se skidaju sa njega.

Opsezi

Opseg	Šta dozvoljava
public:read	GET /v1/agency, GET /v1/site, GET /v1/agents, GET /v1/properties, GET /v1/properties/{idOrSlug}, POST /v1/assistant, POST /v1/voice/speak, GET /v1/voice/confirmation
public:inquiry	POST /v1/inquiries, POST /v1/viewing-requests; uz ovaj opseg AI asistent sme i da pošalje upit ili zahtev za pokazivanje u ime posetioca

Ključ napravljen u aplikaciji ima oba opsega. Ključ samo za čitanje i ključ sa rokom važenja pravi Propertio tim na zahtev. Poziv bez potrebnog opsega vraća 403 FORBIDDEN („API key lacks scope public:inquiry“).

Ključ filijale

Pri dodavanju sajta agencija bira Sajt za → filijala. Svi ključevi takvog sajta su ključevi filijale:

• GET /v1/properties i detalj oglasa vraćaju samo oglase te filijale;
• GET /v1/agency vraća kontakt i logo filijale (prazna polja preuzimaju vrednosti agencije), a branch je { id, name, slug, accent };
• GET /v1/agents vraća ljude te filijale i agente bez filijale koji vode njene oglase;
• opšti upit (bez propertyId) stiže u tu filijalu; upit o oglasu uvek ide filijali oglasa.

Ključ cele agencije vraća branch: null.

Dozvoljeni sajtovi (Origin)

Kada se API poziva iz pregledača, agencija može da ograniči ključeve na svoje domene: Podešavanja → Profil agencije → Napredno → Sajtovi kojima je dozvoljeno da prikazuju vaše oglase (do 20 adresa). Adresa sačuvana na kartici sajta (Portali i sajt → Vaši sajtovi) dodaje se na listu sama, sa www. i bez njega. Lista važi za sve sajtove agencije.

• Prazna lista: ključ radi sa svakog sajta.
• Kada lista postoji, a zaglavlje Origin nije na njoj: 403 FORBIDDEN („Origin not allowed for this agency“). Poređenje je tačno: šema, domen i port, bez / na kraju (https://www.agencija.rs).
• Zahtevi bez zaglavlja Origin (server, cron, curl) se ne proveravaju.
• CORS za /v1/*: Access-Control-Allow-Origin: *, bez kolačića; dozvoljena zaglavlja Content-Type, x-api-key i x-request-id; metode GET, POST, OPTIONS.

Origin nije zaštita ključa

Lista sprečava tuđi sajt da Vaš ključ koristi iz pregledača. Skripta na serveru može da pošalje bilo koji Origin, pa ključ držite na serveru kad god možete. Vidi Bezbednost i podaci.

Opoziv, rok i suspenzija

• Opoziv važi odmah: sledeći zahtev dobija 401 UNAUTHORIZED („Invalid API key“). Isto važi za ključ kome je istekao rok.
• Aplikacija pokazuje kada je ključ poslednji put korišćen (osvežava se najviše jednom u minutu).
• Kada je nalog agencije suspendovan, svi ključevi vraćaju 403 FORBIDDEN („Agency is suspended“).

Zamena ključa bez prekida: agencija napravi novi ključ, Vi ga postavite na sajt, pa agencija opozove stari.