Адкрыты 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. Кропкі API

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 спрацоўвае — так ID трапляе ў 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; гэта дзейнічае адразу.
• Стаўцеся да ключа як да пароля. Пры выпадковым каміце ў адкрыты рэпазіторый адразу адклічце і стварыце новы.