Версия: 1.9.0 (последняя)

Операции с отчётами

Этот раздел API предназначен для управления отчётами об эффективности работы системы.

Работа с отчётами проходит в несколько этапов:

Создаётся отчёт, для которого нужно получить метрики за определённый промежуток времени.
Отчёт ставится в очередь на обработку.
После завершения обработки метрики из отчёта становятся доступными через API.

Состояние отчёта можно отследить по полю "status". Возможные состояния отчёта:

0: Ожидание: Отчёт только создан и не запущен в обработку.
1: Обработка: Отчёт в процессе обработки. Обработка может занимать продолжительное время в зависимости от размера базы данных и временного периода отчёта.
2: Завершён: Отчёт успешно обработан. Если данные за период проверки обновились, чтобы получить их, потребуется создать новый отчёт.
3: Ошибка: Произошла ошибка при построении отчёта.
4: Отменён: Обработка отчёта отменена. Возобновление обработки затронет только недополученные метрики.
5: Неожиданно остановлен: Построение отчёта завершено незапланированно. Например, сервис был перезапущен, когда происходило построение отчёта.

Данные отчёта

Отчёт состоит из нескольких разделов.

Раздел отчёта nist

Раздел содержит следующие метрики:

failRate. Доля аппликантов в статусе "Fail" и "Failed Attempt" относительно общего числа аппликантов.
passRate. Доля аппликантов в статусе "Success" относительно общего числа аппликантов.
completion. Среднее время с момента создания аппликанта до его регистрации.
suspectedFraud. Доля попыток с рисками относительно общего числа попыток.
abandonmentRate. Доля аппликантов в статусе "Pending" относительно общего числа аппликантов.
fraudProofing. Сумма аппликантов в статусе "Cancelled" и количества попыток регистрации с рисками.
fraudAuthentication. Сумма аппликантов в статусе "Cancelled" и количества попыток авторизации с рисками.
authenticationFailures. Средняя доля провальных попыток относительно общего числа попыток по каждому аппликанту.

Раздел отчёта registrationMetrics

Раздел содержит следующие метрики:

applicantsAttemptToRegister. Количество аппликантов, которые пытались зарегистрироваться или зарегистрировались, т.е. имеют хотя бы одну попытку.

Раздел содержит следующие подразделы:

registeredApplicantsSettledInRegAttempts. Данные аппликантов, которые зарегистрировались, уложившись в количество попыток.
registeredApplicantsNotSettledInRegAttempts. Данные аппликантов, которые зарегистрировались, не уложившись в число попыток. Если система настроена на бесконечное число попыток, данные этого раздела будут помечены как "Not calculated due to system settings".
notRegisteredApplicantsSettledInRegAttempts. Данные аппликантов, которые не зарегистрировались, но попытались зарегистрироваться менее допустимого количества раз.
notRegisteredApplicantsNotSettledInRegAttempts Данные аппликантов, которые не зарегистрировались и потратили попыток больше, чем допустимо. Если система настроена на бесконечное число попыток, данные этого раздела будут помечены как "Not calculated due to system settings".

Все подразделы выше содержат одинаковые метрики. Точка в именах означает вложенность, например sample.data означает, что в словаре sample находиться ключ data.

Список метрик:

count. Количество аппликантов в категории.
failReasons.validationFailuresCount.qualityFailedSum. Количество провалов проверки качества.
failReasons.validationFailuresCount.faceMatchingFailedSum. Количество провалов матчинга лиц при регистрации.
failReasons.validationFailuresCount.lrCrossMatchFailedSum. Количество провалов матчинга кадра из видео liveness reflection.
failReasons.validationFailuresCount.mcCrossMatchFailedSum. Количество провалов матчинга кадра из видео motion control.
failReasons.validationFailuresCount.oneFrameLivenessFailedSum. Количество провалов проверки живости.
failReasons.validationFailuresCount.livenessReflectionFailedSum. Количество провалов проверки liveness reflection.
failReasons.inactiveRisksCount.massAttackRiskCount. Количество срабатываний риска неактивного MassAttack.
failReasons.inactiveRisksCount.duplicateFaceCount. Количество срабатываний риска неактивного DuplicateFace.
failReasons.inactiveRisksCount.periodicAttackCount. Количество срабатываний риска неактивного PeriodicAttack.
failReasons.inactiveRisksCount.missingMetadataCount. Количество срабатываний риска неактивного MissingMetadata.
failReasons.inactiveRisksCount.untrustedIpCount. Количество срабатываний риска неактивного UntrustedIp.
failReasons.inactiveRisksCount.untrustedDeviceCount. Количество срабатываний риска неактивного UntrustedDevice.
failReasons.inactiveRisksCount.inconsistentMetadataCount. Количество срабатываний риска неактивного InconsistentMetadata.
failReasons.inactiveRisksCount.motionControlFailedCount. Количество срабатываний риска неактивного MotionControlFailed.
failReasons.activeRisksCount.massAttackRiskCount. Количество срабатываний риска активного MassAttack.
failReasons.activeRisksCount.duplicateFaceCount. Количество срабатываний риска активного DuplicateFace.
failReasons.activeRisksCount.periodicAttackCount. Количество срабатываний риска активного PeriodicAttack.
failReasons.activeRisksCount.missingMetadataCount. Количество срабатываний риска активного MissingMetadata.
failReasons.activeRisksCount.untrustedIpCount. Количество срабатываний риска активного UntrustedIp.
failReasons.activeRisksCount.untrustedDeviceCount. Количество срабатываний риска активного UntrustedDevice.
failReasons.activeRisksCount.inconsistentMetadataCount. Количество срабатываний риска активного InconsistentMetadata.
failReasons.activeRisksCount.motionControlFailedCount. Количество срабатываний риска активного MotionControlFailed.

Создание отчёта

При создании отчёта необходимо указать временные рамки получения метрик. Время необходимо указывать в часовом поясе UTC.

Эндпоинт: POST /publicapi/api/v2/private/Report

Тело запроса:

{
  "startDate": "2024-11-19T11:09:44.530Z",
  "endDate": "2024-11-19T11:09:44.530Z"
}

Пример запроса:

curl -X 'POST' \
  'http://baf.ai/publicapi/api/v2/private/Report' \
  -H 'accept: text/plain' \
  -H 'Content-Type: application/json-patch+json' \
  -d '{
  "startDate": "2024-11-19T11:09:44.530Z",
  "endDate": "2024-11-19T11:09:44.530Z"
}'

Пример ответа:

Status Code

200

{
  "id": "d7b79e25-40e1-4aaa-a203-7ea77f5b6ef2",
  "reportInfo": {
    "nist": {
      "failRate": 0.5,
      "passRate": 0.5,
      "completion": 401,
      "fraudProofing": 0,
      "suspectedFraud": 0,
      "abandonmentRate": 0,
      "fraudAuthentication": 0,
      "authenticationFailures": 0.6666667
    },
    "registrationMetrics": {
      "applicantsAttemptToRegister": 2,
      "notRegisteredApplicantsSettledInRegAttempts": {
        "count": 0,
        "failReasons": {
          "inactiveRisksCount": {
            "massAttackRiskCount": 0,
            "untrustedIpRiskCount": 0,
            "duplicateFaceRiskCount": 0,
            "periodicAttackRiskCount": 0,
            "missingMetadataRiskCount": 0,
            "untrustedDeviceRiskCount": 0,
            "inconsistentMetadataRiskCount": 0,
            "motionControlFailedRiskCount": 0
          },
          "activeRisksCount": {
            "massAttackRiskCount": 0,
            "untrustedIpRiskCount": 0,
            "duplicateFaceRiskCount": 0,
            "periodicAttackRiskCount": 0,
            "missingMetadataRiskCount": 0,
            "untrustedDeviceRiskCount": 0,
            "inconsistentMetadataRiskCount": 0,
            "motionControlFailedRiskCount": 0
          },
          "validationFailuresCount": {
            "qualityFailedSum": 0,
            "faceMatchingFailedSum": 0,
            "lrCrossMatchFailedSum": 0,
            "mcCrossMatchFailedSum": 0,
            "oneFrameLivenessFailedSum": 0,
            "livenessReflectionFailedSum": 0
          }
        }
      },
      "notRegisteredApplicantsNotSettledInRegAttempts": {
        "count": 1,
        "failReasons": {
          "inactiveRisksCount": {
            "massAttackRiskCount": 0,
            "untrustedIpRiskCount": 0,
            "duplicateFaceRiskCount": 0,
            "periodicAttackRiskCount": 0,
            "missingMetadataRiskCount": 0,
            "untrustedDeviceRiskCount": 0,
            "inconsistentMetadataRiskCount": 0,
            "motionControlFailedRiskCount": 0
          },
          "activeRisksCount": {
            "massAttackRiskCount": 0,
            "untrustedIpRiskCount": 0,
            "duplicateFaceRiskCount": 0,
            "periodicAttackRiskCount": 0,
            "missingMetadataRiskCount": 0,
            "untrustedDeviceRiskCount": 0,
            "inconsistentMetadataRiskCount": 0,
            "motionControlFailedRiskCount": 0
          },
          "validationFailuresCount": {
            "qualityFailedSum": 0,
            "faceMatchingFailedSum": 0,
            "lrCrossMatchFailedSum": 3,
            "mcCrossMatchFailedSum": 2,
            "oneFrameLivenessFailedSum": 3,
            "livenessReflectionFailedSum": 1
          }
        }
      },
      "registeredApplicantsSettledInRegAttempts": {
        "count": 1,
        "failReasons": {
          "inactiveRisksCount": {
            "massAttackRiskCount": 0,
            "untrustedIpRiskCount": 0,
            "duplicateFaceRiskCount": 0,
            "periodicAttackRiskCount": 0,
            "missingMetadataRiskCount": 0,
            "untrustedDeviceRiskCount": 0,
            "inconsistentMetadataRiskCount": 0,
            "motionControlFailedRiskCount": 0
          },
          "activeRisksCount": {
            "massAttackRiskCount": 0,
            "untrustedIpRiskCount": 0,
            "duplicateFaceRiskCount": 0,
            "periodicAttackRiskCount": 0,
            "missingMetadataRiskCount": 0,
            "untrustedDeviceRiskCount": 0,
            "inconsistentMetadataRiskCount": 0,
            "motionControlFailedRiskCount": 0
          },
          "validationFailuresCount": {
            "qualityFailedSum": 0,
            "faceMatchingFailedSum": 0,
            "lrCrossMatchFailedSum": 0,
            "mcCrossMatchFailedSum": 0,
            "oneFrameLivenessFailedSum": 0,
            "livenessReflectionFailedSum": 0
          }
        }
      },
      "registeredApplicantsNotSettledInRegAttempts": {
        "count": 0,
        "failReasons": {
          "inactiveRisksCount": {
            "massAttackRiskCount": 0,
            "untrustedIpRiskCount": 0,
            "duplicateFaceRiskCount": 0,
            "periodicAttackRiskCount": 0,
            "missingMetadataRiskCount": 0,
            "untrustedDeviceRiskCount": 0,
            "inconsistentMetadataRiskCount": 0,
            "motionControlFailedRiskCount": 0
          },
          "activeRisksCount": {
            "massAttackRiskCount": 0,
            "untrustedIpRiskCount": 0,
            "duplicateFaceRiskCount": 0,
            "periodicAttackRiskCount": 0,
            "missingMetadataRiskCount": 0,
            "untrustedDeviceRiskCount": 0,
            "inconsistentMetadataRiskCount": 0,
            "motionControlFailedRiskCount": 0
          },
          "validationFailuresCount": {
            "qualityFailedSum": 0,
            "faceMatchingFailedSum": 0,
            "lrCrossMatchFailedSum": 0,
            "mcCrossMatchFailedSum": 0,
            "oneFrameLivenessFailedSum": 0,
            "livenessReflectionFailedSum": 0
          }
        }
      }
    }
  },
  "status": 2,
  "accountId": "28608d66-a571-44ec-94db-04a00143ff51",
  "startDate": "2025-01-31T19:00:00Z",
  "endDate": "2025-02-08T18:59:59Z",
  "creationDate": "2025-02-04T08:26:26.774871Z",
  "lastModified": "2025-02-04T08:26:26.922604Z"
}

Получение отчётов

Для получения отчётов постранично нужно указать номер страницы и её размер.

Эндпоинт: GET /publicapi/api/v2/private/Report

Параметры:

Название поля	Описание	Значение
Page	Номер страницы	От 1 до 2147483647
PageSize	Максимальное количество отчётов на странице	От 1 до 400

Пример запроса:

curl -X 'GET' \
  'http://baf.ai/publicapi/api/v2/private/Report?Page=1&PageSize=10' \
  -H 'accept: text/plain' \
  -H 'Authorization: Bearer sk_1d2ca11d-125a-416c-8fdc-e9661ebecb9a'

Пример ответа:

Status Code

200

{
  "totalCount": 2,
  "reports": [
    {
      "id": "a86b6b35-cf6b-462d-9f64-d706cd2490ce",
      "reportInfo": null,
      "status": 0,
      "accountId": "28608d66-a571-44ec-94db-04a00143ff51",
      "startDate": "2024-11-15T06:27:42.706Z",
      "endDate": "2024-11-15T06:27:42.706Z",
      "creationDate": "2024-11-15T06:27:42.231705Z",
      "lastModified": "2024-11-15T06:27:42.231705Z"
    },
    {
      "id": "d7b79e25-40e1-4aaa-a203-7ea77f5b6ef2",
      "reportInfo": {
        "nist": {
          "failRate": 0.5,
          "passRate": 0.5,
          "completion": 401,
          "fraudProofing": 0,
          "suspectedFraud": 0,
          "abandonmentRate": 0,
          "fraudAuthentication": 0,
          "authenticationFailures": 0.6666667
        },
        "registrationMetrics": {
          "applicantsAttemptToRegister": 2,
          "notRegisteredApplicantsSettledInRegAttempts": {
            "count": 0,
            "failReasons": {
              "inactiveRisksCount": {
                "massAttackRiskCount": 0,
                "untrustedIpRiskCount": 0,
                "duplicateFaceRiskCount": 0,
                "periodicAttackRiskCount": 0,
                "missingMetadataRiskCount": 0,
                "untrustedDeviceRiskCount": 0,
                "inconsistentMetadataRiskCount": 0,
                "motionControlFailedRiskCount": 0
              },
              "activeRisksCount": {
                "massAttackRiskCount": 0,
                "untrustedIpRiskCount": 0,
                "duplicateFaceRiskCount": 0,
                "periodicAttackRiskCount": 0,
                "missingMetadataRiskCount": 0,
                "untrustedDeviceRiskCount": 0,
                "inconsistentMetadataRiskCount": 0,
                "motionControlFailedRiskCount": 0
              },
              "validationFailuresCount": {
                "qualityFailedSum": 0,
                "faceMatchingFailedSum": 0,
                "lrCrossMatchFailedSum": 0,
                "mcCrossMatchFailedSum": 0,
                "oneFrameLivenessFailedSum": 0,
                "livenessReflectionFailedSum": 0
              }
            }
          },
          "notRegisteredApplicantsNotSettledInRegAttempts": {
            "count": 1,
            "failReasons": {
              "inactiveRisksCount": {
                "massAttackRiskCount": 0,
                "untrustedIpRiskCount": 0,
                "duplicateFaceRiskCount": 0,
                "periodicAttackRiskCount": 0,
                "missingMetadataRiskCount": 0,
                "untrustedDeviceRiskCount": 0,
                "inconsistentMetadataRiskCount": 0,
                "motionControlFailedRiskCount": 0
              },
              "activeRisksCount": {
                "massAttackRiskCount": 0,
                "untrustedIpRiskCount": 0,
                "duplicateFaceRiskCount": 0,
                "periodicAttackRiskCount": 0,
                "missingMetadataRiskCount": 0,
                "untrustedDeviceRiskCount": 0,
                "inconsistentMetadataRiskCount": 0,
                "motionControlFailedRiskCount": 0
              },
              "validationFailuresCount": {
                "qualityFailedSum": 0,
                "faceMatchingFailedSum": 0,
                "lrCrossMatchFailedSum": 3,
                "mcCrossMatchFailedSum": 2,
                "oneFrameLivenessFailedSum": 3,
                "livenessReflectionFailedSum": 1
              }
            }
          },
          "registeredApplicantsSettledInRegAttempts": {
            "count": 1,
            "failReasons": {
              "inactiveRisksCount": {
                "massAttackRiskCount": 0,
                "untrustedIpRiskCount": 0,
                "duplicateFaceRiskCount": 0,
                "periodicAttackRiskCount": 0,
                "missingMetadataRiskCount": 0,
                "untrustedDeviceRiskCount": 0,
                "inconsistentMetadataRiskCount": 0,
                "motionControlFailedRiskCount": 0
              },
              "activeRisksCount": {
                "massAttackRiskCount": 0,
                "untrustedIpRiskCount": 0,
                "duplicateFaceRiskCount": 0,
                "periodicAttackRiskCount": 0,
                "missingMetadataRiskCount": 0,
                "untrustedDeviceRiskCount": 0,
                "inconsistentMetadataRiskCount": 0,
                "motionControlFailedRiskCount": 0
              },
              "validationFailuresCount": {
                "qualityFailedSum": 0,
                "faceMatchingFailedSum": 0,
                "lrCrossMatchFailedSum": 0,
                "mcCrossMatchFailedSum": 0,
                "oneFrameLivenessFailedSum": 0,
                "livenessReflectionFailedSum": 0
              }
            }
          },
          "registeredApplicantsNotSettledInRegAttempts": {
            "count": 0,
            "failReasons": {
              "inactiveRisksCount": {
                "massAttackRiskCount": 0,
                "untrustedIpRiskCount": 0,
                "duplicateFaceRiskCount": 0,
                "periodicAttackRiskCount": 0,
                "missingMetadataRiskCount": 0,
                "untrustedDeviceRiskCount": 0,
                "inconsistentMetadataRiskCount": 0,
                "motionControlFailedRiskCount": 0
              },
              "activeRisksCount": {
                "massAttackRiskCount": 0,
                "untrustedIpRiskCount": 0,
                "duplicateFaceRiskCount": 0,
                "periodicAttackRiskCount": 0,
                "missingMetadataRiskCount": 0,
                "untrustedDeviceRiskCount": 0,
                "inconsistentMetadataRiskCount": 0,
                "motionControlFailedRiskCount": 0
              },
              "validationFailuresCount": {
                "qualityFailedSum": 0,
                "faceMatchingFailedSum": 0,
                "lrCrossMatchFailedSum": 0,
                "mcCrossMatchFailedSum": 0,
                "oneFrameLivenessFailedSum": 0,
                "livenessReflectionFailedSum": 0
              }
            }
          }
        }
      },
      "status": 2,
      "accountId": "28608d66-a571-44ec-94db-04a00143ff51",
      "startDate": "2025-01-31T19:00:00Z",
      "endDate": "2025-02-08T18:59:59Z",
      "creationDate": "2025-02-04T08:26:26.774871Z",
      "lastModified": "2025-02-04T08:26:26.922604Z"
    }
  ]
}

Удаление отчёта

Эндпоинт: DELETE /publicapi/api/v2/private/Report

Пример запроса:

curl -X 'DELETE' \
  'http://baf.ai/publicapi/api/v2/private/Report/3fa85f64-5717-4562-b3fc-2c963f66afa6' \
  -H 'accept: */*' \
  -H 'Authorization: Bearer sk_1d2ca11d-125a-416c-8fdc-e9661ebecb9a'

Пример ответа:

Status Code

200

Возможные ошибки:

HTTP статус	Сообщение	Описание	Код ошибки
404	Report not found	Отчёт для удаления не найден	120024

Получение информации об отчёте

Эндпоинт: GET /publicapi/api/v2/private/Report/{report_id}

Пример запроса:

curl -X 'GET' \
  'http://baf.ai/publicapi/api/v2/private/Report/3fa85f64-5717-4562-b3fc-2c963f66afa6' \
  -H 'accept: text/plain' \
  -H 'Authorization: Bearer sk_1d2ca11d-125a-416c-8fdc-e9661ebecb9a'curl -X 'GET'

Пример ответа:

Status Code

200

Возможные ошибки:

HTTP статус	Сообщение	Описание	Код ошибки
404	Report not found	Отчёт не найден	120024

Запуск построения отчёта

Эндпоинт: GET /publicapi/api/v2/private/Report/process/{report_id}

Пример запроса:

curl -X 'POST' \
  'http://baf.ai/publicapi/api/v2/private/Report/Process/3fa85f64-5717-4562-b3fc-2c963f66afa6' \
  -H 'accept: */*' \
  -H 'Authorization: Bearer sk_1d2ca11d-125a-416c-8fdc-e9661ebecb9a' \
  -d ''

Пример ответа:

Status Code

200

Возможные ошибки:

HTTP статус	Сообщение	Описание	Код ошибки
404	Report not found	Отчёт не найден	120024
400	Report already processing	Отчёт уже в процессе построения	120049
400	Too much simultaneously processed reports	Количество одновременно обрабатываемых отчётов достигло лимита	120049

Отмена построения отчёта

Эндпоинт: DELETE /publicapi/api/v2/private/Report/process/{report_id}

Пример запроса:

curl -X 'DELETE' \
  'http://baf.ai/publicapi/api/v2/private/Report/Process/3fa85f64-5717-4562-b3fc-2c963f66afa7' \
  -H 'accept: */*' \
  -H 'Authorization: Bearer sk_1d2ca11d-125a-416c-8fdc-e9661ebecb9a'

Пример ответа:

Status Code

200

Возможные ошибки:

HTTP статус	Сообщение	Описание	Код ошибки
400	This report not processing at this moment	Отчёт не находится в состоянии обработки	120049

Данные отчёта​

Раздел отчёта nist​

Раздел отчёта registrationMetrics​

Создание отчёта​

Получение отчётов​

Удаление отчёта​

Получение информации об отчёте​

Запуск построения отчёта​

Отмена построения отчёта​

Данные отчёта

Раздел отчёта nist

Раздел отчёта registrationMetrics

Создание отчёта

Получение отчётов

Удаление отчёта

Получение информации об отчёте

Запуск построения отчёта

Отмена построения отчёта