Публичный API & API-ключи

1. Обзор

API MousePlayer позволяет получать данные в свои панели, хранилища и инструменты. Кроме присвоения ID клиентов (identify, нужен ключ с записью, см. области ключей) он только для чтения: изменять и удалять данные через API нельзя.

• Базовый URL: https://www.mouseplayer.com/api/v1/
• Все ответы — JSON.
• Каждый запрос авторизуется ключом и ограничен его рабочим пространством — ключ одного никогда не видит данные другого даже случайно.
• Полная запись сеанса (мышь, снимки DOM) не выдаётся через API. Доступны метаданные, просмотры, события и сегменты — достаточно для отчётов и панелей без передачи сырой записи.

2. Аутентификация

Создавайте и управляйте ключами в разделе API-ключи меню учётной записи (/api-keys). Только владельцы и администраторы создают и отзывают ключи.

Передавайте Bearer-токен в заголовке Authorization каждого запроса:

Отсутствующий, неверный или отозванный ключ получает ответ 401 :

Требование тарифа

REST API входит в тарифы Business и Enterprise . Используется тариф владельца рабочего пространства; приглашённые наследуют его. Проверка при каждом запросе, не только создании ключа — при понижении тарифа ключи перестают работать и возвращают 403.

Области ключей

Область видна в префиксе — действие ключа понятно по виду в .env, обращении или терминале.

3. Ограничения частоты

На каждый ключ разрешено 60 запросов в минуту в скользящем окне. При превышении ответ 429 до освобождения окна:

4. Эндпоинты

GET/api/v1/projects

Список всех проектов (отслеживаемых ресурсов) рабочего пространства.

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

Записанные сеансы проекта, сначала новые. С пагинацией.

GET/api/v1/sessions/{session_id}

Метаданные одного сеанса и просмотры. Полная запись намеренно исключена — для неё плеер панели.

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

Собственные события сеанса (переданные через mp('event', ...)) с параметрами.

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

Сегменты посетителей проекта: проектные и всего рабочего пространства.

5. Присвоение ID клиента с сервера

Браузер часто не знает человека. В продукте B2B личность определяется после входа — на вашем сервере. В магазине — при подтверждении заказа. Эндпоинт именно для этого момента.

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 появляется в списке с поиском; срабатывает вебхук session_identified — так данные достигают CRM.

6. Вебхуки: проверка подписи

Вебхуки настраиваются по проектам в Интеграциях, там же секрет подписи. Каждая доставка содержит заголовки:

Подпись — HMAC-SHA256 от timestamp + "." + raw body с секретом подписи проекта в качестве ключа.

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

Доставка и повторы

Неудачная доставка повторяется через 1 мин, 5 мин, 15 мин, 1 ч и 6 ч, затем прекращается. 4xx ответы, кроме 408 и 429 , не повторяются — означают "не так", а не "не сейчас". Отвечайте 2xx быстро и работайте после: время доставки ограничено 10 секундами.

Доступные события

7. Ошибки & коды статуса

8. Безопасность

• Ключи чтения (mp_ro_) ничего не меняют. Ключи записи (mp_rw_) лишь присваивают ID; ни один не удаляет данные и не экспортирует сырые записи.
• Каждый запрос ограничен пространством ключа — нельзя передать другой ID и увидеть чужие данные.
• Отозвать ключ можно в /api-keys; отзыв действует немедленно.
• Обращайтесь с ключом как с паролем. Если случайно внесли в публичный репозиторий, сразу отзовите и создайте новый.