Руководство по интеграции и оценке API для верификации личности (RU)

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

Ответ API — это доказательство, а не полное бизнес-решение. Производственная интеграция также должна определять доверенный сбор данных, владение состоянием клиента, переходы статусов, повторные попытки, проверку, конфиденциальность, ведение записей и политику, которая превращает технические результаты в одобрение, повторную попытку, усиленную проверку, рассмотрение или отказ.

Основные выводы

• API верификации личности — это больше, чем одна конечная точка. Реальный контракт включает сбор данных, асинхронные состояния, доказательства, события, сверку, проверку и удаление.
• Бэкенд принимает решение. Перенаправление клиента или визуальный экран успеха не являются авторитетными; окончательное состояние должно быть подтверждено на стороне сервера.
• Результаты требуют контекста и причин. Подлинность документа, связь с держателем, живость, качество и контекстный риск должны оставаться разделимыми, а не сводиться к необъяснимому булевому значению.
• Надежность проявляется в сценариях отказа. Идемпотентность, проверка веб-хуков, повторное воспроизведение событий, тайм-ауты, повторные попытки, версионирование и паритет песочницы важны так же, как и успешный сценарий.
• Оценка должна использовать выборки, аналогичные производственным. Охват, устойчивость к мошенничеству, завершение, ложные результаты, нагрузка на проверку и конфиденциальность должны измеряться по документу, устройству, географии и соответствующему сегменту пользователя.

Что делает API верификации личности?

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

Модель проверки личности NIST SP 800-63A-4 разделяет три важные функции:

• Разрешение: отличить заявленное лицо в соответствующей популяции.
• Проверка: определить, являются ли доказательства личности и атрибуты подлинными, точными и приемлемыми.
• Подтверждение: установить, что заявитель является субъектом, связанным с этими доказательствами.

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

Сравнение API верификации личности, API документов, API KYC и OCR

Интерфейс	Основное назначение	Полезный вывод	Что он сам по себе не доказывает
OCR API	Преобразование пикселей документа в текст или поля	Извлеченные имя, дата, номер, адрес	Подлинность, владение или риск для клиента
API проверки документов	Проверка документа и собранных доказательств	Проверки подлинности, срок действия, согласованность полей, индикаторы подделки	Что текущий заявитель является его владельцем
API сопоставления лиц	Сравнение отправленного лица с эталоном	Сходство или решение о совпадении по пороговому значению	Живость, подлинность документа или юридическая личность
API проверки живости	Оценка живого присутствия при биометрическом сборе	Доказательства добросовестности, атаки, повторной попытки или оценки	Личность человека
API верификации личности	Объединение проверки доказательств и связи с заявителем	Результаты на уровне доказательств и исход рабочего процесса	Полный KYC или соответствие требованиям бизнеса
KYC API	Поддержка более широкого процесса надлежащей проверки клиента	Личность, проверка, риск, рабочий процесс и записи	Автоматическое соблюдение без политики организации

Это различие предотвращает архитектурные ошибки. Например, добавление OCR к форме загрузки ускоряет ввод данных, но не аутентифицирует документ. Добавление сопоставления лиц связывает два изображения, но не может установить, было ли какое-либо изображение получено через доверенный, живой захват.

Для получения более широкого контекста политики, проверки, риска и текущего обзора этих интерфейсов см. руководство по жизненному циклу KYC. В этой статье рассматривается граница доверия разработчика: сбор данных, состояние API, доказательства, события, сверка и решения бэкенда.

Общие модели интеграции

Размещенная сессия верификации

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

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

Встроенный веб- или мобильный SDK

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

Автономная проверка между серверами

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

Оркестрированный рабочий процесс

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

Безопасная последовательность интеграции

1. Создание попытки с бэкенда

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

Используйте стратегию идемпотентности для операций создания. Тайм-аут клиента не должен создавать вторую оплачиваемую попытку или отключать результат от исходного клиента.

2. Выдача короткоживущего токена для передачи данных

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

3. Сбор и проверка доказательств

Направляйте пользователя через поддерживаемые доказательства и требования к качеству. Отделяйте устранимые проблемы качества от предполагаемых атак. «Подойдите ближе», «срок действия документа истек» и «нарушена целостность захвата» не должны становиться одной общей ошибкой.

4. Получение аутентифицированного события

Рассматривайте веб-хуки как недоверенный ввод, пока они не будут проверены. Проверьте подпись события или аутентификацию сообщения, контроль отметки времени или свежести, ожидаемое назначение, тип контента и идентификатор события. RFC 9421 определяет общий механизм для HTTP Message Signatures, хотя поставщик может использовать другую документированную схему подписи.

Храните идентификаторы событий и обрабатывайте их идемпотентно. Системы доставки повторяют попытки; дублирующиеся события — это нормально. Не предполагайте порядок прибытия и не позволяйте старому событию переводить клиента обратно из конечного состояния.

5. Получение канонического результата

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

6. Применение политики организации

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

7. Запись перехода

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

Модель состояния, которую должен предоставлять API

Булево поле verified слишком мало для реального пути клиента. Полезные состояния часто включают:

Состояние	Значение	Типичное действие приложения
Создано	Попытка существует, но сбор данных еще не начался	Представить или повторно отправить безопасную передачу
В процессе	Пользовательские или асинхронные проверки активны	Ожидать; не предоставлять окончательный доступ
Ожидание ввода	Требуется больше доказательств или действий пользователя	Показать точные рекомендации по восстановлению
Повторная попытка разрешена	Сбор данных или качество восстановимо не удалось	Начать новую ограниченную попытку
На рассмотрении	Обученный рецензент занимается делом	Держать доступ в ожидании и показывать ожидаемый следующий шаг
Одобрено	Требуемые доказательства соответствуют настроенному рабочему процессу	Применить политику организации и переход состояния
Отклонено	Доказательства не прошли определенный контроль	Применить апелляцию, ограничение или альтернативный путь
Истек срок действия или заброшено	Попытка завершилась без решения	Разрешить контролируемый перезапуск
Техническая ошибка	Система не смогла предоставить доказательства	Повторить или сверить, не рассматривая это как мошенничество

Каждый конечный статус должен иметь структурированные причины. Стабильные машинные коды позволяют анализировать политику; локализованные человеческие сообщения помогают пользователям и рецензентам. RFC 9457 предоставляет стандартный формат для машиночитаемых сведений о проблемах HTTP на уровне интерфейса.

Какие доказательства должны содержаться в результате?

Доказательства на уровне документа

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

Доказательства связи с заявителем

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

Доказательства риска и операционные доказательства

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

Происхождение и версия

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

Требования к безопасности API

API идентификации обрабатывают ценные личные и биометрические данные и предоставляют бизнес-процессы, которые злоумышленники могут автоматизировать. OWASP API Security Top 10 выделяет риски, непосредственно относящиеся к этой области: нарушение авторизации объектов, нарушение аутентификации, чрезмерное раскрытие свойств, неограниченное потребление ресурсов, автоматизация чувствительных потоков, плохое управление API и небезопасное доверие к сторонним API.

Аутентификация и авторизация

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

Контроль загрузки и ресурсов

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

Раскрытие данных

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

Контроль веб-хуков и повторного воспроизведения

Аутентифицируйте события, сохраняйте необработанное тело, необходимое для проверки подписи, отклоняйте устаревшие или некорректные доставки, дедуплицируйте идентификаторы событий и получайте каноническое состояние. Ротируйте секреты веб-хуков, не нарушая текущую доставку.

Инвентаризация и версионирование

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

Как тестировать API верификации личности

Тесты контрактов и состояний

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

Тесты доказательств

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

Тесты на мошенничество

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

Операционные тесты

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

Тесты качества решений

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

Тесты конфиденциальности и удаления

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

Как оценивать поставщиков

Объем и гарантии

Какие функции проверки включены? Какие модели гарантии и независимые тесты применимы? Какие компоненты и версии были протестированы? Может ли поставщик объяснить, что означает и чего не означает «пройдено»?

Охват

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

Опыт разработчика

Проверьте согласованность API, качество OpenAPI, поддержку SDK, примеры, сценарии песочницы, инструменты веб-хуков, дисциплину журнала изменений, политику миграции, страницу состояния и эскалацию поддержки. Пример из пяти строк для успешного сценария — это не руководство по производственной интеграции.

Операции и объяснимость

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

Коммерческие условия и переносимость

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

Распространенные ошибки интеграции

Предоставление доступа по URL-адресу возврата

Пользователь контролирует путь браузера. Перенаправление на страницу успеха — это состояние интерфейса, а не доказательство. Подтверждайте окончательное состояние из доверенного бэкенда.

Рассмотрение каждого сбоя как мошенничества

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

Обработка веб-хуков ровно один раз

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

Логирование полных полезных нагрузок

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

Тестирование только успешного сценария песочницы

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

Передача принятия политического решения на аутсорсинг

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

Контрольный список по реализации

Перед запуском в производство убедитесь, что:

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

Использование Didit для верификации личности

Didit предоставляет верификацию личности как компонуемый модуль и позволяет командам добавлять обнаружение живости, анализ устройств и IP, а также условные пути через оркестратор рабочих процессов. Опубликованная цена за автономную верификацию личности составляет 0,15 доллара США, в то время как опубликованный пакет KYC за 0,33 доллара США включает верификацию личности, пассивную проверку живости, сопоставление лиц и анализ IP.

Страница с ценами содержит текущие тарифы на модули, а бесплатный уровень составляет 500 бесплатных проверок в месяц. Эти результаты продукта должны использоваться политикой и состоянием клиента, управляемыми бэкендом, а не заменять их.

Часто задаваемые вопросы

Что такое API верификации личности?

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

Является ли API верификации личности тем же, что и API KYC?

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

Должна ли верификация личности выполняться на фронтенде?

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

Зачем нужны веб-хуки?

Многие проверки и обзоры асинхронны. Веб-хуки уведомляют приложение об изменениях, а конечная точка получения предоставляет каноническое состояние для сверки.

Как обрабатывать дублирующиеся веб-хуки?

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

Что должна включать песочница?

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

Может ли API обеспечить соответствие компании требованиям?

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

Основные источники

• NIST SP 800-63A-4: Проверка и регистрация личности
• OWASP API Security Top 10 — 2023
• RFC 9110: Семантика HTTP
• RFC 9421: Подписи HTTP-сообщений
• RFC 9457: Сведения о проблемах для HTTP API

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