Статус сессии

Получение статуса и результатов одной KYC-сессии по sessionId или clientKey.

Метод: POST
Путь: kyc/session/status
Content-Type: application/json

Авторизация

Поддерживается два способа авторизации:

1. JWT-токен в заголовке `token`:

token: <jwt-token>

2. API-токен (timeuuid) в теле запроса:

{"token": "<api-token>", "sessionId": "..."}

Без токена (ни в header, ни в body) запрос вернёт "access denied".

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

Параметр	Тип	Обязательный	Описание
`sessionId`	string (timeuuid)	нет*	UUID v1 (timeuuid) сессии
`clientKey`	string (непустая)	нет*	Клиентский ключ (непустая строка, макс. 36 символов)

* Необходимо указать хотя бы один из параметров: sessionId или clientKey.

Приоритет параметров

Если переданы оба параметра одновременно, clientKey имеет приоритет — поиск будет выполнен по clientKey, sessionId будет проигнорирован.

Ограничения

sessionId должен быть валидным timeuuid (UUID v1)
clientKey — непустая строка длиной не более 36 символов

Формат ответа

Успешный ответ (200)

{
  "status": "success",
  "sessionId": "550e8400-e29b-41d4-a716-446655440000",
  "errors": [],
  "schemaId": "660e8400-e29b-41d4-a716-446655440000",
  "clientId": "770e8400-e29b-41d4-a716-446655440000",
  "spent": 24.184,
  "createdAt": "2026-03-19T10:31:06.000Z",
  "isClientNew": false,
  "clientKey": "my_client_key_123",
  "clientUser": "",
  "secondsToLive": 0,
  "responseTime": "2026-03-19T10:31:30.000Z",
  "results": [...],
  "email": "user@example.com",
  "wallet": "0x1234...abcd"
}

Описание полей ответа

Поле	Тип	Описание
`status`	string	Статус сессии (см. таблицу ниже)
`sessionId`	string (timeuuid)	UUID v1 (timeuuid) сессии
`errors`	array	Общие ошибки сессии
`schemaId`	string (UUID)	UUID KYC-схемы
`clientId`	string (UUID)	UUID клиента (пустая строка, если клиент не идентифицирован)
`spent`	number	Общее время обработки в секундах
`createdAt`	string (ISO 8601)	Дата и время создания сессии
`isClientNew`	boolean	`true` — первый визит клиента, `false` — повторный
`clientKey`	string	Клиентский ключ, переданный при создании сессии
`clientUser`	string	Идентификатор пользователя клиента
`secondsToLive`	number	Оставшееся время жизни сессии в секундах (0 = истекла)
`responseTime`	string (ISO 8601)	Время формирования ответа
`results`	array	Массив результатов по задачам (см. ниже)
`email`	string	Email клиента (опционально)
`wallet`	string	Адрес криптокошелька клиента (опционально)

Статусы сессии

Статус	Описание
`idle`	Сессия создана, обработка не начата
`processing`	Сессия в процессе обработки
`success`	Все задачи завершены успешно
`failed`	Одна или несколько задач завершились ошибкой
`exception`	Произошла системная ошибка
`expired`	Время жизни сессии истекло

Результаты задач (results)

Массив results содержит результаты по каждой задаче KYC-сессии. Типы задач: document, selfie, faces.

Задача типа `document`

{
  "status": "success",
  "type": "document",
  "spent": 1.367,
  "errors": [],
  "docName": "Passport (2006)",
  "tries": 1,
  "startedAt": "2026-03-19T10:31:08.000Z",
  "isBackSide": false,
  "countryCode": "RUS",
  "checks": [
    {
      "caption": "fraud",
      "items": [
        { "status": "success", "caption": "isPrinted", "confidence": 1 },
        { "status": "success", "caption": "isEdited", "confidence": 0.001 },
        { "status": "success", "caption": "isDisplay", "confidence": 0.938 }
      ]
    }
  ],
  "ocr": {
    "status": "success",
    "fields": [
      { "title": "Surname", "value": "DOE", "conf": "high" },
      { "title": "Given name(s)", "value": "JOHN", "conf": "high" },
      { "title": "Date of birth", "value": "01.01.1970", "conf": "high" }
    ]
  },
  "images": ["https://api.example.com/images/kyc/.../document_0/0"],
  "imagesFull": ["https://api.example.com/images/kycfull/.../document_0_0.jpg"],
  "imageObjects": ["https://api.example.com/images/kyc/.../stamp/0"],
  "history": [...]
}

Поле	Тип	Описание
`status`	string	Статус задачи: `idle`, `processing`, `success`, `failed`
`type`	string	Тип задачи: `document`
`spent`	number	Время обработки в секундах
`errors`	array	Ошибки обработки (напр. `"[document] unknown document type"`)
`docName`	string	Распознанный тип документа (напр. `"Passport (2006)"`, `"ePassport (2005-2008)"`)
`tries`	number	Количество попыток распознавания
`startedAt`	string (ISO 8601)	Время начала обработки
`isBackSide`	boolean	Является ли обратной стороной документа
`countryCode`	string	Код страны документа (ISO 3166-1 alpha-3)
`checks`	array	Результаты проверок (fraud-чеки)
`ocr`	object	Результаты распознавания текста
`images`	array	Ссылки на обработанные изображения (миниатюры)
`imagesFull`	array	Ссылки на полноразмерные изображения
`imageObjects`	array	Ссылки на распознанные объекты (штампы, подписи)
`history`	array	История предыдущих попыток (при `tries` > 1)

Задача типа `selfie`

{
  "status": "success",
  "type": "selfie",
  "spent": 0.14,
  "errors": [],
  "docName": "Passport (2006)",
  "tries": 1,
  "withDoc": ["Domestic passport"],
  "checks": [
    {
      "caption": "fraud",
      "items": [
        { "status": "success", "caption": "isFaceDeepFake" },
        { "status": "success", "caption": "isAgeMismatch", "value": 15 },
        { "status": "success", "caption": "isDisplaySelfie", "confidence": 1 },
        { "status": "success", "caption": "isGenderMismatch", "value": "female" }
      ]
    }
  ],
  "faceSelfie": "https://api.example.com/images/kycthumb/.../selfie/0",
  "faceDoc": "https://api.example.com/images/kycthumb/.../selfie_document/0",
  "images": ["https://api.example.com/images/kyc/.../selfie_0/0"],
  "imagesFull": ["https://api.example.com/images/kycfull/.../selfie_0_0.jpg"]
}

Поле	Тип	Описание
`withDoc`	array/string	Документ(ы), с которым сопоставляется селфи
`faceSelfie`	string	Ссылка на вырез лица с селфи
`faceDoc`	string	Ссылка на вырез лица с документа

Задача типа `faces`

Результат сравнения лиц. Появляется, когда в сессии есть и документ, и селфи.

{
  "status": "success",
  "type": "faces",
  "spent": 0.003,
  "errors": [],
  "checks": [
    {
      "caption": "Face matching",
      "items": [
        {
          "status": "success",
          "caption": "document_0 & selfie",
          "value": "92%",
          "images": [
            "https://api.example.com/images/kycthumb/.../document_0",
            "https://api.example.com/images/kycthumb/.../selfie"
          ]
        },
        {
          "status": "success",
          "caption": "document_0 & selfie_document",
          "value": "96%",
          "images": [...]
        }
      ]
    }
  ]
}

Поле	Тип	Описание
`checks[].items[].value`	string	Процент совпадения лиц
`checks[].items[].images`	array	Пара сравниваемых изображений

Ошибки

Невалидная схема (400)

При нарушении формата параметров:

{
  "status": "error",
  "message": "invalid schema",
  "details": [
    {
      "expected": {},
      "actual": "not-a-uuid",
      "path": "sessionId"
    }
  ]
}

Типичные причины:

sessionId не является валидным timeuuid (UUID v1)
clientKey длиннее 36 символов
clientKey — пустая строка

Сессия не найдена (200)

{
  "status": "error",
  "message": "session not found"
}

Возможные причины:

Сессии с указанным sessionId или clientKey не существует

Не указан идентификатор (400)

{
  "status": "error",
  "message": "sessionId or clientKey is required"
}

Возникает, когда в body не передан ни sessionId, ни clientKey.

Нет авторизации (401)

{
  "status": "error",
  "message": "access denied"
}

Примеры запросов

Поиск по sessionId

curl -X POST https://api.neuro-vision.ru/v1/kyc/session/status 
  -H 'Content-Type: application/json' 
  -H 'token: <jwt-token>' 
  -d '{"sessionId": "550e8400-e29b-41d4-a716-446655440000"}'

Поиск по clientKey

curl -X POST https://api.neuro-vision.ru/v1/kyc/session/status 
  -H 'Content-Type: application/json' 
  -H 'token: <jwt-token>' 
  -d '{"clientKey": "my_client_key_123"}'

Типичные fraud-проверки (checks)

Для документов (`type: "document"`)

Caption	Описание
`isMRZValid`	Валидность MRZ-зоны
`isStampsOk`	Проверка штампов/печатей
`isPrinted`	Документ напечатан (не фото экрана)
`isDamaged`	Документ не повреждён
`isOtherObjectsOk`	Нет посторонних объектов
`isXerocopy`	Документ не является ксерокопией
`isEdited`	Документ не редактирован
`isSignatureOwnerOk`	Подпись владельца
`isSignatureIssuerOk`	Подпись выдающего органа
`isDisplay`	Документ не сфотографирован с экрана
`isFieldsModified`	Поля не модифицированы
`isCropped`	Документ не обрезан
`isFieldsCorrected`	Поля не корректировались
`isMobile`	Снято с мобильного устройства
`isPhotoApplication`	Фото без приложения-редактора
`isLogicalMismatch`	Нет логических несоответствий

Для селфи (`type: "selfie"`)

Caption	Описание
`isFaceDeepFake`	Проверка на deepfake
`isAgeMismatch`	Совпадение возраста (value = разница в годах)
`isCropped`	Фото не обрезано
`isXerocopy`	Не ксерокопия
`isGenderMismatch`	Совпадение пола (value = определённый пол)
`isDisplaySelfie`	Не фото с экрана
`isMobile`	Снято с мобильного