Перейти к основному содержимому

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

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

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

1. Создаётся отчёт, для которого нужно получить метрики за определённый промежуток времени.
2. Отчёт ставится в очередь на обработку.
3. После завершения обработки метрики из отчёта становятся доступными через 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