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

Этот раздел 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.deepfakeFailedSum. Количество провалов проверки DeepFake при регистрации.
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

Получение данных отчета в формате csv

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

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

curl -X 'GET' \
  'http:/baf.ai/publicapi/api/v2/private/Report/3fa85f64-5717-4562-b3fc-2c963f66afa6/Data' \
  -H 'accept: */*' \
  -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/{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​

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

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

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

Получение данных отчета в формате csv​

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

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

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

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

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

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

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

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

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

Получение данных отчета в формате csv

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

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

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