API pública & claves API

1. Resumo

A API MousePlayer permite extraer datos do espazo de traballo aos seus paneis, almacén de datos ou ferramentas internas. Salvo engadir ID de clientes ás sesións (identify, require clave con ámbito de escritura; vexa Ámbitos das claves), é só de lectura: non se poden modificar nin eliminar datos mediante a API.

• URL base: https://www.mouseplayer.com/api/v1/
• Todas as respostas son JSON.
• Cada petición autentícase cunha clave API e limítase automaticamente ao espazo de traballo desa clave — a clave dun espazo nunca pode ver os datos doutro, nin por accidente.
• A gravación completa da reprodución (movementos do rato e capturas DOM) non está exposta na API. Obtén metadatos de sesión, vistas de páxina, eventos personalizados e segmentos — suficiente para crear informes e paneis sen mover os datos de reprodución en bruto.

2. Autenticación

Cree e xestione as claves API en Claves API no menú da conta (/api-keys). Só os propietarios e administradores do espazo de traballo poden crear ou revogar claves.

Envíe a clave como token Bearer na cabeceira Authorization de cada petición:

As claves ausentes, mal formadas ou revogadas reciben unha resposta 401 co seguinte contido:

Requisito do plan

A API REST forma parte dos plans Business e Enterprise e o plan aplicable é o do propietario do espazo de traballo, polo que o herdan os membros invitados. A comprobación execútase en cada petición, non só ao crear a clave — se se reduce o nivel do espazo, as claves existentes deixan de funcionar e devolven 403.

Ámbitos das claves

Cada clave leva o ámbito no prefixo para saber que fai con só mirala — nun .env, nun tícket ou nun terminal.

3. Límites de frecuencia

Cada clave API limítase a 60 peticións por minuto, medidas nunha xanela móbil. Se supera o límite, as peticións reciben unha resposta 429 ata que se libere a xanela:

4. Endpoints

GET/api/v1/projects

Lista todos os proxectos (sitios seguidos) do espazo de traballo.

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

Lista as sesións de visitantes gravadas nun proxecto, as máis recentes primeiro. Paxinado.

GET/api/v1/sessions/{session_id}

Metadatos dunha sesión e as súas vistas de páxina. Exclúe deliberadamente os datos completos da reprodución — use o reprodutor do panel para iso.

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

Eventos personalizados activados nunha sesión (os mesmos que envía con mp('event', ...)), cos seus parámetros.

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

Lista os segmentos de visitantes definidos para un proxecto, tanto os propios como os de todo o espazo de traballo.

5. Engadir un ID de cliente desde o backend

O navegador a miúdo non sabe quen está aí. Nun produto B2B a identidade determínase tras iniciar sesión — no backend. Nunha tenda determínase coa confirmación do pedido. Este endpoint é para ese momento.

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}}

O ID aparece na lista de sesións, pódese buscar nela e actívase o webhook session_identified — así chega ao CRM.

6. Webhook: verificar a sinatura

Os webhook configúranse por proxecto en Integracións, onde tamén está o segredo de sinatura. Cada entrega leva estas cabeceiras:

A sinatura é un HMAC-SHA256 de timestamp + "." + raw body, usando como clave o segredo de sinatura do proxecto.

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

Entrega e novos intentos

Unha entrega fallida reinténtase despois de 1 min, 5 min, 15 min, 1 h e 6 h e despois abandónase. As respostas 4xx distintas de 408 e 429 non se reintentan — significan "non así", non "non agora". Responda 2xx rapidamente e faga o traballo despois; a entrega esgota o tempo de espera tras 10 segundos.

Eventos dispoñibles

7. Erros & códigos de estado

8. Notas de seguridade

• As claves de só lectura (mp_ro_) non cambian nada. As de escritura (mp_rw_) só poden engadir ID de clientes; ningunha pode eliminar datos nin exportar reproducións en bruto.
• Cada petición limítase automaticamente ao espazo de traballo da clave — non hai maneira de pasar outro ID de espazo de traballo e ver datos alleos.
• Revogue unha clave en calquera momento desde /api-keys; a revogación aplícase inmediatamente.
• Trate a clave API como un contrasinal. Se a publica accidentalmente nun repositorio público, revóguea inmediatamente e cree outra.