Changelog · 2026-10-09 · Neurovision KYC

Backend API 1.40.2 · Личный кабинет

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

Ломающие изменения

Новые состав, порядок и подписи пар сверки лиц. Подпись — имена лиц с номером шага (liveness_0 & document_1), у пары есть номер index. Подписи прежнего вида (document_0 & selfie) в новых сессиях не встречаются. Итог сверки берите из status задачи faces, а сохранённые фильтры сессий по подписи пары переведите на новые подписи.

Загрузка кадров

Номер шага stepIndex (новое). Необязательное целое число — номер шага сценария с нуля, то есть позиция шага в results ответа сессии. Если он передан, кадр сопоставляется только с этим шагом, и ошибка кадра и попытка списываются только у него. Без stepIndex шаг выбирается как раньше.

Передаётся в REST POST /v1/kyc/process полем multipart stepIndex — строкой из цифр.

Со stepIndex — одно изображение на запрос.
Без type вид загрузки берётся по виду шага; если type передан, он должен совпадать с видом шага. Поле type помечено устаревшим, но работает.
Номер действует по текущей схеме сценария: после правки схемы номер из старого results может указать на другой шаг.
Передавайте stepIndex, если в сценарии есть шаги одного вида (например, два паспорта) или нужно точно знать, у какого шага спишется попытка.

Загрузка без stepIndex в сценарии с несколькими подходящими шагами (изменено)

Кадр ставится в первый подходящий шаг, который не пройден и не занят другим кадром того же запроса; если таких нет — в первый подходящий.

Кадр в пройденный шаг (изменено)

Пройденный шаг документа или селфи принимает кадр, только пока он указан в retake задачи faces. Со stepIndex остальные пройденные шаги отвечают отказом step closed, без него кадр пропускается без ошибки и без попытки. Пройденный шаг лайвнеса новых попыток не принимает.

Запросы к одной сессии — по очереди (новое)

Одновременные загрузки в одну сессию обрабатываются по одной, результат каждой сохраняется. Следующий запрос ждёт до 25 секунд; если сессия не освободилась — 409 [request] session is busy, кадр не обработан, попытка не списана. Так же ведут себя kyc/session/status/change и kyc/session/reference. Пока сессия обрабатывается, её статус — processing. На 409 повторите тот же запрос после ответа на предыдущий.

Сверка лиц: задача faces

Задача faces есть во всех ответах с шагами сессии, после шагов сценария, когда в сценарии есть что сравнивать (два лица и больше или эталонная сессия). Пример: лайвнес (шаг 0), паспорт (шаг 1), водительское удостоверение (шаг 2), ВУ не совпало ни с одним лицом:

{
  "type": "faces",
  "status": "failed",
  "errors": ["[face] bad face matching"],
  "checks": [{
    "caption": "Face matching",
    "items": [
      { "index": 0, "caption": "liveness_0 & document_1", "status": "success", "images": ["…", "…"] },
      { "index": 1, "caption": "liveness_0 & document_2", "status": "failed", "images": ["…", "…"] },
      { "index": 2, "caption": "document_1 & document_2", "status": "failed", "images": ["…", "…"] }
    ]
  }],
  "retake": [2]
}

Поле	Значение
status	`idle` — ещё не все лица сессии получены; `success` — сверка прошла или пар нет; `failed` — сверка не прошла: сессия закрыта по лицам или ждёт пересъёмки шагов из `retake`
errors	`[face] bad face matching` — несовпадение; `[system] exception` — временный сбой сравнения; `[face] reference session unusable` — сравнение с эталонной сессией невозможно
items[].index	номер пары в полном списке; список задаётся схемой сценария и не меняется
items[].caption	`<лицо> & <лицо>`; лица: `liveness_<n>`, `selfie_<n>`, `selfie_document_<n>` (документ в руках на селфи), `document_<n>`, `ref:face` (эталонная сессия); `<n>` — номер шага в `results`
items[].status	`idle` — пара ещё не сравнивалась; `success` / `failed` — совпала / нет; `skipped` — пара не участвует в сверке
items[].images	ссылки на два лица — только у сравненных пар
`retake` (новое)	номера шагов для пересъёмки по возрастанию; `[]` — переснимать нечего

Как принимается решение

Корни — лицо лайвнеса и живое лицо селфи; в сценарии только из документов — первый документ с фото. Лайвнес и живое лицо селфи должны совпасть напрямую.
Лицо считается связанным, если до него можно дойти от корня по совпавшим парам, в том числе «документ ↔ документ». Сверка проходит, когда связаны все лица.
Пары сравниваются по мере поступления лиц. Отказ и retake определяются, когда получены все лица.
Несовпадение лайвнеса с живым лицом селфи или корня с эталонной сессией — сессия сразу suspicious и закрыта, retake пуст.
Пока сверка не прошла, в ответе весь список пар; когда прошла — только совпавшие пары, достаточные для цепочки, поэтому index идёт с пропусками.
Временный сбой сравнения ([system] exception) не окончательный: сервер повторяет сравнение при следующей загрузке и при чтении kyc/session/status.

Что сделать в интеграции

Не считать idle и skipped отказом. После отказа сверки переснимать только шаги из retake. Обрабатывать suspicious как итог на любом шаге и больше не слать кадры в такую сессию.

Статусы и ошибки

Код	Где	Когда	Что сделать
`[request] invalid stepIndex: out of range` (новое)	HTTP 400	номера нет в сценарии	перечитать сессию, взять номер из `results`
`[request] invalid stepIndex: step kind mismatch` (новое)	HTTP 400	шаг другого вида, чем загрузка	исправить `stepIndex` или `type`
`[request] invalid stepIndex: single image required` (новое)	HTTP 400	со `stepIndex` пришло больше одного изображения	одно изображение на запрос
`[request] invalid stepIndex: step closed` (новое)	HTTP 400	шаг пройден и не в `retake`, исчерпал попытки или достиг порога критических ошибок	снимать непройденные шаги или шаги из `retake`
`[request] session is busy` (новое)	HTTP 409	к сессии шёл другой запрос всё время ожидания	повторить запрос после ответа на предыдущий
`[face] face out of frame` (новое)	ошибка шага селфи	лицо обрезано краем кадра	переснять селфи
`[face] face occluded` (новое)	ошибка шага селфи	документ в руках закрывает больше 30 % лица	переснять селфи
`[general] too many faces` (уточнено)	ошибка шага селфи	вне документа больше одного лица; лица на самом документе не считаются	переснять селфи
`[general] too many tries` (изменено)	ошибка шага	последняя попытка шага неудачна; сессия закрывается сразу	показать итог, кадры не слать

Отказы [request] … (400 и 409) ничего не меняют в сессии: кадр не обрабатывается, попытка не списывается, вебхук не отправляется. Без stepIndex отказов 400 из таблицы не бывает.

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

suspicious — теперь и при несовпадении лайвнес ↔ селфи или корня с эталоном, в любой момент прохождения.
failed с [general] too many tries у шага — сессия закрыта сразу после последней неудачной попытки.
failed с непустым retake — сверка лиц не прошла, сессия ждёт пересъёмки.
processing — сессию обрабатывает запрос.

Сессия со статусом, сменённым вручную (в ЛК или через kyc/session/status/change), кадры больше не принимает.

Уничтожение персональных данных по clientUser

kyc/session/erase принимает clientUser (новое). Одним вызовом уничтожаются ПД во всех сессиях этого пользователя в аккаунте, за всё время хранения, включая сессии, созданные до обновления.

В запросе — ровно одно из sessionId и clientUser; clientUser после обрезки пробелов — от 1 до 36 символов. Иначе 400 invalid_request.
Ответ: { status, result, clientUser, sessions: [...] }. Элемент sessions — sessionId, result, pdErasedAt, parts, как у ответа по sessionId; сессии от новой к старой. Общий result — erased (200), если уничтожены все сессии списка, иначе in_progress (202).
Число сессий в одном вызове не ограничено. Если вызов не успевает дождаться всех, он отвечает in_progress, уничтожение доводится до конца без повторного вызова, завершение по каждой сессии приходит вебхуком.
Нет сессий с этим clientUser в аккаунте — 404 not_found.

Журнал kyc/session/erase/log (новое). В каждой записи — clientUser сессии; новый необязательный фильтр clientUser вместе с периодом, как фильтр sessionId.

Личный кабинет

Блок «Сравнение лиц»: пары по порядку номера, вместо процента — «совпала / не совпала», показаны шаги для пересъёмки.
Новые ошибки шага селфи — в отчётах и фильтре по ошибкам.
Ручная смена статуса закрывает сессию для дальнейшего прохождения.

Полное описание полей — в документации API.