API pública & claus d’API

1. Visió general

L’API de MousePlayer permet extreure dades de l’espai de treball per als seus propis taulers, magatzems de dades o eines internes. A banda d’adjuntar identificadors de client a les sessions (identify, requereix una clau amb abast d’escriptura; vegi Abasts de les claus), és de només lectura: no es pot modificar ni suprimir cap dada mitjançant l’API.

• URL base: https://www.mouseplayer.com/api/v1/
• Totes les respostes són JSON.
• Cada petició s’autentica amb una clau d’API i es limita automàticament a l’espai de treball al qual pertany la clau — una clau d’un espai de treball no pot veure mai les dades d’un altre, ni per accident.
• La gravació completa de reproducció de la sessió (moviments del ratolí, captures del DOM) no s’exposa mitjançant l’API. Obtindrà metadades de sessió, visualitzacions de pàgina, esdeveniments personalitzats i segments — prou per crear informes i taulers sense moure la càrrega útil de reproducció en brut.

2. Autenticació

Creï i gestioni les claus d’API a Claus d’API del menú del seu compte (/api-keys). Només els propietaris i administradors de l’espai de treball poden crear o revocar claus.

Enviï la clau com a token Bearer a la capçalera Authorization de cada petició:

Les claus absents, mal formades o revocades reben una resposta 401 com aquesta:

Requisit de pla

L’API REST forma part dels plans Business i Enterprise corresponents. El pla es determina a partir del propietari de l’espai de treball; per tant, els membres convidats l’hereten. La comprovació es fa en cada petició, no només en crear una clau — si es baixa de pla un espai de treball, les claus existents deixen de funcionar i retornen 403.

Abasts de les claus

Cada clau incorpora l’abast al prefix, perquè pugui saber què fa només de mirar-la — en un .env, en un tiquet o en un terminal.

3. Límits de peticions

Cada clau d’API està limitada a 60 peticions per minut, comptades en una finestra mòbil. En superar el límit, les peticions reben una resposta 429 fins que s’allibera la finestra:

4. Endpoints

GET/api/v1/projects

Llista tots els projectes (propietats amb seguiment) del seu espai de treball.

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

Llista les sessions de visitants gravades per a un projecte, de la més recent a la més antiga. Amb paginació.

GET/api/v1/sessions/{session_id}

Metadades d’una sessió i les seves visualitzacions de pàgina. Exclou expressament la càrrega útil completa de reproducció — per a això utilitzi el reproductor del tauler.

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

Esdeveniments personalitzats activats durant una sessió (els mateixos que envia amb mp('event', ...)), inclosos els seus paràmetres.

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

Llista els segments de visitants definits per a un projecte (tant els específics del projecte com els de tot l’espai de treball).

5. Adjuntar un identificador de client des del backend

El navegador sovint no sap qui hi ha a l’altra banda. En un producte B2B, la identitat es determina després de l’inici de sessió — al seu backend. En una botiga, es determina amb la confirmació de la comanda. Aquest endpoint és precisament per a aquell 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}}

L’identificador apareix després a la llista de sessions, on es pot cercar, i s’activa el webhook session_identified corresponent — així arriba al seu CRM.

6. Webhooks: verificar la signatura

Els webhooks es configuren per projecte a Integracions, on també trobarà el secret de signatura. Cada lliurament conté aquestes capçaleres:

La signatura és un HMAC-SHA256 de timestamp + "." + raw body, amb el secret de signatura del seu projecte com a clau.

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

Lliurament i reintents

Un lliurament fallit es reintenta al cap de 1 min, 5 min, 15 min, 1 h i 6 h i després s’abandona. Les respostes 4xx que no siguin 408 o 429 mai no es reintenten — indiquen "no d’aquesta manera", no "ara no". Respongui 2xx ràpidament i faci la feina després; el lliurament esgota el temps d’espera al cap de 10 segons.

Esdeveniments disponibles

7. Errors & codis d’estat

8. Notes de seguretat

• Les claus de només lectura (mp_ro_) no poden canviar res. Les d’escriptura (mp_rw_) només poden adjuntar identificadors de client; cap clau no pot suprimir dades ni exportar dades de reproducció en brut.
• Cada petició es limita automàticament a l’espai de treball de la mateixa clau — no es pot passar un identificador d’espai de treball diferent per veure les dades d’algú altre.
• Revoqui una clau en qualsevol moment des de /api-keys; la revocació és immediata.
• Tracti la clau d’API com una contrasenya. Si la incorpora per accident a un repositori públic, revoqui-la immediatament i creï’n una de nova.