Описание API Ядра v1 (legacy)

Данная версия API является устаревшей и не рекомендуется к использованию.

Документация API v2

Описание текущей версии API размешено на отдельном портале.

Для доступа к документации требуется логин и пароль, полученные при подключении услуги.

Перейти к описанию API v2

Бэкэнд Информационной системы Заказчика может вызывать API Ядра ИППМ для сообщения Ядру о произошедших событиях, например, начале и окончании сессии Клиента, а также для получения информации, например, параметров сессии и ее скоринга. Для запросов к Ядру требуется персональный ключ Заказчика (apiKey). В API Ядра реализованы следующие функции.

Начало сессии

Данный метод вызывается бэкэндом Заказчика и сообщает Ядру, что указанная в параметрах метода сессия началась.

Тип HTTP запроса: POST
Путь вызова: /frap/pixel/api/startClientSession
Формат передачи параметров: application/json
Формат ответа: application/json
Код ответа HTTP в случае успеха: 200

Параметры:

Параметр	Тип	Обязательный	Описание
apiKey	string	Да	Персональный ключ Заказчика для доступа к API Ядра
clientId	string	Да	Номер мобильного телефона Клиента, инициировавшего сессию (идентификатор клиента)

Метод возвращает:

Параметр	Тип	Обязательный	Описание
sessionId	string	Да	Идентификатор сессии

POST /frap/pixel/api/startClientSession
Content-Type: application/json
Accept: application/json

{
    "apiKey": "b97fd8458b8579d7b3987cf6b406a0cc",
    "sessionId": "1a3e142e46d0ad6250f184ffc45ed632",
    "clientId": "79531234567"
}

Пример успешного ответа:

{
    "sessionId": "1a3e142e46d0ad6250f184ffc45ed632"
}

Окончание сессии

Данный метод сообщает Ядру, что указанная в параметрах метода сессия завершилась.

Тип HTTP запроса: POST
Путь вызова: /frap/pixel/api/endClientSession
Формат передачи параметров: application/json
Формат ответа: text/plain
Текст ответа в случае успеха: Session ended
Код ответа HTTP в случае успеха: 200

Параметры:

Параметр	Тип	Обязательный	Описание
apiKey	string	Да	Персональный ключ Заказчика для доступа к API Ядра
sessionId	string	Нет	Идентификатор завершившейся сессии

Пример вызова:

POST /frap/pixel/api/endClientSession
Content-Type: application/json
Accept: */*

{
    "apiKey": "b97fd8458b8579d7b3987cf6b406a0cc",
    "sessionId": "1a3e142e46d0ad6250f184ffc45ed632"
}

Список инцидентов скоринга сессии

Данный метод запрашивает перечень инцидентов, влияющих на скоринг сессии.

Тип HTTP запроса: POST
Путь вызова: /frap/pixel/api/getClientSessionIncidents
Формат передачи параметров: application/json
Формат ответа: application/json
Код ответа HTTP в случае успеха: 200

Параметры:

Параметр	Тип	Обязательный	Описание
apiKey	string	Да	Персональный ключ Заказчика для доступа к API Ядра
sessionId	string	Нет	Идентификатор сессии

Метод возвращает:

Параметр	Тип	Обязательный	Описание
incidents	Incident[]	Да	Массив инцидентов сессии

Объект инцидента содержит следующие параметры:

Параметр	Тип	Обязательный	Описание
id	int	Да	**
uniqueId	string	Да	Уникальный идентификатор инцидента – может использоваться при взаимодействии с IDX для получения разъяснений по инциденту
timestamp	string	Да	Временная метка создания инцидента в Ядре
usage	string	Да	**
type	string	Да	**
origi	string	Да	**
group	string	Да	Название группы инцидентов
name	string	Нет	*
value	string	Нет	*
code	int	Да	Код инцидента
score	int	Да	Скоринг инцидента
message	string	Да	Текстовое сообщение, разъясняющее суть инцидента – может использоваться в пользовательском интерфейсе ИС Заказчика
parentType	string	Да	Тип сущности Ядра, породившей данный инцидент – сессия, фингерпринт и т.д.
parentRecordId	int	Да	Идентификатор сущности, породившей инцидент

* – Значение, специфичное для данного кода инцидента, дающее дополнительную информацию об инциденте
** – служебный параметр

Пример вызова:

POST /frap/pixel/api/getClientSessionIncidents
Content-Type: application/json
Accept: application/json

{
    "apiKey": "b97fd8458b8579d7b3987cf6b406a0cc",
    "sessionId": "1a3e142e46d0ad6250f184ffc45ed632"
}

Пример успешного ответа:

{
    "incidents": [
        {
            "id": 10003,
            "uniqueId": "12345678-4321-8765-4321-123456789012",
            "timestamp": "2000-01-01T00:00:00.940643",
            "usage": "S",
            "type": "I",
            "origin": "A",
            "group": "software",
            "name": null,
            "value": null,
            "code": 1004,
            "score": 50,
            "message": "Клиент включил режим инкогнито",
            "parentType": "F",
            "parentRecordId": 1000,
            "parentId": "12345678-1234-5678-1234-123456789012"
        }
    ]
}

Список атрибутов сессии

Данный метод запрашивает перечень атрибутов сессии.

Тип HTTP запроса: POST
Путь вызова: /frap/pixel/api/getClientSessionAttributes
Формат передачи параметров: application/json
Формат ответа: application/json
Код ответа HTTP в случае успеха: 200

Параметры:

Параметр	Тип	Обязательный	Описание
apiKey	string	Да	Персональный ключ Заказчика для доступа к API Ядра
sessionId	string	Нет	Идентификатор сессии

Метод возвращает:

Параметр	Тип	Обязательный	Описание
hostIpAddressPublic	string	Да	IPv4 или IPv6
pixelType	string	Да	Платформа пикселя: W – веб A – Android
hostTimezone	double	Да	Смещение временной зоны по часам устройства Клиента
ipCity	string	Нет	Город по IP-адресу
ipCountry	string	Нет	Страна по IP-адресу
ipTimezoneId	string	Нет	Идентификатор (TZ) временной зоны по IP-адресу
uaBrowser	string	Да	Название браузера
uaIsMobile	boolean	Да	Признак мобильного устройства
uaPlatform	string	Да	Название операционной системы
deviceId	string	Да	Идентификатор устройства

Пример вызова:

POST /frap/pixel/api/getClientSessionAttributes
Content-Type: application/json
Accept: application/json

{
    "apiKey": "b97fd8458b8579d7b3987cf6b406a0cc",
    "sessionId": "1a3e142e46d0ad6250f184ffc45ed632"
}

Пример успешного ответа:

{
    "hostIpAddressPublic": "10.10.10.10",
    "pixelType": "W",
    "hostTimezone": 3.0,
    "ipCity": "Moscow",
    "ipCountry": "Russia",
    "ipTimezoneId": "Europe/Moscow",
    "uaBrowser": "Chrome",
    "uaIsMobile": false,
    "uaPlatform": "Win10",
    "deviceId": "12365432-1234-4140-1353-46f3d958a380"
}

Обратная связь по репутации сессии

Данный метод сообщает Ядру, что указанная в параметрах метода сессия имеет плохую репутацию.

Тип HTTP запроса: POST
Путь вызова: /frap/pixel/api/reportClientSessionReputation
Формат передачи параметров: application/json
Формат ответа: text/plain
Текст ответа в случае успеха: Session reputation noted
Код ответа HTTP в случае успеха: 200

Параметры:

Параметр	Тип	Обязательный	Описание
apiKey	string	Да	Персональный ключ Заказчика для доступа к API Ядра
sessionId	string	Нет	Идентификатор завершившейся сессии

Пример вызова:

POST /frap/pixel/api/reportClientSessionReputation
Content-Type: application/json
Accept: */*

{
    "apiKey": "b97fd8458b8579d7b3987cf6b406a0cc",
    "sessionId": "1a3e142e46d0ad6250f184ffc45ed632"
}

Скоринг хоста

Данный метод запрашивает скоринг хоста.

Тип HTTP запроса: POST
Путь вызова: /frap/pixel/api/getNormalizedDeviceScore
Формат передачи параметров: application/json
Формат ответа: application/json
Код ответа HTTP в случае успеха: 200

Параметры:

Параметр	Тип	Обязательный	Описание
apiKey	string	Да	Персональный ключ Заказчика для доступа к API Ядра
entityType	string	Да	Указывает, идентификатор какой сущности (фингерпринта, сессии или хоста) передается в параметре entityId. Допустимые значения: SESSION
entityId	string	Да	Идентификатор сессии

Метод возвращает:

Параметр	Тип	Обязательный	Описание
score	int	Да	Значение скоринга хоста

Пример вызова:

POST /frap/pixel/api/getNormalizedDeviceScore
Content-Type: application/json
Accept: */*

{
    "apiKey": "b97fd8458b8579d7b3987cf6b406a0cc",
    "entityType": "SESSION",
    "entityId": "1a3e142e46d0ad6250f184ffc45ed632"
}

Пример успешного ответа:

{
    "score": 5
}