Javni API & API ključevi

1. Pregled

MousePlayer API omogućava preuzimanje podataka iz radnog prostora u vlastite kontrolne ploče, skladište podataka ili interne alate. Osim dodavanja ID-jeva klijenata sesijama (identify, potreban ključ s opsegom pisanja, pogledajte Opsezi ključeva), služi samo za čitanje: putem API-ja nije moguće mijenjati ni brisati podatke.

• Osnovni URL: https://www.mouseplayer.com/api/v1/
• Svi odgovori su JSON.
• Svaki zahtjev se autentificira API ključem i automatski ograničava na njegov radni prostor — ključ jednog radnog prostora nikad ne može vidjeti podatke drugog, čak ni slučajno.
• Potpun snimak reprodukcije sesije (pokreti miša, DOM snimci) nije dostupan putem API-ja. Dobijate metapodatke sesije, preglede stranica, prilagođene događaje i segmente — dovoljno za izvještaje i kontrolne ploče bez premještanja sirovih podataka reprodukcije.

2. Autentifikacija

Kreirajte i uređujte API ključeve pod API ključevi u meniju računa (/api-keys). Samo vlasnici i administratori radnog prostora mogu kreirati ili opozivati ključeve.

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

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

Potreban plan

REST API je dio planova Business i Enterprise u ponudi. Plan se uzima od vlasnika radnog prostora, pa ga pozvani članovi tima nasljeđuju. Provjera se izvršava pri svakom zahtjevu, ne samo pri kreiranju ključa — ako se plan radnog prostora smanji, postojeći ključevi prestaju raditi i vraćaju 403.

Opsezi ključeva

Svaki ključ nosi opseg u svom prefiksu, pa iz njega vidite šta radi — u datoteci .env, tiketu ili terminalu.

3. Ograničenja učestalosti

Svaki API ključ je ograničen na 60 zahtjeva u minuti u pomičnom vremenskom prozoru. Kad prekoračite limit, zahtjevi dobijaju odgovor 429 dok se prozor ne oslobodi:

4. Endpointi

GET/api/v1/projects

Navodi sve projekte (praćena svojstva) radnog prostora.

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

Navodi snimljene sesije posjetilaca projekta, prvo najnovije. Paginirano.

GET/api/v1/sessions/{session_id}

Metapodaci jedne sesije i njeni pregledi stranica. Namjerno bez potpunih podataka reprodukcije — za to koristite plejer kontrolne ploče.

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

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

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

Navodi segmente posjetilaca definirane za projekt, i one posebne za projekt i one za cijeli radni prostor.

5. Dodavanje ID-ja klijenta iz backenda

Preglednik često ne zna ko je s druge strane. U B2B proizvodu identitet se utvrđuje nakon prijave — u backendu. U prodavnici se utvrđuje potvrdom narudžbe. Ovaj endpoint je upravo za taj trenutak.

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 u listi sesija, može se pretraživati i aktivira se webhook session_identified koji ga prenosi — tako stiže do CRM-a.

6. Webhookovi: provjera potpisa

Webhookovi se postavljaju po projektu pod Integracije, gdje je i tajna potpisivanja. Svaka dostava nosi ova zaglavlja:

Potpis je HMAC-SHA256 nad timestamp + "." + raw body, s tajnom potpisivanja projekta kao ključem.

// 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');

Dostava i ponovni pokušaji

Neuspjela dostava ponavlja se nakon 1 min, 5 min, 15 min, 1 h i 6 h pa se odustaje. Odgovori 4xx koji nisu 408 ili 429 ne podliježu ponovnim pokušajima — znače "ne ovako", ne "ne sada". Odgovorite 2xx brzo i obavite posao poslije; dostava ističe nakon 10 sekundi.

Dostupni događaji

7. Greške & statusni kodovi

8. Sigurnosne napomene

• Ključevi čitanja (mp_ro_) ne mogu ništa mijenjati. Ključevi pisanja (mp_rw_) mogu samo dodati ID-jeve klijenata; nijedan ključ ne može brisati podatke ili izvoziti sirove podatke reprodukcije.
• Svaki zahtjev automatski je ograničen na radni prostor ključa — nema načina da pošaljete drugi ID radnog prostora i vidite tuđe podatke.
• Opozovite ključ bilo kada sa /api-keys; opoziv djeluje odmah.
• Tretirajte API ključ kao lozinku. Ako ga slučajno pohranite u javni repozitorij, odmah ga opozovite i kreirajte novi.