Javni API & API ključevi

1. Pregled

MousePlayer API omogućava preuzimanje podataka iz radnog prostora u vaše kontrolne table, skladište podataka ili interne alate. Osim dodavanja ID-jeva kupaca sesijama (identify zahteva ključ sa opsegom pisanja, pogledajte Opsezi ključeva), on je samo za čitanje: podaci ne mogu da se menjaju ili brišu preko API-ja.

• Osnovni URL: https://www.mouseplayer.com/api/v1/
• Svi odgovori su JSON.
• Svaki zahtev se autentifikuje API ključem i automatski ograničava na radni prostor kome ključ pripada — ključ jednog radnog prostora nikada ne može da vidi podatke drugog, čak ni slučajno.
• Potpuni snimak sesije (pomeranja miša, DOM snimci) nije dostupan preko API-ja. Dobijate metapodatke sesije, prikaze stranica, prilagođene događaje i segmente — dovoljno za izveštaje i kontrolne table bez prenošenja sirovih podataka snimka.

2. Autentifikacija

Napravite API ključeve i upravljajte njima pod API ključevi u meniju naloga (/api-keys). Samo vlasnici i administratori radnog prostora mogu da prave ili opozivaju ključeve.

Šaljite ključ kao Bearer token u zaglavlju Authorization svakog zahteva:

Nedostajući, neispravni ili opozvani ključevi dobijaju odgovor 401:

Zahtev plana

REST API je deo planova Business i Enterprise. Plan se preuzima od vlasnika radnog prostora, pa ga pozvani članovi tima nasleđuju. Provera se izvršava pri svakom zahtevu, ne samo pri pravljenju ključa — ako radni prostor pređe na niži plan, postojeći ključevi prestaju da rade i vraćaju 403.

Opsezi ključeva

Svaki ključ nosi opseg u svom prefiksu, pa možete da vidite šta radi samim pogledom — u .env, u tiketu, u terminalu.

3. Ograničenja učestalosti

Svaki API ključ ograničen je na 60 zahteva u minuti, praćeno u kliznom vremenskom prozoru. Nakon prekoračenja, zahtevi dobijaju odgovor 429 dok se prozor ne oslobodi:

4. Endpoint-i

GET/api/v1/projects

Navodi sve projekte (praćene sajtove) u radnom prostoru.

GET/api/v1/projects/{channelid}/sessions

Navodi sesije posetilaca snimljene za projekat, prvo najnovije. Sa straničenjem.

GET/api/v1/sessions/{session_id}

Metapodaci jedne sesije uz njene prikaze stranica. Namerno izostavlja potpune podatke snimka — za njih koristite plejer kontrolne table.

GET/api/v1/sessions/{session_id}/events

Prilagođeni događaji pokrenuti tokom sesije (isti koje šaljete preko mp('event', ...)), uključujući parametre.

GET/api/v1/projects/{channelid}/segments

Navodi segmente posetilaca definisane za projekat (i segmente projekta i celog radnog prostora).

5. Dodavanje ID-ja kupca iz vašeg pozadinskog sistema

Pregledač često ne zna ko sedi za njim. U B2B proizvodu identitet se utvrđuje nakon prijave — u vašem pozadinskom sistemu. U prodavnici se utvrđuje pri potvrdi porudžbine. Ovaj endpoint služi upravo tom trenutku.

POST /api/v1/sessions/{session_id}/identify
Authorization: Bearer mp_live_xxxxxxxxxxxx
Content-Type: application/json

{"user_id": "customer-4711"}

// 200 OK
{"data": {"session_id": "s_a1b2c3", "user_id": "customer-4711",
          "changed": true, "previous": null, "webhook_queued": true}}

ID se zatim pojavljuje na listi sesija, tamo se može pretraživati i pokreće se webhook session_identified — tako stiže u vaš CRM.

6. Webhook-ovi: provera potpisa

Webhook-ovi se podešavaju po projektu pod Integracije, gde se nalazi i tajna za potpisivanje. Svaka isporuka sadrži ova zaglavlja:

Potpis je HMAC-SHA256 nad timestamp + "." + raw body, uz tajnu za potpisivanje vašeg projekta kao ključ.

// PHP
$erwartet = 'sha256=' . hash_hmac('sha256', $timestamp . '.' . $rawBody, $secret);
if (!hash_equals($erwartet, $signature)) { http_response_code(401); exit; }

// Node
const expected = 'sha256=' + crypto.createHmac('sha256', secret)
                                     .update(timestamp + '.' + rawBody).digest('hex');

Isporuka i ponovni pokušaji

Neuspela isporuka pokušava se ponovo nakon 1 min, 5 min, 15 min, 1 h i 6 h, pa se odustaje. 4xx odgovori osim 408 i 429 se ne ponavljaju — znače "ne ovako", a ne "ne sada". Odgovorite sa 2xx brzo, a posao obavite posle; isporuka ističe nakon 10 sekundi.

Dostupni događaji

7. Greške & statusni kodovi

8. Bezbednosne napomene

• Ključevi samo za čitanje (mp_ro_) ne mogu ništa da menjaju. Ključevi pisanja (mp_rw_) mogu samo da dodaju ID-jeve kupaca; nijedan ključ ne može da briše podatke ili izvozi sirove podatke snimka.
• Svaki zahtev automatski je ograničen na radni prostor ključa — ne postoji način da se prosledi ID drugog radnog prostora i vide tuđi podaci.
• Opozovite ključ u bilo kom trenutku preko /api-keys; opoziv odmah stupa na snagu.
• Postupajte sa API ključem kao sa lozinkom. Ako ga slučajno komitujete u javni repozitorijum, odmah ga opozovite i napravite novi.