Remote Workflow

Remote позволяет встроить биометрическую проверку в продукт без разработки собственного интерфейса для съёмки документов, проверки живости и других технологий. Ваш backend создаёт сессию по заранее настроенному Workflow, а затем frontend перенаправляет пользователя на страницу Biometric.Vision. После завершения проверки backend получает итоговый результат через API.

Workflow определяет состав и порядок технологий, которые должен пройти пользователь. Сессия представляет один конкретный запуск этого сценария и связывает действия пользователя с результатами проверки.

Границы интеграции¶

В интеграции участвуют три стороны:

• backend клиентской системы создаёт сессию, хранит API KEY, принимает webhook и запрашивает результат;
• frontend клиентской системы получает от backend только session_id или готовый URL и перенаправляет пользователя;
• Biometric.Vision показывает интерфейс проверки, запускает технологии Workflow и сохраняет результаты сессии.

До запуска интеграции настройте Workflow и сохраните его API KEY в секретах backend. После этого каждая проверка состоит из пяти шагов:

1. Создать отдельную сессию для попытки пользователя.
2. Перенаправить пользователя на Remote URL с полученным session_id.
3. Дождаться, пока пользователь пройдёт технологии Workflow.
4. Определить завершение сессии через webhook или возврат пользователя на redirect URL.
5. Запросить результат с backend и принять бизнес-решение на основе результатов технологий.

sequenceDiagram
    title Взаимодействие Клиентской системы с сервисом биометрии

    participant AIS as Клиентская система
    participant BIO as Biometric.Vision (KYC)
    participant USER as Конечный пользователь

    note over AIS: Предусловие:<br/>Workflow создан в личном кабинете

    note over AIS,BIO: Этап 1 — Создание сессии
    AIS->>+BIO: POST /flows/session/create/<br/>{api_key}
    BIO-->>-AIS: {session_id, technologies}

    note over AIS,USER: Этап 2 — Перенаправление
    AIS->>USER: Redirect → https://remote.biometric.vision/flow/{session_id}

    note over BIO,USER: Этап 3 — Биометрическая верификация
    USER->>+BIO: Открытие flow-страницы
    BIO->>USER: UI верификации

    loop Технологии
        BIO->>BIO: Liveness Detection
        BIO->>BIO: Document Recognition
        BIO->>BIO: Face2Face
    end

    BIO-->>-USER: Верификация завершена

    note over AIS,USER: Этап 4 — Триггер получения результата

    alt Вариант А: Webhook (server-to-server)
        BIO-)AIS: Webhook: flow.end<br/>{session_id, success, data}
        note right of AIS: Асинхронное уведомление<br/>на настроенный URL
    else Вариант Б: Redirect пользователя
        BIO->>USER: Redirect → redirect_url?session_id=...
        USER->>AIS: Переход на страницу Клиентской системы
        note right of AIS: Клиентская система получает session_id<br/>из параметров URL
    end

    note over AIS,BIO: Этап 5 — Получение результата
    AIS->>+BIO: GET /flows/session/result/<br/>?session_id=...&flow_api_key=...
    BIO-->>-AIS: JSON результат<br/>{liveness_result, doc_recognition_result,<br/>face2face_result, edocument_result}

    note over AIS: Обработка результатов верификации

1. Подготовка Workflow¶

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

Для серверной интеграции потребуется API KEY выбранного Workflow. Храните соответствие между бизнес-сценарием и ключом Workflow в конфигурации backend. Перед перенаправлением пользователя backend создаёт отдельную сессию и передаёт frontend полученный session_id. При создании можно передать метаданные для технологий или связать сессию с существующей персоной. Это особенно важно, если разные продукты или категории пользователей проходят разные наборы проверок.

2. Перенаправление пользователя¶

После создания сессии сформируйте Remote URL:

https://remote.biometric.vision/flow/<session_id>

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

К URL можно добавить параметры:

Значение redirect обязательно кодируйте как отдельный query-параметр:

const remoteUrl = new URL(`https://remote.biometric.vision/flow/${sessionId}`)
remoteUrl.searchParams.set('redirect', 'https://example.com/verification/complete')
remoteUrl.searchParams.set('locale', 'ru')

window.location.assign(remoteUrl.toString())

Поддерживаемые значения locale: kz, en, ru, my, de, es, fa, fr, it, ja, kg, ko, pt.

Значения newCabinet и oldCabinet параметра redirect зарезервированы для внутреннего использования и не должны применяться в клиентской интеграции.

3. Определение завершения сессии¶

Есть два способа запустить получение результата:

• webhook flow.end подходит для основного server-to-server сценария и не зависит от того, закрыл ли пользователь вкладку;
• возврат на redirect URL удобен для обновления интерфейса пользователя, но сам по себе не гарантирует наличие готового результата.

Практический вариант — поддерживать оба канала. Webhook обновляет состояние заявки на backend, а страница возврата периодически запрашивает его. Если результат ещё не готов, выполняйте polling с интервалом 2–3 секунды и ограничьте общее время ожидания.

Обработчик webhook должен быть идемпотентным: повторная доставка одного события не должна повторно запускать бизнес-операцию. Связывайте событие с заявкой по session_id, сохраняйте факт обработки и отвечайте только после надёжной записи состояния.

Связанные разделы¶

• Workflow
• Создание сессии и метаданные
• Получение результата
• Причины отказа
• Webhooks
• Персоны