Личный кабинетКонтакты

Внешний API

Справочник методов внешнего API — визиты и профили посетителей, интеграция Telegram-ботов.

Через внешний API Fingprint вы можете получить оценку риска визита и профиль посетителя, а также зарегистрировать Telegram-визит, запросить его данные и профиль Telegram-пользователя. Пример интеграции с ботом приведён на странице «Telegram-боты». Эти методы вызываются с бэкенда.

Авторизуйте запрос

Для регистрации Telegram-визита используйте POST https://gusyrooms.com/api/v1/visit/telegram с активным публичным ключом в X-Public-Key. Приватный ключ и подпись не нужны. Поля запроса, ответ и ошибки описаны в инструкции для Telegram-ботов.

Для получения данных визита, оценки риска или профиля понадобятся публичный и приватный ключи из одной пары API-ключей. Приватный ключ храните только на сервере. Передайте два заголовка:

ЗаголовокЧто передать
X-Public-KeyПубличный API-ключ проекта. Ключ должен быть активен.
X-SignatureПодпись тела запроса, вычисленную с приватным ключом.

Чтобы получить подпись, вычислите HMAC-SHA256 от тела запроса, используя приватный ключ как секрет. Передайте результат в виде шестнадцатеричной строки без префикса. Если у запроса нет тела, вычислите подпись от пустой строки.

Подписывайте именно ту строку, которую отправляете: даже изменение пробелов в JSON меняет подпись. Приватный ключ используется только для вычисления подписи и не передаётся в запросе. Пример подписанного запроса показан на странице API-ключей.

Выберите метод для браузера или Telegram

Для браузерных визитов и Telegram используются отдельные методы:

ДанныеБраузерTelegram
Оценка риска визитаGET /api/v1/fingerprint/visit/risk/{request_id}GET /api/v1/fingerprint/visit/risk/{request_id}/telegram
Профиль посетителяPOST /api/v1/fingerprint/visitor/profilePOST /api/v1/fingerprint/visitor/profile/telegram

В GET-запросе подставьте request_id в адрес и подпишите пустую строку. В POST-запросе передайте JSON с полем visitor_fp_hash и подпишите это тело. Параметр sdk не требуется: тип данных определяется выбранным методом.

В request_id передавайте одноимённое поле из ответа регистрации, а в visitor_fp_hash — значение user. Сохраняйте идентификаторы без изменений. Для Telegram ответ регистрации также содержит platform: "tg". Пример запросов для Telegram.

Справочник методов

Получить оценку риска web-визита

GET
/fingerprint/visit/risk/{request_id}

Возвращает оценку риска на момент конкретного web-визита по его request_id. Поля риска находятся в объекте risk в формате профиля посетителя и относятся только к найденному визиту. Объект current_visit содержит время, IP, браузер, ОС и геолокацию этого визита в формате latest_visit из профиля. Геолокация определяется по IP визита; если она недоступна, location равен null. Входящий запрос авторизуется заголовками X-Public-Key и X-Signature, где подпись равна HMAC-SHA256 от raw body с использованием private key.

Authorization

PublicKeyAuth SignatureAuth
X-Public-Key<token>

Открытый ключ клиентского приложения.

In: header

X-Signature<token>

HMAC-SHA256(raw request body, private key) в hex-формате.

In: header

Path Parameters

request_id*string

request_id из ответа регистрации визита.

Lengthlength <= 255

Response Body

application/json

curl -X GET "https://example.com/fingerprint/visit/risk/string"
{  "visitor_id": "string",  "bot": {    "is_bot": true,    "type": "good"  },  "risk": {    "level": "high",    "has_incognito": true,    "has_telegram_browser": true,    "has_vpn": true,    "has_danger_browser": true  },  "current_visit": {    "at": "2019-08-24T14:15:22Z",    "ip_address": "string",    "browser": "string",    "os": "string",    "location": {      "country_code": "string",      "city": "string"    }  }}

Получить оценку риска Telegram-визита

GET
/fingerprint/visit/risk/{request_id}/telegram

Возвращает оценку риска и данные конкретного Telegram-визита по его request_id. Ответ содержит visitor_id, user_id, risk и current_visit с данными from. Доступны только визиты авторизованного ключа. Входящий запрос авторизуется заголовками X-Public-Key и X-Signature, где подпись равна HMAC-SHA256 от raw body с использованием private key.

Authorization

PublicKeyAuth SignatureAuth
X-Public-Key<token>

Открытый ключ клиентского приложения.

In: header

X-Signature<token>

HMAC-SHA256(raw request body, private key) в hex-формате.

In: header

Path Parameters

request_id*string

request_id из ответа регистрации Telegram-визита.

Lengthlength <= 255

Response Body

application/json

curl -X GET "https://example.com/fingerprint/visit/risk/string/telegram"
{  "visitor_id": "string",  "user_id": 0,  "risk": {    "level": "no",    "is_bot": true  },  "current_visit": {    "request_id": "string",    "key_id": 0,    "created_at": "2019-08-24T14:15:22Z",    "profile_hash": "string",    "from": {      "id": 0,      "is_bot": true,      "first_name": "string",      "last_name": "string",      "username": "string",      "language_code": "string",      "is_premium": true,      "added_to_attachment_menu": true    }  }}

Получить iOS-визит в группе ключа

GET
/fingerprint/visit/risk/{request_id}/ios

Возвращает признаки риска и сохранённые данные iOS-визита по request_id. Доступны визиты ключей той же группы и того же клиента, включая историю удалённых ключей. Для ключа без группы доступ ограничен самим ключом. Запрос подписывается HMAC-SHA256 от raw body с использованием private key через X-Public-Key и X-Signature.

Authorization

PublicKeyAuth SignatureAuth
X-Public-Key<token>

Открытый ключ клиентского приложения.

In: header

X-Signature<token>

HMAC-SHA256(raw request body, private key) в hex-формате.

In: header

Path Parameters

request_id*string
Lengthlength <= 255

Response Body

application/json

curl -X GET "https://example.com/fingerprint/visit/risk/string/ios"
{  "visitor_id": "string",  "risk": {    "has_vpn": true,    "has_jailbreak": true,    "has_emulator": true,    "is_location_simulated": true,    "is_location_mismatch": true  },  "current_visit": {    "request_id": "266ea41d-adf5-480b-af50-15b940c2b846",    "key_id": 0,    "created_at": "2019-08-24T14:15:22Z",    "ip_address": "string",    "user_agent": "string",    "data_hash": "string",    "data": {      "property1": null,      "property2": null    },    "device_address": "string"  }}

Получить web-профиль посетителя

POST
/fingerprint/visitor/profile

Возвращает сохранённый web-профиль посетителя без агрегации визитов во время запроса. Входящий запрос авторизуется заголовками X-Public-Key и X-Signature, где подпись равна HMAC-SHA256 от raw JSON body с использованием private key. Private key в запрос не передается.

Authorization

PublicKeyAuth SignatureAuth
X-Public-Key<token>

Открытый ключ клиентского приложения.

In: header

X-Signature<token>

HMAC-SHA256(raw request body, private key) в hex-формате.

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

curl -X POST "https://example.com/fingerprint/visitor/profile" \  -H "Content-Type: application/json" \  -d '{    "visitor_fp_hash": "visitor-fingerprint-hash"  }'
{  "visitor_id": "string",  "bot": {    "is_bot": true,    "type": "good"  },  "risk": {    "level": "high",    "has_incognito": true,    "has_telegram_browser": true,    "has_vpn": true,    "has_danger_browser": true  },  "statistics": {    "visits_count": 0,    "incognito_visits_count": 0,    "vpn_visits_count": 0,    "unique_ip_count": 0,    "unique_location_count": 0,    "unique_device_count": 0  },  "latest_visit": {    "at": "2019-08-24T14:15:22Z",    "ip_address": "string",    "browser": "string",    "os": "string",    "location": {      "country_code": "string",      "city": "string"    }  },  "latest_vpn": {    "ip_address": "string",    "detected_at": "2019-08-24T14:15:22Z"  },  "updated_at": "2019-08-24T14:15:22Z"}

Получить Telegram-профиль посетителя

POST
/fingerprint/visitor/profile/telegram

Возвращает сохранённый Telegram-профиль по visitor_fp_hash из ответа регистрации визита. Профиль и статистика доступны только для авторизованного ключа. Входящий запрос авторизуется заголовками X-Public-Key и X-Signature, где подпись равна HMAC-SHA256 от raw JSON body с использованием private key. Private key в запрос не передаётся.

Authorization

PublicKeyAuth SignatureAuth
X-Public-Key<token>

Открытый ключ клиентского приложения.

In: header

X-Signature<token>

HMAC-SHA256(raw request body, private key) в hex-формате.

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

curl -X POST "https://example.com/fingerprint/visitor/profile/telegram" \  -H "Content-Type: application/json" \  -d '{    "visitor_fp_hash": "visitor-fingerprint-hash"  }'
{  "visitor_id": "string",  "user_id": 0,  "risk": {    "level": "no",    "is_bot": true  },  "statistics": {    "visits_count": 0,    "data_count": 0,    "first_visit_at": "2019-08-24T14:15:22Z",    "last_visit_at": "2019-08-24T14:15:22Z"  },  "latest_visit": {    "request_id": "string",    "key_id": 0,    "created_at": "2019-08-24T14:15:22Z",    "profile_hash": "string",    "from": {      "id": 0,      "is_bot": true,      "first_name": "string",      "last_name": "string",      "username": "string",      "language_code": "string",      "is_premium": true,      "added_to_attachment_menu": true    }  }}

Получить iOS-профиль в группе ключа

POST
/fingerprint/visitor/profile/ios

Возвращает iOS-профиль по visitor_fp_hash из ответа регистрации визита. Профиль, накопленные признаки риска, статистика и последний визит ограничены группой авторизованного ключа и его клиентом. Для ключа без группы поиск ограничен самим ключом. Групповая статистика собирается с момента внедрения групповых агрегатов; существующая история не пересчитывается. Запрос подписывается HMAC-SHA256 от raw JSON body с использованием private key через X-Public-Key и X-Signature.

Authorization

PublicKeyAuth SignatureAuth
X-Public-Key<token>

Открытый ключ клиентского приложения.

In: header

X-Signature<token>

HMAC-SHA256(raw request body, private key) в hex-формате.

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

curl -X POST "https://example.com/fingerprint/visitor/profile/ios" \  -H "Content-Type: application/json" \  -d '{    "visitor_fp_hash": "visitor-fingerprint-hash"  }'
{  "visitor_id": "string",  "risk": {    "has_vpn": true,    "has_jailbreak": true,    "has_emulator": true,    "is_location_simulated": true,    "is_location_mismatch": true  },  "statistics": {    "visits_count": 0,    "data_count": 0,    "vpn_visits_count": 0,    "jailbreak_visits_count": 0,    "emulator_visits_count": 0,    "location_simulated_visits_count": 0,    "location_mismatch_visits_count": 0,    "first_visit_at": "2019-08-24T14:15:22Z",    "last_visit_at": "2019-08-24T14:15:22Z"  },  "latest_visit": {    "request_id": "266ea41d-adf5-480b-af50-15b940c2b846",    "key_id": 0,    "created_at": "2019-08-24T14:15:22Z",    "ip_address": "string",    "user_agent": "string",    "data_hash": "string",    "data": {      "property1": null,      "property2": null    },    "device_address": "string"  }}

Ошибки SDK

Коды FingprintAgentError, когда они возникают и как их исправить.