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

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

Этот раздел 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