# Действия пользователя

# Введение

Действия пользователя (англ. «action») — это отдельный процесс проверок, который выполняется независимо от основной верификации пользователя и не влияет на её результат. Проверку действий пользователя (actions) можно выбрать в настройках уровня верификации.

Проверку действий пользователя можно запускать при срабатывании определенных событий. Например, в ситуации когда нужно убедиться в том, что именно владелец аккаунта в данный момент пользуется учетной записью. В этом случае запускается действие пользователя «Авторизация по лицу».

В данный момент мы можем предложить вам следующие типы проверок действий пользователя:

• Авторизация по лицу Для успешного прохождения проверки лицо из селфи (liveness или фото с вебкамеры) должно совпадать с лицом из основной анкеты.
• Проверка электронной почты
• Проверка по источникам
• Прохождение опросника

# Настройка уровня верификации

Чтобы использовать действия пользователя (actions):

1. В Дешборд откройте страницу «Интеграция SDK», вкладка «Физические лица».
2. Нажмите «Создать уровень».
3. В разделе «Общие» в выпадающем списке «Процесс» выберите «Действия».
4. В разделе «Обязательные настройки» удалите все шаги проверки кроме «Селфи».
5. В выпадающем списке «Тип действия» выберите тип действия пользователя.
6. Завершите настройку уровня верификации и сохраните изменения.

Результаты проверки действий пользователя можно получить в анкете пользователя или через вебхуки.

# API-запросы для действий пользователя

# POST Создание действия пользователя

Используйте этот запрос, для того чтобы создать действия пользователя для определенной анкеты.

POST /resources/applicantActions/-/forApplicant/{applicantId}?levelName={levelName}

Параметры запроса

Query-параметры

Тело запроса

Пример

curl -X POST \     'https://api.cyberity.ru/resources/applicantActions/-/forApplicant/63e096c51b6b4030f2e01154?levelName=some-level-name' \
     -H 'Content-Type: application/json' \
     -d '{
          "externalActionId": "yourActionId",
          "email": "example@email.com",
          "phone": "+49 123456789"
        }'

curl -X POST \     'https://api.cyberity.ru/resources/applicantActions/-/forApplicant/63e096c51b6b4030f2e01154?levelName=questionnaire-level' \
     -H 'Content-Type: application/json' \
     -d '{
          "questionnaires": [
            {
              "id": "Example_Questionnaire",
              "sections": {
                "section_id_1": { // Section ID
                  "items": {
                    "item_id_0": { // Item ID
                      "values": [ // Item values
                        "EUR",
                        "USD"
                      ]
                    },
                    "item_id_1": { // Item ID
                      "value": "String Value", // Item values, string
                    }
                  }
                },
                "section_id_2": { // Section ID
                  "items": {
                    "item_id_3": { // Item ID
                      "value": null // Item values, null
                    }
                  }
                }
              }
            }
          }],
          "externalActionId": "yourActionId",
          "email": "example@email.com",
          "phone": "+49 123456789"
        }'

# POST Генерация внешней ссылки WebSDK для действия пользователя

POST /resources/sdkIntegrations/levels/{levelName}/websdkLink?externalUserId={externalUserId}&externalActionId={externalActionId}

Параметры запроса

Query-параметры

Ответ

Пример

curl -X POST \
  'https://api.cyberity.ru/resources/sdkIntegrations/levels/action-level/websdkLink?externalUserId=304775ty&externalActionId=actionID123'

{
    "url": "https://api.cyberity.ru/idensic/l/#/lPDnIKwzmxPfDohk"
}

# POST Добавление изображения в действие пользователя

Этот эндпоинт добавляет изображение к действию пользователя (например, фотографию лица для «Авторизации по лицу»).

POST /resources/applicantActions/{actionId}/images

Параметры запроса

Вы можете получить идентификатор действия пользователя при создании нового действия или при использовании запроса «GET Получение действий пользователя конкретной анкеты».

Заголовки запроса

Тело запроса

Поля элемента metadata

Ответ

Если запрос отправлен и обработан правильно, в ответе вы получите JSON-файл с информацией об изображении.

Поля элемента idDocDef

Пример

curl -X POST \
   'https://api.cyberity.ru/resources/applicantActions/5e022e0f0a975a45325c7ff5/images' \
    -H 'Content-Type: multipart/form-data' \
    -F 'metadata={"idDocType":"SELFIE","country":"GBR"}' \
    -F 'content=@/Sumsub/Example/name.jpg'

{
  "id": "66bb6c71546bfc57cffe92a8",
  "addedDate": "2024-08-13 14:23:45",
  "creatorClientId": "API",
  "imageHash": "64d2f3aa8da8a98fffaf751a9c323981474f6375",
  "imageFileName": "name.jpg",
  "resizedImageId": 603758274,
  "mimeType": "jpg",
  "sigHash": "3809bc3c-831d-4be3-8cee-1684553beffe",
  "imageId": 1411431805,
  "fileSize": 1362,
  "actualResolution": {
      "width": 192,
      "height": 192
  },
  "answer": "GREEN",
  "idDocDef": {
      "country": "GBR",
      "idDocType": "SELFIE"
  },
  "reviewResult": {},
  "attemptId": "teinm"
}

# POST Отправка действия пользователя на проверку

Используйте этот эндпоинт для запроса проверки действий пользователя. Статус проверки действия устанавливается как pending, после чего действие готово к обработке.

POST /resources/applicantActions/{actionId}/review/status/pending

Параметры запроса

Вы можете получить идентификатор действия пользователя при создании нового действия или при использовании запроса «GET Получение действий пользователя конкретной анкеты».

Пример

 curl -X POST \
  'https://api.cyberity.ru/resources/applicantActions/5e022e0f0a975a45325c7ff5/review/status/pending'

# GET Получение результата проверки действий пользователя

GET /resources/applicantActions/{actionId}/one

Параметры запроса

Вы можете получить идентификатор действия пользователя при создании нового действия или при использовании запроса «GET Получение действий пользователя конкретной анкеты».

Ответ

Поля элемента review

Поля элемента reviewResult

Пример

{
  // applicant action id - that's what you should get from WebSDK or MobileSDK
  "id" : "5d9f76507edd7d8162bfcea8",
  "createdAt" : "2019-10-10 18:20:00",
  "applicantId" : "5d9f74a27edd7d813405fe07",
  "type" : "selfieAuth",
  "review": {
    "reviewResult" : {
      "reviewAnswer" : "GREEN"
    },
  }
  // checks performed: liveness and comparison with the relevant document
  // NOTE: if liveness check didn't pass, we won't perform a face match check
  "checks" : [ {
    "answer" : "GREEN",
    "checkType" : "FACE_LIVELINESS",
    "createdAt" : "2019-10-10 18:19:57",
    "livenessInfo": {
      "livenessData": {
        "sessionId": "512deb48-bb6b-438c-ae7c-f8953351cc57",
        "images": [
          {
            "imageId": 1368276695
          },
          {
            "imageId": 1060469685
          },
          {
            "imageId": 2074791000
          },
          {
            "imageId": 810045545
          },
          {
            "imageId": 1328042852
          }
         ]
        },
        "livenessResult": {
          "answer": "GREEN",
          "glasses": false,
          "retryReason": 0
          }
        }
  },
  {
    "answer" : "GREEN",
    "checkType" : "FACE_MATCH",
    "createdAt" : "2019-10-10 18:20:00",
    "faceMatchInfo" : {
      "answer" : "GREEN",
    }
  } ]
}

# GET Получение действий пользователя конкретной анкеты

Для того чтобы получить список действий пользователя, которые принадлежат конкретной анкете, нужно воспользоваться этим эндпоинтом.

GET /resources/applicantActions/-;applicantId={applicantId}?limit={limit}&offset={offset}&order=-createdAt

Параметры запроса

Query-параметры

Ответ

Ответ представляет собой список действий пользователей и их общее количество. В элементе list содержится список действий пользователя, структура которых описана в разделе «GET Получение результата проверки действий пользователя».

Пример

curl -X GET \
  'https://api.cyberity.ru/resources/applicantActions/-;applicantId=5e5f9ab10a975a6e224dc286?limit=100&order=-createdAt'

{
  "list" : {
    "items" : [ {
      "id" : "5dd3f15704f9404c41307c85", // applicant action id
      "createdAt" : "2019-11-19 13:42:47",
      "applicantId" : "5dd3d58304f9404c412f1665",
      // ...
    }, {
      "id" : "5dd3d94153d4864d5aa98f21", // applicant action id
      "createdAt" : "2019-11-19 12:00:01",
      "applicantId" : "5dd3d58304f9404c412f1665",
      // ...
    } ],
    // total items (even if a limit is provided)
    "totalItems" : 213
  }
}

# GET Получение оригинального изображения

GET /resources/applicantActions/{actionId}/images/{imageId}?preview={isPreview}

Тело запроса

Query-параметры

# Действия пользователя в WebSDK

Инициализируйте WebSDK с externalActionId как это описано в разделах WebSDK и Начало работы.

Генерация токена доступа для действий пользователя:
POST /resources/accessTokens?userId={externalUserId}&externalActionId={externalActionId}&levelName={levelName}

Пример

curl -X POST \
  'https://api.cyberity.ru/resources/accessTokens?userId=JamesBond007&externalActionId=JamesBond007Action1&levelName=action-liveness&ttlInSecs=600' \
  -H 'Accept: application/json'

{
  "token": "_act-80bbf59b-98e6-4aa5-9310-82f2df5fe211",
  "userId": "JamesBond007",
  "externalActionId": "JamesBond007Action1"
}

# Действия пользователя в Android SDK

Инициализируйте Android SDK с externalActionId как это описано в разделах Android SDK и Начало работы.

При обработке действия «Авторизация по лицу» пользователь сразу попадает на экран FaceScan (Liveness), а после завершения проверки SDK автоматически закрывается.

val onSDKStateChangedHandler: (CBRSDKState, CBRSDKState) -> Unit = { newState, prevState ->
		Timber.d("onSDKStateChangedHandler: $prevState -> $newState")
		// Завершение процесса аутентификации по лицу
		if (newState is CBRSDKState.ActionCompleted) {
					val actionId = newState.actionId
					val type = newState.type
					val answer = newState.answer
					val payload = newState.payload
	}
}

CBRStateChangedHandler stateChangedHandler = (prevState, newState) -> {
	Timber.d("The SDK state was changed: " + prevState + " -> " + newState);
	// Завершение процесса аутентификации по лицу
	if (newState instanceof CBRSDKState.ActionCompleted) {
		CBRSDKState.ActionCompleted actionState = (CBRSDKState.ActionCompleted) newState;
		String actionId = actionState.getActionId();
		FlowActionType type = actionState.getType();
		String answer = actionState.getAnswer();
		Map<String, Object> payload = actionState.getPayload();
	}
};

# Уведомление о результате действий (actions)

Для получения результата действия (actions) и управления процессом действия можно использовать этот обработчик.

Обработчик принимает два параметра:

• actionId : String — ID действия.
• answer : String — ответ модуля проверки живости. Возможные значения:
  • GREEN
  • YELLOW
  • RED
  • ERROR
  • null

Обработчик должен вернуть CBRActionResult. Поддерживаются следующие значения:

• CBRActionResult.Continue — продолжить сценарий действия по умолчанию (показать экран результата и т. д.).
• CBRActionResult.Cancel — отменить сценарий действия по умолчанию (закрыть SDK без экрана результата).

val onActionResultHandler: CBRActionResultHandler = object : CBRActionResultHandler {
		override fun onActionResult(actionId: String, actionType: String, answer: String?, allowContinuing: Boolean): CBRActionResult {
				Timber.d("Face Auth action result: actionId: $actionId answer: $answer")
				// Используем стандартный сценарий
				return CBRActionResult.Continue
		}
}
val cbrSdk = CBRMobileSDK.Builder(this).withActionResultHandler(onActionResult)

CBRActionResultHandler actionResultHandler = (actionId, actionType, answer, allowContinuing) -> {
	Timber.d("Action Result: actionId: " + actionId + ", answer: " + answer);
	return CBRActionResult.Continue;
};

CBRMobileSDK.SDK cbrSdk = new CBRMobileSDK.Builder(requireActivity()).withActionResultHandler(actionResultHandler).build();

# Действия пользователя в iOS SDK

Инициализируйте iOS SDK с externalActionId как это описано в разделах iOS SDK и Начало работы.

Действия «Авторизация по лицу» обрабатываются следующим образом:

• При обработке действия «Авторизация по лицу» пользователь сразу попадает на экран FaceScan (Liveness), а после завершения проверки SDK автоматически закрывается.
• После завершения процесса свойство sdk.status устанавливается в значение .actionCompleted, а в sdk.actionResult содержится результат последнего выполненного действия.
• Чтобы определить статус SDK и получить результат действия, можно использовать один из следующих коллбэков: onDidDismiss, dismissHandler или onStatusDidChange.

sdk.onDidDismiss { (sdk) in
			switch sdk.status {
			case .failed:
					print("failReason: [\(sdk.description(for: sdk.failReason))] - \(sdk.verboseStatus)")
			case .actionCompleted:
			// the Face authentication action was performed or cancelled
					if let result = sdk.actionResult {
							print("Face Auth action result: actionId=\(result.actionId) answer=\(result.answer ?? "<none>")")
					} else {
							print("Face Auth action was cancelled")
					}
			default:
					// in case of Face authentication action, the other statuses are not used for now,
					// but you could see them if the user closes the sdk before the level is loaded
					break
			}
}

# Уведомление о результате действий (actions)

Результат действия «Авторизация по лицу» представлен свойством sdk.actionResult, которое включает следующие поля:

Отсутствие sdk.actionResult означает, что пользователь отменил процесс прохождения проверки.

# Обработка результата проверки действия

Для действий «Авторизация по лицу» доступен необязательный обработчик actionResultHandler, который позволяет обработать результат после его получения с сервера. В этот момент пользователь видит экран обработки (Processing).

sdk.actionResultHandler { (sdk, result, onComplete) in
			print("Face Auth action result handler: actionId=\(result.actionId) answer=\(result.answer ?? "<none>")")
			// you are allowed to process the result asynchronously, just don't forget to call `onComplete` when you finish,
			// you could pass `.cancel` to force the user interface to close, or `.continue` to proceed as usual
			onComplete(.continue)
}

# Вебхуки

Типы вебхуков, которые мы отправляем, зависят от настроек в разделе «Панель разработчика».

Больше информации о вебхуках см. здесь.

Пример полезной нагрузки вебхуков

{
  "applicantId": "5dc158b109494c3cbf431e28",
  "applicantActionId": "5dc2d80ce3cc9b1c1e389c4c",
  "externalApplicantActionId": "id122424234-action-random-r7otyykndi",
  "inspectionId": "5dc158b109494c3cbf431e29",
  "applicantType": "individual",
  "correlationId": "req-8fbf5a81-339f-43b6-a9a7-290080e9039c",
  "externalUserId": "pid122424234",
  "type": "applicantActionPending",
  "reviewStatus": "completed",
  "createdAtMs": "2020-02-21 13:23:16.098"
}

{
  "applicantId" : "5dc158b109494c3cbf431e28",
  "applicantActionId" : "5dc2d80ce3cc9b1c1e389c4c",
  "externalApplicantActionId": "id122424234-action-random-r7otyykndi",
  "inspectionId" : "5dc158b109494c3cbf431e29",
  "correlationId" : "req-c9041677-e8dc-446b-ab8f-50b438a40aa8",
  "externalUserId" : "id122424234",
  // note the type of the webhook
  "type" : "applicantActionReviewed",
  "reviewResult" : {
    "reviewAnswer" : "GREEN"
  },
  "reviewStatus" : "completed",
  "createdAtMs": "2020-02-21 13:23:19.987"
}

{
  "applicantId": "5ea867a9772e27d66728c64b",
  "applicantActionId": "5ea867c2772e27d66728c64f",
  "inspectionId": "5ea867a9772e27d66728c64c",
  "correlationId": "req-2c3cce19-c723-4fd0-a2f2-527789f95bcc",
  "externalUserId": "random-4gguvx1oha",
  "type": "applicantActionOnHold",
  "reviewStatus": "init",
  "createdAtMs": "2020-04-28 18:16:09.888"
}