Создание сессии и метаданные¶

Для каждой попытки проверки создавайте отдельную сессию. Backend клиентской системы отправляет API KEY выбранного Workflow, получает одноразовый session_id и передаёт его в Remote, Widget или WebView.

Создание сессии¶

POST https://kyc.biometric.vision/api/flows/sessions/create/
Content-Type: application/json

Минимальный запрос:

curl --request POST \
  --url 'https://kyc.biometric.vision/api/flows/sessions/create/' \
  --header 'Content-Type: application/json' \
  --data '{
    "api_key": "<FLOW_API_KEY>"
  }'

Успешный ответ возвращается с HTTP 201 Created и содержит:

{
  "session_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "technologies": ["LC", "DR2", "F2F"]
}

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

Метаданные сессии¶

Объект metadata позволяет передать известные клиентской системе данные, предзаполнить поля технологии, указать эталонную фотографию или связать сессию с существующей персоной. Метаданные передаются при создании сессии и не добавляют технологии в Workflow.

Если метаданные не требуются настройками Workflow, поле metadata можно не передавать. Исключение — включённая отправка отчётов: в этом случае необходимо передать extra.iin.

Передавайте разделы, необходимые для вашего сценария. Не используйте metadata и extra как произвольное хранилище пользовательских полей: запрос создания сессии имеет фиксированную схему метаданных.

Face2Face¶

Если у клиентской системы уже есть фотография пользователя, передайте её для сравнения в Base64:

{
  "api_key": "<FLOW_API_KEY>",
  "metadata": {
    "face2face": {
      "photo1": "<BASE64_IMAGE>"
    }
  }
}

Переданная фотография используется в Workflow, где Face2Face выполняется вместе с Liveness, E-Document или Document Recognition.

Передавайте чистую строку Base64 без префикса data:image/...;base64,. URL изображения и ключ файла в хранилище не подходят для запроса создания сессии.

Если в Workflow включена DSI или DSS, передавать face2face.photo1 нельзя: создание сессии завершится ошибкой HTTP 400. Если также передан person.alias, фотография из face2face.photo1 имеет приоритет перед фотографией персоны.

E-Document¶

Метаданные E-Document позволяют предзаполнить ИИН и номер телефона, запретить их изменение и при выполнении всех условий пропустить экран ввода данных.

Чтобы пропустить экран ввода, одновременно передайте значения ИИН и телефона, установите для обоих полей changeable: false и задайте skip_input: true:

{
  "api_key": "<FLOW_API_KEY>",
  "metadata": {
    "edocument": {
      "iin": {
        "value": "<SUBJECT_IIN>",
        "changeable": false
      },
      "phone": {
        "value": "<SUBJECT_PHONE>",
        "changeable": false
      },
      "skip_input": true
    }
  }
}

Пользователь сразу перейдёт к вводу OTP-кода от 1414. Если передать skip_input: true, но не выполнить хотя бы одно из перечисленных условий, backend отклонит создание сессии с HTTP 400.

Чтобы показать экран ввода с предзаполненными данными, передайте skip_input: false. Для каждого переданного объекта iin или phone укажите непустое value; changeable: false запрещает пользователю редактировать соответствующее поле, а true разрешает.

Значения по умолчанию в таблице описывают поведение формы из интеграционной документации. Если эти параметры не переданы, backend не подставляет changeable и edocument.skip_input в сохранённые метаданные. Для явного управления сценарием передавайте их в запросе.

Digital Signature Identifier¶

Метаданные ds_identifier предзаполняют данные подписанта:

Для управления редактированием используйте объекты с value и changeable, как в примере ниже. Строковая форма также поддерживается, но не позволяет задать changeable для поля. Если changeable не передан, backend не добавляет его в метаданные; значение true в таблице описывает поведение формы.

ИИН должен содержать 12 цифр. Телефон передавайте цифрами, без +, пробелов и разделителей. Чтобы сохранить экран ввода данных, явно задайте skip_input: false:

{
  "api_key": "<FLOW_API_KEY>",
  "metadata": {
    "ds_identifier": {
      "iin": {
        "value": "<SUBJECT_IIN>",
        "changeable": true
      },
      "phone": {
        "value": "<SUBJECT_PHONE>",
        "changeable": true
      },
      "skip_input": false
    }
  }
}

Загрузка документов для подписания и получение CMS-подписи относятся к отдельным операциям Digital Signature и не входят в создание сессии.

GBDUL¶

Метаданные gbdul позволяют заранее указать БИН организации для получения данных из ГБД ЮЛ, в том числе в сценарии цифровой подписи для юридического лица.

Чтобы предзаполнить БИН и запретить его изменение, передайте:

{
  "api_key": "<FLOW_API_KEY>",
  "metadata": {
    "gbdul": {
      "bin": {
        "value": "<ORGANIZATION_BIN>",
        "changeable": false
      },
      "skip_input": false
    }
  }
}

Если changeable не передан или равен true, пользователь может ввести или изменить БИН. Backend не подставляет отсутствующий changeable в метаданные. skip_input управляет пропуском ввода; сам запрос к ГБД ЮЛ выполняется на этапе технологии, а не при создании сессии.

KZ Info¶

Поле kz_info.iin передаёт известный ИИН пользователя. В сценарии KZ Info с альтернативным способом получения данных он используется, если ИИН не указан в запросе самой технологии.

{
  "api_key": "<FLOW_API_KEY>",
  "metadata": {
    "kz_info": {
      "iin": "<SUBJECT_IIN>"
    }
  }
}

Этот ИИН также имеет приоритет при общем поиске ИИН в данных сессии, к которому обращаются, в зависимости от сценария, GBDFL, Address, RPN и PPS. Он не подставляется автоматически во все поля всех технологий: например, не заменяет edocument.iin.value или обязательный для отправки отчётов extra.iin.

ERD¶

Поле erd.iin позволяет передать ИИН для сценария ERD. Метаданные возвращаются интерфейсу прохождения при запуске сессии; запрос проверки ERD отдельно принимает ИИН в поле personal_number. Передача метаданных сама по себе не запускает проверку.

{
  "api_key": "<FLOW_API_KEY>",
  "metadata": {
    "erd": {
      "iin": "<SUBJECT_IIN>"
    }
  }
}

erd.iin также может использоваться генератором отчётов как источник ИИН, если не переданы extra.iin и kz_info.iin.

OTP¶

Поле otp.phone_number задаёт номер телефона для отдельной технологии OTP. Это не настройка OTP-кода E-Document от 1414 и не замена edocument.phone или ds_identifier.phone.

{
  "api_key": "<FLOW_API_KEY>",
  "metadata": {
    "otp": {
      "phone_number": "<SUBJECT_PHONE_WITH_PLUS>"
    }
  }
}

Код отправляется при вызове технологии OTP. Номер из запроса отправки имеет приоритет; если он не передан, backend берёт metadata.otp.phone_number. Если номера нет в обоих местах, отправка не выполняется и результат OTP получает статус FAILED с причиной phone_number_missing.

Дополнительные метаданные¶

Поле extra.iin передаёт ИИН пользователя для формирования PDF-отчётов, в том числе подписанных отчётов Liveness и Face2Face.

Если в конфигурации Workflow включён параметр отправки отчётов Send signed report, непустое metadata.extra.iin обязательно уже при создании сессии. ИИН в других разделах метаданных не заменяет его при этой проверке.

При формировании отчёта extra.iin используется первым. Если он отсутствует, генератор также может получить ИИН из других метаданных или результатов технологий. Поэтому обязательность именно extra.iin при создании определяется настройкой Send signed report.

{
  "api_key": "<FLOW_API_KEY>",
  "metadata": {
    "extra": {
      "iin": "<SUBJECT_IIN>"
    }
  }
}

Персона¶

Поле metadata.person.alias позволяет найти существующую персону или сохранить алиас при сборе данных новой персоны. Передайте значение действующего алиаса существующей персоны либо новый уникальный идентификатор клиентской системы. Для работы с персонами в Workflow должна быть включена технология PS и настроены соответствующие функции.

{
  "api_key": "<FLOW_API_KEY>",
  "metadata": {
    "person": {
      "alias": "<PERSON_ALIAS>"
    }
  }
}

Тип алиаса отдельно передавать не нужно. Система обрабатывает значение следующим образом:

• при запуске сессии система ищет персону по значению действующего алиаса внутри организации, которой принадлежит Workflow; истёкшие алиасы не участвуют в поиске;
• после успешного завершения сессии при включённом сборе персон система асинхронно создаёт или обновляет персону по собранным данным, включая переданный алиас;
• если подходящей персоны нет, создаётся новая; новый алиас из метаданных сохраняется с типом custom. Сам запрос создания сессии ещё не создаёт персону.

Повторное использование результатов включается настройкой Skip technology with existing Document result и зависит от пригодности сохранённых результатов, включая ограничения срока действия. Использование фотографии персоны для Face2Face включается настройкой Use person's photo for F2F comparison; истёкшая или удалённая фотография не используется как фотография по умолчанию. Если передана face2face.photo1, фотография персоны не добавляется для сравнения.

Подробности сбора персон и повторного использования данных описаны на странице «Персоны».

Валидация и ошибки метаданных¶

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

Условия edocument.skip_input не распространяются автоматически на ds_identifier или gbdul: для них при создании сессии нет аналогичной проверки сочетания skip_input, value и changeable. Для kz_info.iin, erd.iin, gbdul.bin.value, extra.iin и otp.phone_number создание сессии также не выполняет отдельную проверку формата значения, кроме проверки типа поля. Передавайте корректные данные для соответствующей технологии.

Нарушение дополнительных условий возвращает HTTP 400 с кодом invalid_flow_session_metadata. Например, если указать edocument.skip_input: true, но разрешить редактирование ИИН:

{
  "message": "Invalid metadata for session",
  "detail": "Value error, Both IIN and phone must have values and be non-changeable when skip_input is True",
  "code": "invalid_flow_session_metadata"
}

Если при включённой отправке отчётов не передать extra.iin:

{
  "message": "Invalid metadata for session",
  "detail": "Value error, IIN is required in extra metadata when report should be sent",
  "code": "invalid_flow_session_metadata"
}

Ошибки структуры запроса и типов полей могут возвращаться отдельно с HTTP 422. Для обработки ошибок используйте HTTP-статус и code, если он присутствует; detail содержит пояснение конкретной причины.

Метаданные в вебхуках¶

Вебхуки содержат сохранённый объект metadata сессии. Он может отличаться от исходного запроса: поля со значением null исключаются при сохранении, а некоторые значения по умолчанию добавляются согласно схеме.

В частности, после загрузки фотографии face2face.photo1 заменяется ключом файла в хранилище. В вебхуке это поле содержит ключ, а не исходную строку Base64 и не готовую ссылку на изображение. Не используйте его как URL для скачивания.

Полный запрос¶

Следующий cURL-пример показывает совместную передачу метаданных персоны и E-Document. Примеры других разделов выше предназначены для соответствующих сценариев Workflow; объединять все разделы в одном запросе не требуется. Замените значения в угловых скобках своими данными перед отправкой:

curl --request POST \
  --url 'https://kyc.biometric.vision/api/flows/sessions/create/' \
  --header 'Content-Type: application/json' \
  --data '{
    "api_key": "<FLOW_API_KEY>",
    "metadata": {
      "person": {
        "alias": "<PERSON_ALIAS>"
      },
      "edocument": {
        "iin": {
          "value": "<SUBJECT_IIN>",
          "changeable": false
        },
        "phone": {
          "value": "<SUBJECT_PHONE>",
          "changeable": false
        },
        "skip_input": true
      }
    }
  }'

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