API public & chei API

1. Prezentare generală

API-ul MousePlayer vă permite să extrageți date din spațiul de lucru în propriile tablouri de bord, depozite de date sau instrumente interne. În afară de atașarea ID-urilor de client la sesiuni (identify, necesită o cheie cu permisiune de scriere, consultați Permisiunile cheilor), permite doar citirea: datele nu pot fi modificate sau șterse prin API.

• URL de bază: https://www.mouseplayer.com/api/v1/
• Toate răspunsurile sunt în format JSON.
• Fiecare cerere este autentificată printr-o cheie API și limitată automat la spațiul de lucru căruia îi aparține cheia — o cheie dintr-un spațiu de lucru nu poate vedea niciodată datele altuia, nici măcar accidental.
• Înregistrarea completă pentru redarea sesiunii (mișcările mouse-ului, capturile DOM) nu este expusă prin API. Primiți metadatele sesiunii, vizualizările de pagină, evenimentele personalizate și segmentele — suficiente pentru rapoarte și tablouri de bord, fără a transfera datele brute de redare.

2. Autentificare

Creați și administrați cheile API în secțiunea Chei API din meniul contului (/api-keys). Doar proprietarii și administratorii spațiului de lucru pot crea sau revoca chei.

Trimiteți cheia ca token Bearer în antetul Authorization al fiecărei cereri:

Cheile lipsă, cu format incorect sau revocate primesc un răspuns 401:

Cerință de abonament

API-ul REST este inclus în abonamentele Business și Enterprise. Se aplică abonamentul proprietarului spațiului de lucru, deci membrii invitați ai echipei îl moștenesc. Verificarea are loc la fiecare cerere, nu doar la crearea cheii — dacă spațiul de lucru trece la un abonament inferior, cheile existente nu mai funcționează și returnează 403.

Permisiunile cheilor

Fiecare cheie își indică permisiunile prin propriul prefix, astfel încât puteți vedea ce permite doar privind-o — într-un .env, într-o solicitare de asistență sau într-un terminal.

3. Limite de cereri

Fiecare cheie API este limitată la 60 de cereri pe minut, într-o fereastră de timp glisantă. Dacă depășiți limita, cererile primesc un răspuns 429 până când fereastra permite din nou cereri:

4. Endpointuri

GET/api/v1/projects

Listează toate proiectele (site-urile monitorizate) din spațiul de lucru.

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

Listează sesiunile vizitatorilor înregistrate pentru un proiect, începând cu cele mai recente. Rezultatele sunt paginate.

GET/api/v1/sessions/{session_id}

Metadatele unei singure sesiuni și vizualizările sale de pagină. Datele complete de redare sunt excluse intenționat — pentru acestea, folosiți playerul din tabloul de bord.

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

Evenimentele personalizate declanșate într-o sesiune (aceleași evenimente pe care le trimiteți cu mp('event', ...)), inclusiv parametrii acestora.

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

Listează segmentele de vizitatori definite pentru un proiect (atât cele specifice proiectului, cât și cele valabile în întregul spațiu de lucru).

5. Atașarea unui ID de client din backend

Browserul nu știe adesea cine îl folosește. Într-un produs B2B, identitatea este stabilită după autentificare — în backendul dvs. Într-un magazin, este stabilită la confirmarea comenzii. Acest endpoint este destinat exact acelui moment.

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-ul apare apoi în lista sesiunilor, poate fi căutat acolo și se declanșează webhookul session_identified — astfel ajunge în CRM.

6. Webhookuri: verificarea semnăturii

Webhookurile se configurează pentru fiecare proiect în Integrări, unde găsiți și secretul de semnare. Fiecare livrare include aceste antete:

Semnătura este un HMAC-SHA256 calculat pe timestamp + "." + raw body, folosind drept cheie secretul de semnare al proiectului.

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

Livrare și reîncercări

O livrare eșuată este reîncercată după 1 min, 5 min, 15 min, 1 h și 6 h, apoi este abandonată. Pentru răspunsurile 4xx diferite de 408 și 429 reîncercarea nu are loc — ele spun "nu în acest mod", nu "nu acum". Răspundeți rapid cu 2xx și efectuați prelucrarea ulterior; livrarea expiră după 10 secunde.

Evenimente disponibile

7. Erori & coduri de stare

8. Note de securitate

• Cheile doar pentru citire (mp_ro_) nu pot modifica nimic. Cheile de scriere (mp_rw_) pot doar atașa ID-uri de client; nicio cheie nu poate șterge date sau exporta date brute de redare.
• Fiecare cerere este limitată automat la spațiul de lucru al cheii — nu există o modalitate de a transmite alt ID de spațiu de lucru pentru a vedea datele altcuiva.
• Revocați oricând o cheie din /api-keys; revocarea intră în vigoare imediat.
• Tratați cheia API ca pe o parolă. Dacă o includeți accidental într-un commit într-un depozit public, revocați-o imediat și creați alta.