Работа с clientKey

clientKey — это пользовательский идентификатор, который вы сами задаёте и используете для связи KYC‑сессий с вашими пользователями, заявками или договорами.

Через clientKey вы можете:

находить KYC‑сессию по вашему ключу;
сопоставлять результаты проверки с вашими объектами (userId, orderId, loanId и т.п.);
фильтровать сессии через REST API;
проще обрабатывать вебхуки.

Важно: значение clientKey придумываете вы, платформа не генерирует его автоматически.

Формат и ограничения

Тип: string
Максимальная длина: 36 символов
Формат: любая строка, удобно ограничиться латиницей, цифрами и разделителями ([a-zA-Z0-9_-])

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

Рекомендуется использовать:

clientKey = "<userId>:<orderId>:<номер попытки>", например u1024:o77:1 — если KYC привязана к заявке, заказу, договору;
clientKey = UUID — если удобнее работать только с KYC‑идентификатором.

Чтобы найти все попытки одного пользователя, передавайте его идентификатор в clientUser.

Две формы clientKey: «сырой» и зашифрованный

Для интеграции с WebSDK нужно понимать, что есть:

Исходное значение (clientKeyRaw) — то, что вы придумали: например, "user_123" или "loan-42".
Зашифрованное значение (clientKey) — то, что вы реально передаёте в виджет. Это результат шифрования clientKeyRaw секретным ключом сценария из личного кабинета.

Порядок работы:

На вашем сервере формируете clientKeyRaw (до 36 символов), шифруете его секретным ключом сценария и отдаёте зашифрованный clientKey в браузер.
В браузере передаёте зашифрованный clientKey в KYCWidget.setupKYC(...).
NeuroVision расшифровывает значение и сохраняет в сессии исходный clientKeyRaw — по нему можно искать сессии и получать результаты через API и вебхуки.

В API (/kyc/session/status, /kyc/sessions/filter) и в вебхуках вы работаете с исходным значением, которое задали сами. Шифрование нужно только для безопасной передачи clientKey в браузер.

Где используется clientKey

В WebSDK

Вызов виджета:

window.KYCWidget.setupKYC({
  scenarioId:  "SCENARIO_ID",            // ID сценария проверки
  clientKey: "ENCRYPTED_CLIENT_KEY", // зашифрованный clientKeyRaw
  theme: "light",
  closeCb:   () => console.log("CLOSE"),
  successCb: (payload) => {
    console.log("SUCCESS", payload);
    // исходный clientKeyRaw вы уже знаете: вы задали его на своём сервере
  },
});

Итог проверки в браузере

successCb приходит только при итоге success. Он не означает, что окно закрыто: пользователь ещё видит экран результата.
При любом другом итоге (отказ, ошибка, пользователь закрыл виджет) срабатывает только closeCb, без статуса. Итог сессии берите из вебхука или запросом статуса сессии.
Решение о прохождении проверки принимайте на сервере по вебхуку или статусу сессии, а не по колбэкам в браузере.

В REST API

/kyc/session/status — можно передать clientKey, чтобы уточнить статус по конкретному ключу;
/kyc/sessions/filter — есть фильтр clientKey, чтобы получать все сессии по ключу.

Здесь вы передаёте исходное значение (clientKeyRaw), без шифрования.

Генерация и шифрование clientKey на сервере

Секретный ключ сценария хранится только на вашем сервере. Передавать его в браузер нельзя.

Порядок:

Берёте clientKeyRaw (до 36 символов).
Берёте секретный ключ сценария из личного кабинета.
На сервере шифруете clientKeyRaw алгоритмом AES‑256‑CBC со случайным IV.
Получившуюся Base64‑строку передаёте в WebSDK как clientKey.

Шифрование симметричное: тот же секретный ключ сценария расшифровывает clientKey на стороне NeuroVision. Готовые примеры на Node.js, PHP, Python и Go есть в карточке сценария: вкладка «Документация по интеграции» → «Шифрование ключа клиента».

Пример на Node.js (AES‑256‑CBC)

const crypto = require("crypto");

// 1. Исходный идентификатор (то, что вы хотите видеть в API и вебхуках)
const clientKeyRaw = "user_123"; // до 36 символов

// 2. Секретный ключ сценария из личного кабинета (НЕ передаём в браузер!)
const password = "SCENARIO_SECRET_KEY";

// 3. Получаем 32‑байтовый ключ из пароля
const key = crypto.createHash("sha256").update(password).digest('hex').substr(0, 32);

// 4. Генерируем случайный IV (16 байт)
const iv = crypto.randomBytes(16);

// 5. Шифруем clientKeyRaw
const cipher = crypto.createCipheriv("aes-256-cbc", key, iv);
const encrypted = Buffer.concat([cipher.update(clientKeyRaw, "utf8"), cipher.final()]);

// 6. Склеиваем IV + шифртекст и кодируем в Base64 — это и есть clientKey для виджета
const encryptedBase64 = Buffer.concat([iv, encrypted]).toString("base64");

console.log("clientKeyRaw:", clientKeyRaw);
console.log("clientKey (encrypted):", encryptedBase64);

Именно такой зашифрованный clientKey вы подставляете в:

window.KYCWidget.setupKYC({
  scenarioId:  "SCENARIO_ID",
  clientKey: encryptedBase64,
  // ...
});

Кнопка «Проверить» рядом с секретным ключом сценария в личном кабинете шифрует значение тем же алгоритмом и помогает быстро убедиться, что clientKey формируется правильно. В рабочей интеграции всегда шифруйте clientKey на своём сервере.

clientKey и связанные сценарии

Если сценарий связан в личном кабинете с другими сценариями, сессия выбирает сценарий группы по первому документу пользователя, но для интеграции остаётся сессией сценария входа — того, чей scenarioId вы передали:

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

Как тестировать clientKey

В личном кабинете откройте сценарий и найдите его секретный ключ.
Нажмите кнопку «Проверить» и введите тестовый clientKeyRaw (например, test_user_1).
Личный кабинет вернёт зашифрованное значение — его можно временно подставить в примеры интеграции (вместо "ENCRYPTED_CLIENT_KEY").
Убедитесь, что виджет открывается без ошибок, а в списке сессий личного кабинета и в ответе /kyc/sessions/filter по clientKey видно исходное значение clientKeyRaw.

Частые вопросы и ошибки

«Где мне взять значения для clientKey и clientUser?»

clientKey — любая строка до 36 символов, которую вы определяете сами, уникальная для каждой попытки: например, номер заявки с номером попытки. Параметр обязателен, кроме случая, когда виджет открывается по taskId.
clientUser — необязательная строка до 36 символов, не обязана быть уникальной: по ней можно позже найти все сессии (попытки) одного пользователя.

Правильная практика: задайте clientKeyRaw уникальным для попытки (например, u1024:o77:1), идентификатор пользователя передайте в clientUser, зашифруйте clientKeyRaw и передавайте в виджет только зашифрованный clientKey.

Ошибка «Неправильное значение ключа клиента»

Виджет показывает это сообщение, если не смог расшифровать clientKey секретным ключом сценария. Чаще всего значит, что:

в виджет передан незашифрованный clientKeyRaw;
или использован другой секретный ключ, отличный от ключа сценария;
или значение clientKey было повреждено/обрезано (например, при копировании).

Проверьте:

Что вы передаёте в виджет именно Base64‑строку, полученную после шифрования (см. пример выше).
Что секретный ключ, которым вы шифруете, взят из того же сценария, scenarioId которого передаётся в виджет. У связанных сценариев это ключ сценария входа, а не сценария, который выберет документ.

«А как узнать clientKey для расшифровки вебхука?»

Для расшифровки тела вебхука clientKey не нужен:

тело вебхука шифруется алгоритмом AES‑256‑CBC секретным ключом сценария — тем же, которым вы шифруете clientKey. Шифрование включается флагом «Зашифровать тело POST-запроса с помощью секретного ключа» в настройках вебхука сценария;
для расшифровки достаточно секретного ключа сценария и поля encrypted из POST‑запроса.

clientKey в вебхуке — это просто одно из полей JSON внутри уже расшифрованного тела, и его значение будет ровно тем, которое вы задавали в clientKeyRaw.

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

«Почему каждый тестовый вебхук приходит с разной строкой encrypted, хотя JSON один и тот же?»

Это нормально:

при шифровании используется случайный IV (вектор инициализации);
даже при одинаковом JSON и ключе шифрования шифртекст каждый раз разный;
после расшифровки тело будет одинаковым JSON.

«Как общий статус success/failed связан с проверками и базами?»

Общий статус KYC‑сессии:

success — все проверки шагов сценария пройдены;
failed — хотя бы одна проверка шага (распознавание, признаки подделки, сравнение лиц, Liveness) не пройдена.

Проверки по внешним базам данных (санкционные списки, задолженности и т.п.) влияют на статус сессии, только если проверка отмечена в сценарии как блокирующая: если она не пройдена, сессия получает failed с кодом [legal] database check failed в errors. Неблокирующие проверки на статус не влияют. Подробные результаты проверок приходят отдельно — методом kyc/session/databases или вебхуком о завершении проверок по базам.