# API-запросы

# Введение

Прежде чем начать работу с API IDnGO, все клиенты должны пройти аутентификацию, как это описано в разделе Начало работы.

Все несовместимые изменения в API будут сопровождаться новой версией и не повлияют на существующие эндпоинты. Однако мы можем добавлять новые поля в JSON-ответы без предварительного уведомления или изменения версии API. Поэтому не рекомендуется использовать мапперы объектов в коде интеграции, так как они не смогут обработать неизвестные свойства.

# Аутентификация

# POST Генерация токена доступа

При инициализации SDK необходимо использовать токен доступа accessToken. Для его получения нужно отправить запрос:

POST /resources/accessTokens?userId={userId}&levelName={levelName}

Токен доступа для верификации пользователя имеет ограниченный доступ к API, например, он действителен только для одного пользователя и не может быть использован для других.

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

Параметр запроса userId должен быть уникальным и осмысленным. Это может быть внешний идентификатор пользователя в вашей системе или адрес электронной почты. Не генерируйте эти идентификаторы случайным образом, если только вы не проводите тестирование.

Ответ

Пример

curl -X POST \
'https://api.cyberity.ru/resources/accessTokens?userId=JamesBond007&levelName=basic-kyc-level&ttlInSecs=600' \
  -H 'Accept: application/json'

{
  "token": "_act-b8ebfb63-5f24-4b89-9c08-5bbabeec986e",
  "userId": "JamesBond007"
}

# Ошибки

# GET Проверка состояния API и обработка ошибок

Вы можете проверить рабочее состояние сервиса с помощью запроса, приведённого ниже. Ответ с HTTP-статусом 200 подтверждает доступность API.

Запрос должен быть авторизован с использованием заголовков, описанных в разделе Аутентификация.

GET /resources/status/api

Ответ

При ошибках API возвращает стандартные коды HTTP-статусов.

Ответ содержит тело в формате JSON с дополнительной информацией об ошибке.

Тело ответа

Пример

curl -X GET \
'https://api.cyberity.ru/resources/status/api'

{
  "description": "Error analyzing file, unsupported format or corrupted file",
  "code": 400,
  "correlationId": "req-5fd59b09-7f5e-41cd-a86b-38a4e6d57e08",
  "errorCode": 1004, // may be absent
  "errorName": "corrupted-file" // may be absent
}

# Коды ошибок

Не все ошибки содержат errorCode и errorName. Со временем мы будем добавлять коды для новых типов ошибок.

Если всё же не удается решить возникшую проблему, пожалуйста, свяжитесь с нами указав correlationId ошибки.

# Анкета пользователя

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

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

Чтобы создать анкету пользователя, используйте запрос:

POST /resources/applicants?levelName={levelName}

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

Тело запроса

Поля элементов fixedInfo и info

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

Пример

curl -X POST \
  'https://api.cyberity.ru/resources/applicants?levelName=basic-kyc-level' \
  -H 'Content-Type: application/json' \
  -d '{
          "externalUserId": "someUniqueUserId",
          "email": "john.smith@cyberity.ru",
          "phone": "+449112081223",
          "fixedInfo": {
              "country": "GBR",
              "placeOfBirth": "London"
          }
      }'

{
    "id": "5f80e6b7155a6336271e4677", //applicantId
    "createdAt": "2020-10-09 22:39:51",
    "clientId": "cyberityClient",
    "inspectionId": "5f80e6b7155a6336271e4678",
    "externalUserId": "someUniqueUserId",
    "fixedInfo": {
        "placeOfBirth": "London",
        "country": "GBR"
    },
    "email": "john.smith@cyberity.ru",
    "phone": "+449112081223",
    "requiredIdDocs": {
        "excludedCountries": [
            "PRK"
        ],
        "docSets": [
            {
                "idDocSetType": "IDENTITY",
                "types": [
                    "PASSPORT",
                    "DRIVERS",
                    "ID_CARD",
                    "RESIDENCE_PERMIT"
                ]
            },
            {
                "idDocSetType": "SELFIE",
                "types": [
                    "SELFIE"
                ],
                "videoRequired": "disabled"
            }
        ]
    },
    "review": {
        "reprocessing": false,
        "createDate": "2020-10-09 22:39:51+0000",
        "reviewStatus": "init"
    },
    "type": "individual"
}

# POST Изменение уровня верификации

Данный запрос позволяет сменить один уровень верификации пользователя (набор шагов для проверки) на другой. Это может понадобиться в случае, когда нужно добавить еще один шаг к проверке.

Пример: изначальный уровень требует для верификации только удостоверение личности и селфи, а вам необходимо получить подтверждение адреса проживания (PoA). В таком случае уровень меняется на тот, в котором присутствуют все нужные проверки: удостоверение личности, селфи и проверка адреса проживания.

POST /resources/applicants/{applicantId}/moveToLevel?name={levelName}

Если вы используете наши SDK, вы можете просто инициализировать его с подходящим levelName, и SDK изменит уровень автоматически.

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

Ответ

Будут выданы новые requiredIdDocs (список документов/селфи, необходимых для верификации) и levelName (название уровня).

Пример

Пример запроса с телом для изменения требуемого набора документов:

curl -X POST \
  'https://api.cyberity.ru/resources/applicants/5f80e6b7155a6336271e4677/moveToLevel?name=kyc-with-poa' \
  -H 'Content-Type: application/json' \

{
    "id": "5f80e6b7155a6336271e4677",
    "createdAt": "2020-10-09 22:47:58",
    "clientId": "cyberityClient",
    "inspectionId": "5f80e6b7155a6336271e4678",
    "externalUserId": "someUniqueUserId",
    "info": {
        "firstName": "John",
        "firstNameEn": "John",
        "lastName": "Smith",
        "lastNameEn": "Smith",
        "dob": "2000-03-04",
        "placeOfBirth": "London",
        "placeOfBirthEn": "London",
        "country": "GBR",
        "phone": "+449112081223"
    },
    "email": "john.smith@cyberity.ru",
    "requiredIdDocs": {
        "docSets": [
            {
                "idDocSetType": "IDENTITY",
                "types": [
                    "PASSPORT",
                    "DRIVERS",
                    "ID_CARD",
                    "RESIDENCE_PERMIT"
                ]
            },
            {
                "idDocSetType": "SELFIE",
                "types": [
                    "SELFIE"
                ],
                "videoRequired": "disabled"
            },
            {
                "idDocSetType": "PROOF_OF_RESIDENCE",
                "types": [
                    "UTILITY_BILL"
                ]
            }
        ]
    },
    "review": {
        "reprocessing": false,
        "levelName": "kyc-with-poa",
        "createDate": "2020-10-09 22:47:58+0000",
        "reviewStatus": "init"
    },
    "type": "individual"
}

# POST Получение текущих настроек уровня верификации

Если вы хотите получить список необходимых для верификации документов/селфи (requiredIdDocs), используйте эндпоинт:

POST /resources/applicants/{applicantId}/requiredIdDocs

Пример

curl -X POST \
  'https://api.cyberity.ru/resources/applicants/5f80e6b7155a6336271e4677/requiredIdDocs' \
  -H 'Content-Type: application/json'

# POST Добавление документа, удостоверяющего личность

Ответ на запрос включает в себя: метаданные документа JSON и, опционально, фотографию документа. Если документ с таким же типом метаданных и страной уже существует, их данные будут объединены, существующие данные будут перезаписаны, а новое изображение будет добавлено в анкету пользователя. Если метаданные документа еще неизвестны, отправьте нам тип (idDocType) и страну (country), эти два поля являются обязательными. Например, «PASSPORT» и «RUS».

POST /resources/applicants/{applicantId}/info/idDoc

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

Для добавления документов, подтверждающих адрес проживания (PoA), или удостоверения личности рекомендуется использовать заголовок X-Return-Doc-Warnings со значением true. Заголовок запроса позволяет определить, читаемы ли данные документа и подходят ли они прежде, чем переводить пользователя в статус ожидания (pending).

У некоторых типов документов idDocType данные располагаются на разных сторонах/разворотах (FRONT_SIDE и BACK_SIDE). Убедитесь, что отправили BACK_SIDE, если уже был отправлен FRONT_SIDE, иначе шаг верификации не будет завершен, и вы не сможете начать проверку. Если при загрузке одной из сторон документа возникает ошибка errors, оба изображения будут помечены как неактивные.

Так как это упрощенная и быстрая проверка, для некоторых типов документов она может не присылать ошибок, чтобы обеспечить лучшую конверсию.

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

Тело запроса

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

Если у документа две необходимых стороны/разворота, отправьте два изображения и правильно настройте idDocSubType (FRONT_SIDE и BACK_SIDE).

Ответ

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

JSON, содержащий дополнительную информацию о документе. В случае обнаружения проблем с изображением документа будет представлено сообщение из массива errors или warnings.

Идентификатор фотографии imageId, можно найти в заголовке ответа X-Image-Id.

Доступные значения массива errors

В случае получения ошибок (errors), загруженное изображение будет помечено как неактивное и не будет использоваться для верификации, нужно будет загрузить другое изображение, чтобы продолжить процесс проверки пользователя. Если при загрузке одной из сторон документа возникает ошибка errors, оба изображения будут помечены как неактивные.

Доступные значения массива warnings

Массив warnings предупреждает о том, что с документом может быть что-то не так.

Пример

curl -X POST \
  'https://api.cyberity.ru/resources/applicants/5b75a5e80a975a3ef2102a87/info/idDoc' \
  -H 'Content-Type: multipart/form-data' \
  -H 'X-Return-Doc-Warnings: true' \
  -F 'metadata={"idDocType":"PASSPORT","country":"USA"}' \
  -F 'content=@/cyberity/Example/name.jpg'

{
  "idDocType": "PASSPORT",
  "country": "USA",
  "errors": [ "dataNotReadable" ] // will be absent in case of X-Return-Doc-Warnings not having value of "true"
}

В случаях, когда необходимо загрузить только данные документа:

curl -X POST \
  'https://api.cyberity.ru/resources/applicants/5b75a5e80a975a3ef2102a87/info/idDoc' \
  -H 'Content-Type: multipart/form-data' \
  -F 'metadata={
  "idDocType": "PASSPORT",
  "country": "GBR",
  "number": "123456789",
  "issuedDate": "2015-01-02",
  "dob": "2000-02-01",
  "placeOfBirth": "London"
}'

{
  "idDocType": "PASSPORT",
  "country": "GBR",
  "issuedDate": "2015-01-02",
  "number": "40111234567",
  "dob": "2000-02-01",
  "placeOfBirth": "London"
}

# GET Получение данных о пользователе

В процессе верификации мы извлекаем данные из документов, удостоверяющих личность пользователя.

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

GET /resources/applicants/{applicantId}/one

или, если вы не знаете applicantId, используйте:

GET /resources/applicants/-;externalUserId={externalUserId}/one

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

Ответ

В ответе приходят данные анкеты пользователя, которая была создана вами или SDK, с дополнительной информацией в случаях, когда верификация была завершена. Массив объектов info.idDocs[] содержит информацию, извлеченную из документов пользователя. Наличие определенных полей зависит от документов, которые отправили на проверку, а также от правил верификации.

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

Чтобы убедиться, что данные были получены из актуального документа, проверьте, какие idDocType и country были одобрены при помощи этого эндпоинта.

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

# Основные поля ответа:

Поля элементов fixedInfo и info

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

Пример

curl -X GET \
  'https://api.cyberity.ru/resources/applicants/5b594ade0a975a36c9349e66/one'

{
  "id": "5b594ade0a975a36c9349e66",
  "createdAt": "2020-06-24 05:05:14",
  "clientId": "ClientName",
  "inspectionId": "5b594ade0a975a36c9379e67",
  "externalUserId": "SomeExternalUserId",
  "fixedInfo": {
    "firstName": "Chris",
    "lastName": "Smith"
  },
  "info": {
    "firstName": "CHRISTIAN",
    "firstNameEn": "CHRISTIAN",
    "lastName": "SMITH",
    "lastNameEn": "SMITH",
    "dob": "1989-07-16",
    "country": "DEU",
    "idDocs": [
      {
        "idDocType": "ID_CARD",
        "country": "DEU",
        "firstName": "CHRISTIAN",
        "firstNameEn": "CHRISTIAN",
        "lastName": "SMITH",
        "lastNameEn": "SMITH",
        "validUntil": "2028-09-04",
        "number": "LGXX359T8",
        "dob": "1989-07-16",
        "mrzLine1": "IDD<<LGXX359T88<<<<<<<<<<<<<<<",
        "mrzLine2": "8907167<2809045D<<<<<<<<<<<<<8",
        "mrzLine3": "SMITH<<CHRISTIAN<<<<<<<<<<<<<<"
      }
    ]
  },
  "agreement": { //present when WebSDK was initialized with Agreement screen enabled
    "createdAt": "2020-06-24 04:18:40",
    "source": "WebSDK",
    "targets": [
      "By clicking Next, I accept [the Terms and Conditions](https://www.cyberity.ru/consent-to-personal-data-processing/)",
      "I agree to the processing of my personal data, as described in [the Consent to Personal Data Processing](https://cyberity.ru/consent-to-personal-data-processing/)"
    ]
  },
  "email": "christman1@gmail.com",
  "applicantPlatform": "Android",
  "requiredIdDocs": {
    "docSets": [
      {
        "idDocSetType": "IDENTITY",
        "types": [
          "PASSPORT",
          "ID_CARD"
        ]
      },
      {
        "idDocSetType": "SELFIE",
        "types": [
          "SELFIE"
        ]
      }
    ]
  },
  "review": {
    "elapsedSincePendingMs": 115879,
    "elapsedSinceQueuedMs": 95785,
    "reprocessing": true,
    "levelName": "basic-kyc",
    "createDate": "2020-06-24 05:11:02+0000",
    "reviewDate": "2020-06-24 05:12:58+0000",
    "reviewResult": {
      "reviewAnswer": "GREEN"
    },
    "reviewStatus": "completed"
  },
  "lang": "de",
  "type": "individual"
}

# PATCH Изменение предоставленной информации (fixedInfo)

В fixedInfo вы можете передавать информацию о пользователе, которую необходимо сверить с полученными из документов данными. Эту информацию мы не можем редактировать самостоятельно, поэтому, если вы хотите изменить данные, которые вы нам предоставили, используйте метод PATCH.

PATCH /resources/applicants/{applicantId}/fixedInfo

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

Доступные атрибуты fixedInfo можно увидеть здесь.

Пример

curl -X PATCH \
  'https://api.cyberity.ru/resources/applicants/609d68bf460647000aa2d87e/fixedInfo' \
  -H 'Content-Type: application/json' \
  -d '{
        "firstName" : "Bradley",
        "lastName" : "Peak",
        "dob" : "1990-01-01"
      }'

# POST Запрос проверки пользователя

Автоматическое изменение статуса на pending работает только в наших SDK, поэтому как только все необходимые документы и данные будут загружены в анкету, сообщите системе, что пользователь готов к верификации. Запрос проверки пользователя также может понадобиться, если вам нужно запросить у нас повторную проверку пользователя.

С помощью данного эндпоинта вы можете перевести анкету пользователя в статус pending.

POST /resources/applicants/{applicantId}/status/pending?reason={reason}

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

Если возможно, укажите причину изменения статуса reason. Это поможет нам улучшить качество сервиса, мы можем автоматизировать этот процесс или, например, выполнять несколько дополнительных проверок.

Ответ

В случае получения HTTP-ответа 200 вы можете не обращать внимания на его тело.

Пример

curl -X POST \
  'https://api.cyberity.ru/resources/applicants/5b73b82f0a975a3b46429758/status/pending?reason=someReason'

{
  "ok": 1
}

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

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

GET /resources/inspections/{inspectionId}/resources/{imageId}

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

Ответ

Двоичное содержимое, представляющее собой изображение, заголовок Content-Type точно описывает медиа-тип ответа.

Пример

curl -X GET \
  'https://api.cyberity.ru/resources/inspections/5bb8cca10a975a624903cf66/resources/551262049'

# POST Добавление пользователя в черный список

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

POST /resources/applicants/{applicantId}/blacklist

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

Ответ

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

Пример

curl -X POST \
  'https://api.cyberity.ru/resources/applicants/5c0e93c30a975a53a79aa54b/blacklist?note=A%20user%20provided%20a%20fake%20document'

{
  "id": "5bb8563c0a975a5e6b322ecc",
  "createdAt": "2018-10-06 06:29:16",
  "clientId": "cyberityClient",
  "inspectionId": "5bb8563c0a975a5e6b322ecd",
  "externalUserId": "someClientUserId",
  "info": {
    "firstName": "John",
    "lastName": "Smith",
    "dob": "2000-03-04",
    "placeOfBirth": "London",
    "country": "GBR",
    "phone": "+449112081223"
  },
  "requiredIdDocs": {
    "docSets": [
      {
        "idDocSetType": "IDENTITY",
        "types": ["PASSPORT", "ID_CARD", "DRIVERS"]
      }
    ]
  },
  "review": {
    "createDate": "2018-12-10 16:26:45+0000",
    "reviewDate": "2018-12-10 16:27:29+0000",
    "reviewResult": {
      "reviewAnswer": "RED",
      "rejectLabels": ["BLOCKLIST"],
      "reviewRejectType": "FINAL"
    },
    "reviewStatus": "completed"
  }
}

# POST Сброс одного из шагов верификации

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

Обратите внимание, что не все шаги верификации можно сбросить с помощью описанного ниже запроса.

POST /resources/applicants/{applicantId}/resetStep/{idDocSetType}

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

Шаги верификации

Пример

curl -X POST \
  'https://api.cyberity.ru/resources/applicants/62164ddf8a86e20bbd28ab75/resetStep/PHONE_VERIFICATION'

{
  "ok": 1
}

# POST Сброс анкеты пользователя

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

POST /resources/applicants/{applicantId}/reset

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

Пример

curl -X POST \
  'https://api.cyberity.ru/resources/applicants/5d6f821b0a975a0b8aa27b27/reset'

{
  "ok": 1
}

# PATCH Изменение информации верхнего уровня

Этот запрос исправляет информацию верхнего уровня о пользователе, такую как email, externalUserId, sourceKey, type. Тело запроса должно содержать только те поля, которые вы собираетесь изменить. Отсутствующие поля будут проигнорированы.

PATCH /resources/applicants

Тело запроса

Пример

curl -X PATCH \
    'https://api.cyberity.ru/resources/applicants' \
    -H 'Content-Type: application/json' \
    -d '{"id":"5e9ad53d0a975a656d67e4d0","externalUserId":"1983114","email":"new@email.nz"}'

{
  "id": "5e9ad53d0a975a656d67e4d0",
  "createdAt": "2020-04-18 10:23:57",
  "inspectionId": "5e9ad53d0a975a656d67e4d1",
  "externalUserId": "1983114",
  "email": "new@email.nz",
  "requiredIdDocs": {
    "docSets": [
      {
        "idDocSetType": "IDENTITY",
        "types": [
          "ID_CARD",
          "PASSPORT",
          "DRIVERS"
        ]
      },
      {
        "idDocSetType": "SELFIE",
        "types": [
          "SELFIE"
        ],
        "videoRequired": "liveness"
      }
    ]
  },
  "review": {
    "createDate": "2020-04-18 10:25:53+0000",
    "expireDate": "2020-04-18 10:40:53+0000",
    "reviewStatus": "init"
  },
  "lang": "en",
  "type": "individual"
}

# POST Импорт пользователей

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

POST /resources/applicants/-/ingestCompleted?levelName={levelName}

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

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

Пример

curl -X POST 'https://api.cyberity.ru/resources/applicants/-/ingestCompleted?levelName=basic-kyc-level' \
  -H 'Content-Type: application/json' \
  -d '{
	  "externalUserId": "someClientUserId",
	  "info": {
		"firstName": "John",
		"lastName": "Snow",
		"country": "GBR"
	  },
	  "review": {
		"elapsedSincePendingMs": 100,
		"elapsedSinceQueuedMs": 50,
		"createDate": "2020-10-21 08:25:32+0000",
		"reviewDate": "2020-10-21 08:25:36+0000",
		"reviewResult": {
			"moderationComment": "",
			"clientComment": "",
			"reviewAnswer": "GREEN"
		},
		"reviewStatus": "completed"
	  }
  }'

{
  "id": "5f0864923cc18175d35bf1aa",
  "createdAt": "2020-07-10 12:52:34",
  "key": "QJZKBRIYUSBBWY",
  "clientId": "yourclientid",
  "inspectionId": "5f0864923cc18175d35bf1ab",
  "externalUserId": "someClientUserId",
  "info": {
    "firstName": "John",
    "lastName": "Snow"
  },
  "requiredIdDocs": {
    "docSets": [{
      "idDocSetType": "IDENTITY",
      "types": [
        "PASSPORT",
        "ID_CARD",
        "DRIVERS"
      ]
    }]
  },
  "review": {
    "elapsedSincePendingMs": 100,
    "elapsedSinceQueuedMs": 50,
    "createDate": "2019-10-21 08:25:32+0000",
    "reviewDate": "2019-10-21 08:25:36+0000",
    "reviewResult": {
      "moderationComment": "",
      "clientComment": "",
      "reviewAnswer": "GREEN"
    },
    "reviewStatus": "completed",
    "levelName": "basic-kyc-level"
  },
  "lang": "en",
  "type": "individual"
}

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

Этот запрос позволяет вам задать уровень риска для пользователя по вашим собственным критериям.

POST /resources/applicants/{applicantId}/riskLevel/entries

Тело запроса

Пример

curl -X POST 'https://api.cyberity.ru/resources/applicants/5edbe3460a975a259dd2f993/riskLevel/entries' \
  -H 'Content-Type: application/json' \
  -d '{"comment":"Danger!","riskLevel":"high"}'

{
  "riskLevel": "high",
  "entries": [
    {
      "id": "5eda11960a975a6de48b5c08",
      "createdAt": "2020-06-05 09:34:14",
      "comment": "Danger!",
      "riskLevel": "high"
    }
  ]
}

# POST Добавление тегов для пользователя

Используйте этот эндпоинт для присвоения пользовательских тегов профилям пользователей. Создать теги можно в разделе «Глобальные настройки» Дешборда.

POST /resources/applicants/{applicantId}/tags

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

Пример

curl -X POST 'https://api.cyberity.ru/resources/applicants/5fd1012c885b5d0009d50e6e/tags' \
  -H 'Content-Type: application/json' \
  -d '["Approved Sanctions", "Approved PEP", "821"]'

{
    "ok": 1
}

# DELETE Пометка изображения как неактивного (удаленного)

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

DELETE /resources/inspections/{inspectionId}/resources/${imageId}

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

Query-параметры

Ответ

В случае получения HTTP-ответа 200 вы можете не обращать внимания на его тело.

Пример

curl -X DELETE \
  'https://api.cyberity.ru/resources/inspections/5f649369aee05c75ea54c80a/resources/1045510331'

{
  "ok": 1
}

# Результаты проверки

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

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

GET /resources/applicants/{applicantId}/status

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

Ответ

Доступные значения элемента ReviewStatus

Пример

curl -X GET \
  'https://api.cyberity.ru/resources/applicants/5b76df770a975a1404cbcb60/status'

{
  "createDate": "2018-10-06 12:47:57+0000",
  "reviewResult": {
    "moderationComment": "We could not verify your profile. Please contact support: support@cyberity.ru",
    "clientComment": "The submitted documents or means of payment belong to different people.",
    "reviewAnswer": "RED",
    "rejectLabels": ["INCONSISTENT_PROFILE", "GRAPHIC_EDITOR"],
    "reviewRejectType": "FINAL"
  },
  "reviewStatus": "completed"
}

# GET Получение статусов для отдельных шагов верификации (API)

Рекомендуется использовать этот запрос, если вы хотите получить результаты отдельных шагов проверки и комментарии к ним.

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

GET /resources/applicants/{applicantId}/requiredIdDocsStatus

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

Ответ

Ответ приходит в формате JSON, в котором содержится информация о прохождении шагов проверки. Каждый шаг содержит массив идентификаторов изображений (их может быть несколько, например, если было загружено две стороны).

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

Пример

curl -X GET \
  'https://api.cyberity.ru/resources/applicants/5bb8cca10a975a624903cf65/requiredIdDocsStatus'

{
  "IDENTITY": {
   // a step identifier
    "reviewResult": {
    // if exists, that means that a document was uploaded
      "moderationComment": "Please upload a photo of the front of your ID card.",
      "reviewAnswer": "RED"
    },
    "country": "LVA", // document country
    "idDocType": "ID_CARD", // specific document type for the step
    "imageIds": [122352326,34246467], // image IDs that represent a document
    //If imageIds array contains more than one element the first one would be front side and others - back sides
    "imageReviewResults": {
      "34246467": {
        "reviewAnswer": "GREEN"
      },
      "122352326": {
        "moderationComment": "Please upload a photo of the front of your ID card.", // A human-readable comment that can be shown to your end user
        "clientComment": "One side of the document is missing.",  //A human-readable comment that should not be shown to an end user, and is meant to be read by a client
        "reviewAnswer": "RED",
        "rejectLabels": ["DOCUMENT_PAGE_MISSING","FRONT_SIDE_MISSING"],
        "reviewRejectType": "RETRY"
      }
    }
  },
  "SELFIE": {
    "reviewResult": {
      "reviewAnswer": "GREEN"
    },
    "country": "LVA",
    "idDocType": "SELFIE",
    "imageIds": [181314576],
    "imageReviewResults": {
      "181314576": {
        "reviewAnswer": "GREEN"
      }
    }
  }
}

# GET Уточнение причины отказа

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

GET /resources/moderationStates/-;applicantId={applicantId}

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

Ответ

imagesStates и applicantState присутствуют в ответе только в том случае, если пользователь был отклонён.

Доступный buttonId

{
  "spam": [], //Загружено слишком много изображений
  "redCrypto": [], //Криптотранзакции с высоким рисковым рейтингом
  "blackCrypto": [], //Переданы некорректные параметры для проверки криптотранзакции
  "applicantDataMismatch": [],
  "regulationsViolations": [
    "age", //Возраст не соответствует требованиям
    "duplicate", //У пользователя уже есть одобренная анкета
    "wrongRegion", //Регион или страна входит в список исключённых
    "foreigner", //Страна проживания не совпадает со страной банковской карты
    "crime", //У пользователя есть судимости
    "poorDrivingSkills", //Водительский стаж не соответствует требованиям
    "poorFinancialPosition", //Финансовое положение не соответствует требованиям
    "fines", //Сумма штрафов не соответствует требованиям
    "deprivations", //Обнаружены факты изъятия документов
    "notAllowedToDrive", //У пользователя нет права на вождение (специальная настройка)
    "diffDocPersons", //Предоставлены документы разных людей
    "inconsistency", //Предоставленная информация не совпадает с данными в документах
    "docNotFound", //Данные документа не найдены в базах данных
    "countriesMismatch", //Страна проживания не совпадает со страной банковской карты
    "riskBankCard", //Банковская карта с высоким уровнем риска
    "highRiskProfile", //Высокий поведенческий риск
    "spam", //Загружено слишком много изображений
    "blacklist" //Данные пользователя найдены в глобальном блок-листе
    "blocklist" //Данные пользователя найдены в вашем локальном блок-листе
  ],
  "automaticRegulations": [
    "wrongRegion", //Регион или страна входит в список исключённых
    "wrongProvince", //Провинция входит в список исключённых
    "wrongCountry" //Страна входит в список исключённых
  ],
  "specificClientRequirements": [
    "age", //Возраст не соответствует требованиям
    "notAllowedToDrive", //У пользователя нет права на вождение
    "anotherDocument" //Документ не поддерживается по индивидуальным требованиям
  ],
  "kycBlacklisted": [
    "compromisedDoc", //Использован украденный или утекший документ
    "physicalForgery", //Фото физически подделанного документа
    "digitalForgery", //Фото документа с цифровыми правками
    "creditCardFraud", //Мошенничество с банковской картой
    "anotherPersonsDoc", //Использован документ другого человека
    "multipleRegistration", //Повторная регистрация
    "forcedRegistration", //Регистрация была выполнена под давлением
    "financialFraud", //Финансовое мошенничество
    "clientRules", //Индивидуальная причина отказа (задано клиентом)
    "virtualCam" //Во время проверки использовалась виртуальная камера
  ]
  "dataMismatch": [
    "fullName", //Полное имя в профиле отсутствует или указано с ошибкой
    "dateOfBirth", //Дата рождения в профиле отсутствует или указана с ошибкой
    "address", //Проблема с адресом в профиле
    "inconsistency" //Имя держателя банковской карты не совпадает с именем в документе
  ],
  "fraudulentPatterns": [
    "selfieMismatch", //Селфи не совпадает с фото в документе
    "fake", //Подозрение на мошенничество
    "blacklist", //Аккаунт подозревается в подделке — найден в глобальном блок-листе
    "blocklist", //Аккаунт подозревается в подделке — найден в вашем локальном блок-листе
    "highRiskProfile", //Высокий поведенческий риск
    "physicalForgery", //Загружена физически подделанная копия документа
    "wantedDocument", //Документ находится в списке разыскиваемых или утерянных
    "livenessForced", //Обнаружены следы принуждения пользователя
    "deepFake" //Попытка обойти проверку с помощью дипфейка
  ],
  "moreDocs": [
    "individual", //Не предоставлены все обязательные документы
    "additionalPages" //Требуются дополнительные страницы документа
  ],
  "compromisedPersons": [ //Обнаружено совпадение с персоной из списков AML (подозрение подтверждено)
    "pep",
    "sanctionList",
    "criminalRecords",
    "adverseMedia"
  ],
  "company": [
    "moreDocs", //Не предоставлены все обязательные документы компании
    "notDeterminedBeneficiaries", //Не удалось определить бенефициаров
    "controlStructureIsNotEstablished",
    "notValidatedBeneficiaries", //Бенефициары не прошли проверку
    "notDeterminedRepresentatives", //Не удалось определить представителей
    "notValidatedRepresentatives", //Представители не прошли проверку
    "additionalInfo" //Требуется дополнительная информация о компании
  ],
  "checks": [
    "noInfoForChecks"
  ],
  "additionalPages": [ //Требуются дополнительные страницы или стороны документа
    "anotherSide",
    "frontSideId",
    "backSideId",
    "frontSideDl",
    "backSideDl",
    "frontSideTranslation",
    "backSideTranslation",
    "frontSideRp",
    "backSideRp",
    "mainPageId",
    "frontSideForeignId",
    "backSideForeignId",
    "localId",
    "registrationStamp",
    "2-3_IdDocPages",
    "4-5_IdDocPages",
    "6-7_IdDocPages",
    "8-9_IdDocPages",
    "10-11_IdDocPages",
    "12-13_IdDocPages",
    "30-31_IdDocPages",
    "selfie",
    "passport",
    "proofOfAddress",
    "birthCertificate"
  ],
  "badDocument": [ //Предоставлен неподходящий документ
    "expiredId", //Истек срок действия документа
    "invalidId", //Недействительный документ
    "damagedId", //Документ повреждён
    "notFullNameOrDob", //В документе отсутствует полное имя и/или дата рождения
    "withoutFace", //Лицо в документе плохо видно
    "dataNotVisible", //Необходимые данные документа не видны
    "copyOfIdDoc", //Предоставлена копия документа
    "noStamp", //Печать не видна
    "wrongType", //TТип документа не поддерживается или не принимается
    "unsigned", //Документ не подписан
    "needTranslation", //Требуется перевод документа на английский язык
    "fake", //Недостоверное удостоверение личности
    "expirationDate", //Документ должен быть действителен минимум 1 месяц после загрузки
    "inconsistency" //Имя владельца банковской карты не совпадает с именем в документе
  ],
  "badPhoto": [
    "lowQuality", //Низкое качество изображения
    "screenshot", //Загружен скриншот
    "blackAndWhite", //Требуется цветное фото или скан
    "imageEditor", //Обнаружено использование графического редактора
    "incomplete", //Все углы документа должны быть видны
    "notAPhoto", //Фото было преобразовано в PDF
    "idOnly", //Требуется только документ, удостоверяющий личность
    "faceNotFound",
    "fullDoublePage", //Разворот документа виден не полностью
    "frontSideId", //Требуется главный разворот документа
    "backSideId", //Требуется обратный разворот документа
    "frontSideDl", //Требуется лицевая сторона ВУ
    "backSideDl", //Требуется обратная сторона ВУ
    "mainIdDocPage",
    "2-3_IdDocPages",
    "4-5_IdDocPages",
    "6-7_IdDocPages",
    "frontSideNationalDl",
    "backSideNationalDl",
    "dataNotVisible", //Необходимые данные документа не видны
    "pdfFonts", //Обнаружены следы редактирования изображения
    "sticker", //Личная информация скрыта с помощью графического редактора
    "cardRequirements"
  ],
  "proofOfIdentity": [
    "passport", //Запрошен паспорт
    "idCard", //Запрошена ID-карта
    "drivingLicence", //Запрошено водительское удостоверение
    "residencePermit" //Запрошен вид на жительство
  ],
  "selfie": [
    "lowQuality", //Запрошено новое селфи с лучшим качеством изображения
    "selfieWithId", //Запрошено селфи с удостоверением личности
    "selfieWithPassport",
    "selfieWithDl",
    "selfieWithAnotherId", //Запрошено селфи с другим документом
    "selfieWithNewId", //Запрошено селфи с новым удостоверением личности
    "selfiePaper", //Запрошено селфи с листом бумаги с сегодняшней датой
    "blackAndWhite", //Запрошено цветное фото
    "badFaceComparison", //Плохое сравнение лиц
    "avatarIssue",
    "freshSelfie", //Запрошено актуальное селфи с текущей датой.
    "selfieLiveness", //Запрошена повторная проверка на живость лица
    "customIssue"
  ],
  "videoSelfie": [
    "lowQuality",
    "videoWithoutFace",
    "spokenPhraseMismatch",
    "videoWithId", //Запрошено видео-селфи с документом
    "videoWithAnotherId",
    "videoWithNewId"
  ],
  "profileImage": [
    "lowQuality",
    "wrongPhoto"
  ],
  "proofOfAddress": [
    "fullName", //Запрошено подтверждение адреса с полным именем пользователя
    "fullAddress", //Требуется документ с подходящей датой выдачи
    "issueDate", //Запрошен подходящий документ, подтверждающий адрес
    "listOfDocs", //Истек срок действия документа
    "expirationDate",
    "dataMismatch",
    "sameDoc", //Один и тот же документ был предоставлен как удостоверение личности и как подтверждение адреса
    "certifiedForm", //Запрошена заверенная форма документа, подтверждающего адрес
    "notEnoughData",
    "countryMismatch"
  ],
  "proofOfPayment": [
    "bankCard", //Высокорисковая банковская карт
    "bankStatement", //Запрошена выписка из банка
    "e-wallet", //Запрошено подтверждение электронного кошелька
    "wireTransfer", //Запрошено подтверждение банковского перевода
    "bankAccount", //Отсутствует номер счёта
    "dataMismatch"
  ],
  "bankCard": [
    "fullNameIssue", //Карта без имени пользователя
    "highRisk",
    "expirationDate",
    "badCard",
    "specificCard",
    "noCard"
  ],
  "bankStatement": [
    "fullNameIssue", //Запрошена выписка с полным именем пользователя
    "numberMismatch", //Номер карты в выписке не совпадает с предоставленной картой
    "invalidIssueDate", //Запрошена выписка с подходящей датой выдачи
    "notEnoughData" //Отсутствуют номер счёта или номер карты
  ],
  "differentDocs": [
    "identityDoc",
    "paymentMethodDoc"
  ],
  "graphicEditor": [
    "frontSide",
    "backSide",
    "selfie"
  ],
  "fake": [
    "printed", //Распечатанная копия документа
    "editedMrz", //Отредактированные MRZ-данные
    "blacklisted", //Документ или способ оплаты в чёрном списке
    "editedId", //Отредактированы основные данные документа
    "forgedId", //Поддельный физический документ
    "webId", //Образец документа из интернета
    "fakePoa", //Недостоверное подтверждение адреса
    "editedPoa", //Отредактированные данные адреса
    "fakeSelfie" //Селфи с поддельным документом
  ],
  "paymentsIssues": [
    "bankStatement",
    "bankBook",
    "emailScreen",
    "webScreen",
    "dataScreen"
  ],
  "livenessIssues": [
    "livenessDifferentPeople", //Во время проверки на живость обнаружены разные лица
    "livenessBypassAttempt" //Попытка обойти проверку на живость
  ]
}

Пример

curl -X GET \
  'https://api.cyberity.ru/resources/moderationStates/-;applicantId=5eeb914604f940217bdbad05'

{
  "list": {
    "items": [
      {
        "id": "5eebac3dd5ea480a98d51b40",
        "applicantId": "5eeb914604f940217bdbad05",
        "key": "TFRRN1THCATLDW",
        "imagesStates": {
          "104037333": { //imageId
            "state": {
              "badPhoto": { //Unsatisfactory photo was submitted
                "value": true //buttonId is active
              },
              "badPhoto_imageEditor": { //Graphic editing software usage was detected
                "value": true
              }
            }
          },
          "885188054": {
            "state": {
              "badPhoto": {
                "value": true
              },
              "badPhoto_imageEditor": {
                "value": true
              }
            }
          },
          "1777063415": {
            "state": {
              "badPhoto": { //Unsatisfactory photo was submitted
                "value": true
              },
              "badPhoto_incomplete": { //Not all document edges are visible
                "value": true
              }
            }
          },
          "1054210547": {
            "state": {
              "badPhoto": {
                "value": true
              },
              "badPhoto_incomplete": {
                "value": true
              }
            }
          },
          "1234193281": {
            "state": {
              "badPhoto": {
                "value": true
              },
              "badPhoto_incomplete": {
                "value": true
              }
            }
          },
          "484169174": {
            "state": {
              "badPhoto": {
                "value": true
              },
              "badPhoto_imageEditor": {
                "value": true
              }
            }
          },
          "741138243": {
            "state": {
              "badPhoto": {
                "value": true
              },
              "badPhoto_incomplete": {
                "value": true
              }
            }
          },
          "2118922684": {
            "state": {
              "badPhoto": {
                "value": true
              },
              "badPhoto_imageEditor": {
                "value": true
              }
            }
          },
          "1719337639": {
            "state": {
              "badPhoto": {
                "value": true
              },
              "badPhoto_incomplete": {
                "value": true
              }
            }
          }
        },
        "applicantState": {
          "regulationsViolations_wrongRegion": { //User is from excluded region/country
            "value": false //buttonId is inactive
          },
          "regulationsViolations": {
            "value": false
          },
          "dataMismatch": {},
          "dataMismatch_address": {
            "value": false
          },
          "regulationsViolations_duplicate": {
            "value": false
          }
        }
      }
    ],
    "totalItems": 1
  }
}

# Тестирование API-интеграции

# POST Назначение результата проверки для пользователя в Тестовом окружении (Sandbox)

В Тестовом окружении (Sandbox) вы можете попробовать получить результаты проверки через вебхук applicantReviewed, но перед этим вам необходимо задать параметры проверки с помощью этого запроса.

POST /resources/applicants/{applicantId}/status/testCompleted

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

Тело запроса

Ответ

В случае получения HTTP-ответа 200 вы можете не обращать внимания на его тело.

Пример

curl -X POST \
  'https://api.cyberity.ru/resources/applicants/5bb8cca10a975a624903cf65/status/testCompleted' \
  -H 'content-type: application/json' \
  -d '{
   "reviewAnswer" : "GREEN",
   "rejectLabels": []
  }
'

curl -X POST \
  'https://api.cyberity.ru/resources/applicants/5bb8cca10a975a624903cf65/status/testCompleted' \
  -H 'content-type: application/json' \
  -d '{
          "reviewAnswer": "RED",
          "moderationComment": "We do not accept screenshots. Please upload an original photo.",
          "clientComment": "Screenshots are not accepted.",
          "reviewRejectType": "RETRY",
          "rejectLabels": ["UNSATISFACTORY_PHOTOS","SCREENSHOTS"]
      }
'

{
  "ok": 1
}

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

Если вы начинаете сотрудничество с другим нашим клиентом и хотите упростить и ускорить верификацию пользователей, отличным решением будет объединить ваши пользовательские базы через IDnGO. Подробнее об обмене пользователями в разделе О верификации

# POST Генерация shareToken

POST /resources/accessTokens/-/shareToken?applicantId={applicantId}&forClientId={clientId}

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

Ответ

В полученном JSON shareToken указан в поле token.

Пример

Пример получения shareToken (выполняется X):

## applicantId and Y's client ID must be provided
 curl -X POST \
    'https://api.cyberity.ru/resources/accessTokens/-/shareToken?applicantId=5ce412012b4da877b2d910bd&forClientId=CoolCoinLtd'

{
  "token": "_act-460a698b-d2bc-4cbc-9456-5f36fee38083",
  "forClientId": "CoolCoinLtd"
}

# POST Импорт пользователя от сервиса-партнера

POST /resources/applicants/-/import?shareToken={shareToken}

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

Ответ

В ответ приходит информация об анкете импортированного в сервис Y пользователя.

Пример

Пример импорта пользователя (выполняется Y):

 curl -X POST \
    'https://api.cyberity.ru/resources/applicants/-/import?shareToken=_act-0b8a43f6-b70f-4ad3-bda9-7ce904589380'

{
    // Applicant in service Y
    "id": "5d08a63239b79354a2ebaa1d",
    "createdAt": "2019-06-18 10:52:02",
    "clientId": "CoolCoinLtd",
    ...
}

# Проверка отправителя вебхука

Подробнее о вебхуках в разделе Начало работы.

# POST Проверка отправителя вебхука

Чтобы проверить, что вы вычисляете контрольное значение (digest) тем же способом, что и мы, воспользуйтесь этим эндпоинтом. Он принимает текст в качестве тела и не может обрабатывать полезную нагрузку в формате JSON, как в реальных случаях.

POST /resources/inspectionCallbacks/testDigest?secretKey={secretKey}

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

Ответ

Пример

curl -X POST \
  'https://api.cyberity.ru/resources/inspectionCallbacks/testDigest?secretKey=SoMe_SeCrEt_KeY' \
  -H 'Content-Type: text/plain' \
  -d 'someText'

{
  "digest": "f6e92ffe371718694d46e28436f76589312df8db"
}