Получение результата¶

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

Запрашивайте результат с backend клиентской системы. Момент завершения можно отслеживать через webhook flow.end; после сигнала интерфейса также проверяйте результат серверным запросом. Ответ содержит текущее состояние сессии и доступные результаты, в том числе промежуточные.

Полный результат¶

POST https://kyc.biometric.vision/api/flows/sessions/result/

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

Облегчённый результат¶

POST https://kyc.biometric.vision/api/flows/sessions/result/light/

curl --request POST \
  --url 'https://kyc.biometric.vision/api/flows/sessions/result/light/' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --compressed \
  --data '{
    "session_id": "<SESSION_ID>",
    "api_key": "<FLOW_API_KEY>"
  }'

Light — вариант ответа, а не HTTP-метод. Для обоих endpoints выше используется POST с JSON-телом. Query-параметры получения результата этими маршрутами не предусмотрены.

Совместимость с прежними маршрутами¶

В текущем коде также доступны следующие маршруты прежнего API. Они используют те же выходные схемы, правила исключения null, проверки принадлежности сессии и ограничение частоты.

У этих GET-методов ключ Workflow называется flow_api_key, а не api_key. POST для прежнего light-маршрута не объявлен. Для новой интеграции используйте POST-маршруты из примеров выше.

Авторизация и параметры¶

Авторизация выполняется по api_key в теле запроса: ключ определяет Workflow, а session_id должен принадлежать этому Workflow. Дополнительные Authorization или X-API-Key для этих двух методов не требуются.

HTTP-ответы¶

Для больших ответов поддерживается сжатие gzip (Accept-Encoding: gzip; в примерах его запрашивает --compressed).

Правила чтения полей¶

В таблицах указан тип реально передаваемого значения. Если поле допускает отсутствие значения, API исключает его из JSON: это относится и к полям вложенных схем. Поэтому result: false, отсутствующий result и отсутствующий блок технологии — разные состояния.

• Обязательное поле присутствует при успешной сериализации соответствующего родительского объекта.
• При наличии значения означает: поле допускает null в исходных данных, но такой ключ не включается в ответ. Пустая строка, false, 0, {} и [] сами по себе не удаляются.
• Удаление null из полей схем не означает очистку произвольного JSON. Внутри динамических словарей и массивов null может сохраняться и отличается от отсутствующего ключа.
• Отсутствие блока не устанавливает причину: проверка могла ещё не начаться, запись могла не создаться или технология могла не участвовать в сессии. Блок может появиться до завершения проверки, иногда как {}.
• UUID передаётся строкой. ИИН, БИН, номера документов и телефоны — строки: сохраняйте ведущие нули.
• number — JSON-число; оценки prediction у Liveness, Face2Face и NPCK передаются строками, а не числами.

Обязательность вложенного поля всегда рассматривается только при наличии его родительского объекта. Для динамического JSON нет закрытого перечня ключей, если это прямо не указано.

Структура ответа¶

Корневой объект ответа.

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

Указатель результатов технологий¶

Одиночные блоки имеют тип object и исключаются, если соответствующей записи нет. Три массива в конце таблицы возвращаются как [], если записей нет. Наличие блоков определяется сохранёнными результатами, а не только текущим списком technologies.

Коды в таблице — значения по умолчанию в конфигурации проекта; развёрнутый сервис может использовать переопределённые коды. У разных вариантов одной технологии может быть общий блок. Отдельного persons_result, массива всех попыток Liveness или результатов каждой модели Liveness в этом ответе нет. Метаданные создания сессии, её контекст и срок действия также не входят в этот контракт.

Технологии¶

Родитель: technologies[].

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

Сведения об устройствах¶

Родитель: request_sessions[].

Поля с пометкой «Обязателен» присутствуют всегда внутри этого объекта. Остальные поля — при наличии значения; null исключается из ответа.

Одинаковые наборы всех перечисленных значений объединяются; полностью пустые записи исключаются. Это не хронология запросов и не количество попыток. Порядок элементов не следует использовать как порядок посещений.

Статус, итог и ошибки сессии¶

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

Поле: status.

Допустимые значения регистра и написания приведены точно.

flow_session_result возвращает false для любого статуса, кроме FINISHED и APPROVED. Для этих двух статусов дополнительно проверяются связанные результаты технологий Workflow, кроме технологии персон:

• отсутствующая ожидаемая связь с результатом приводит к false;
• записанная причина отказа или явный result: false у выбранного результата приводят к false;
• отсутствие значения result само по себе не равно false; для связи с несколькими записями отсутствие записей также не является самостоятельным отрицательным условием этого расчёта.

Проверка итога использует технологии Workflow без того же фильтра активности, который применяется к technologies. Поэтому flow_session_result нельзя самостоятельно восстановить простым логическим AND всех видимых result. APPROVED также не гарантирует flow_session_result: true.

result технологии отражает её правила и конфигурацию. Например, AML может быть принят при найденном совпадении, если отказ по совпадению отключён; некоторые проверки могут принять недоступность сервиса. При этом причина ошибки иногда сохраняется, и общий итог остаётся отрицательным. У KZ Info и ЕРД отдельного result вообще нет: смотрите статус получения, данные и ошибку.

Причины отказа¶

Родители: *.failure_reason (кроме адреса) и flow_session_failure_reasons[].

Для адреса предусмотрено исключение: address_result.failure_reason — строковый UUID, см. раздел адреса.

Значения failure_reason.type.

flow_session_failure_reasons[].type имеет тип свободной строки и объединяет категории технологий с категориями сессии (OTHER, EXPIRED).

Общий массив ошибок содержит ошибки сессии, затем ошибки выбранных результатов технологий в порядке Workflow. Он не является полным журналом повторных попыток; в элементах нет кода технологии, UUID ошибки или времени. Возможны повторы. Для привязки причины к проверке используйте её собственный блок.

Примеры диагностических сочетаний приведены в справочнике причин отказа. Не принимайте решение только по тексту detail. result: false не гарантирует наличие failure_reason, а наличие result: true не гарантирует отсутствие ошибки.

Незавершённые сессии и повторные попытки¶

Получение результата не требует конечного статуса. Во время прохождения доступны частичные данные, пустые массивы и блоки без result; flow_session_result: false в этот момент не означает окончательный отказ. Статусы и даты могут обновляться при следующем запросе.

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

Результаты E-Document, Document Recognition v2 и PPS могут быть скопированы из предыдущей сессии при настроенном повторном использовании данных персоны. На это указывают status: "COPIED" и source_session. Это не новое получение документа или фотографии. Возможность копирования зависит от настроек срока актуальности и проверок пригодности исходного результата.

Файлы в полном и light-ответе¶

Base64 содержит байты файла без префикса data:...;base64,. Для document_pdf это байты PDF; тип и расширение изображений нельзя определять только по названию поля. Light сохраняет имена и структуру полей, меняя значение на строку URL только в перечисленных местах.

Файловое поле доступно, если файл связан с результатом. При отсутствии файла поле исключается; словарь images старого Document Recognition может остаться {}, а массив изображений v2 — []. Некоторые файлы появляются позже остальных данных или не формируются в выбранном сценарии.

Ссылки формируются хранилищем; для S3 используется подписанный доступ. Срок действия не входит в ответ и не закреплён этим API. Не сохраняйте URL как постоянный адрес: при необходимости запросите свежий результат. Наличие URL не гарантирует, что файл не был удалён; полный ответ дополнительно требует успешного чтения файлов при формировании Base64.

Статусы запросов реестров¶

Эта таблица объясняет общие обозначения. Каждый раздел ниже задаёт свой допустимый набор: не все технологии используют все значения.

Значения поля status для адреса, ГБД ФЛ, ГБД ЮЛ, PPS и РПН.

В enum результата сохраняется регистр, приведённый в таблице.

Успешный результат¶

Ниже два целостных ответа для одной условной сессии с Liveness. Дополнительные метрики не сформированы, поэтому их полей нет. В Base64-примере использовано маленькое синтетическое PNG, а не фотография человека; URL в light вымышленный.

Полный ответ¶

{
  "id": "11111111-1111-4111-8111-111111111111",
  "status": "FINISHED",
  "validated_at": "2026-09-01T10:00:00Z",
  "finished_at": "2026-09-01T10:01:00Z",
  "flow_session_result": true,
  "technologies": [
    {
      "code": "LDD",
      "name": "Проверка живости",
      "description": "Проверка лица при изменении расстояния"
    }
  ],
  "liveness_result": {
    "result": true,
    "prediction": "0.9800",
    "face_photo": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mP8/x8AAwMCAO+aWQAAAABJRU5ErkJggg=="
  },
  "request_sessions": [],
  "flow_session_failure_reasons": [],
  "ip_check_results": [],
  "questionnaire_results": [],
  "otp_results": []
}

Light-ответ¶

{
  "id": "11111111-1111-4111-8111-111111111111",
  "status": "FINISHED",
  "validated_at": "2026-09-01T10:00:00Z",
  "finished_at": "2026-09-01T10:01:00Z",
  "flow_session_result": true,
  "technologies": [
    {
      "code": "LDD",
      "name": "Проверка живости",
      "description": "Проверка лица при изменении расстояния"
    }
  ],
  "liveness_result": {
    "result": true,
    "prediction": "0.9800",
    "face_photo": "https://files.example.invalid/liveness/face.png?signature=EXAMPLE"
  },
  "request_sessions": [],
  "flow_session_failure_reasons": [],
  "ip_check_results": [],
  "questionnaire_results": [],
  "otp_results": []
}

Неуспешный результат¶

Целостный ответ с отрицательным Liveness. 200 от метода получения такого JSON не отменяет flow_session_result: false.

{
  "id": "22222222-2222-4222-8222-222222222222",
  "status": "FAILED",
  "flow_session_result": false,
  "technologies": [
    {
      "code": "LDD",
      "name": "Проверка живости",
      "description": "Проверка лица при изменении расстояния"
    }
  ],
  "liveness_result": {
    "result": false,
    "failure_reason": {
      "type": "CALC_RESULT",
      "detail": "Low overall prediction"
    }
  },
  "request_sessions": [],
  "flow_session_failure_reasons": [
    {
      "type": "CALC_RESULT",
      "detail": "Low overall prediction"
    }
  ],
  "ip_check_results": [],
  "questionnaire_results": [],
  "otp_results": []
}

Промежуточный ответ¶

Целостный ответ до начала проверки. Отсутствие блока Liveness здесь ожидаемо.

{
  "id": "33333333-3333-4333-8333-333333333333",
  "status": "CREATED",
  "flow_session_result": false,
  "technologies": [
    {
      "code": "LDD",
      "name": "Проверка живости",
      "description": "Проверка лица при изменении расстояния"
    }
  ],
  "request_sessions": [],
  "flow_session_failure_reasons": [],
  "ip_check_results": [],
  "questionnaire_results": [],
  "otp_results": []
}

Фрагменты результатов¶

JSON-примеры на страницах технологий — фрагменты корневого объекта, а не целостные ответы. Все номера и имена условные; примеры не предназначены для отправки в API запуска проверок.

Скопированный результат распознавания v2 в light; динамический текст может содержать null:

• document_recognition_v2_result: JSON-пример.

E-Document без файлов и с повторно использованными датами:

• edocument_result: JSON-пример.

Принятая ошибка ГБД ЮЛ и адресная ошибка другого формата:

• gbdul_result: JSON-пример.
• address_result: JSON-пример.

Фото PPS остаётся ссылкой в обоих вариантах, а вопрос с файлом может не иметь value:

• pps_result: JSON-пример.
• questionnaire_results: JSON-пример.

Полученные пустые выдачи KZ Info и ЕРД, завершённое подтверждение OTP:

• kz_info_result: JSON-пример.
• erd_result: JSON-пример.
• otp_results: JSON-пример.

Остальные форматы документов и сравнения лиц (фрагмент light-ответа; блоки не обязаны встречаться в одной сессии):

• face2face_result: JSON-пример.
• npck_result: JSON-пример.
• edocument_child_result: JSON-пример.
• mxdocument_result: JSON-пример.
• mrz_result: JSON-пример.

{
  "document_recognition_result": {
    "result": true,
    "first_name": "ПРИМЕР",
    "last_name": "ПРИМЕРОВ",
    "images": {}
  }
}

Ожидание ответа реестра и полученные сведения (динамические JSON намеренно не изображены как универсальная схема):

• gbdfl_result: JSON-пример.
• rpn_result: JSON-пример.
• tunduk_result: JSON-пример.
• aml_result: JSON-пример.

Идентификация, подписание и IP-проверка:

• ds_identifier_result, ds_signer_result: JSON-пример.
• ip_check_results: JSON-пример.

Обработка ответа¶

1. Проверяйте HTTP-статус и связывайте id ответа со своей заявкой и исходным session_id.
2. Учитывайте status сессии, flow_session_result и состояние нужных технологий. Не считайте промежуточный false окончательным отказом.
3. Различайте отсутствующие поля, пустые контейнеры, пустые строки и явные отрицательные значения.
4. Для файлов применяйте таблицу full/light; не пытайтесь декодировать все файловые поля как Base64.
5. При повторном запросе учитывайте обновление выбранной записи и появление новых результатов. Не используйте этот ответ как полный журнал попыток.