Интеграция
Onfido и вердикт, который не «да» и не «нет»
Onfido проверяет личность по документам и биометрии и возвращает результат, который затем применяет ваш бот. Итог здесь не двоичный: проверка может завершиться чистым результатом, отказом или промежуточным consider — и главное проектное решение в том, что consider означает для ваших правил доступа.
Onfido — интеграция: доступ, лимиты и доступность
- Модель авторизации
- Ключ API
- Модель отчётов
- Одна проверка даёт несколько отчётов плюс выведенный общий итог
- Доступность в Заливе
- Используется регулируемыми компаниями Залива; покрытие документов проверяйте по рынкам
- Поток данных
- 5 переходов, через воркер
As of 2025-10-01, Telegram Bot API 13.4
Зачем нужна эта интеграция
Onfido чаще выбирают там, где требование проверять личность пришло из финансовых услуг или из регулируемой отрасли вообще, а не из крипты, и его модель это отражает. Вместо единственного вердикта проверка порождает набор отчётов — подлинность документа, сходство лица, сверка со списками, — у каждого свой результат, а общий итог из них выводится.
Такая дробность действительно полезна и заставляет принять решение, от которого большинство интеграций предпочло бы уклониться. Кроме чистого результата и отказа есть consider: автоматические проверки нашли что-то, на что стоит взглянуть человеку. Это не провал. Считать его провалом — отказывать реальным клиентам, которые всего лишь плохо сфотографировали документ; считать его пропуском — обессмыслить саму проверку.
Правильный ответ — очередь ручного разбора с поимённо названным владельцем и целевым сроком ответа, согласованными до запуска. Это обязательство операционное, а не инженерное, и проект, выехавший без него, за пару недель тихо сведёт consider либо к «всегда одобряем», либо к «всегда отказываем» — смотря что вызывает меньше жалоб от того, кто громче кричит.
Как на самом деле движутся данные
Токен API лежит секретом воркера, а базовый адрес зависит от региона и обязан совпадать с тем регионом, в котором был создан аккаунт. Вебхуки подписаны, и подпись проверяется по сырому телу запроса до того, как содержимому поверили: непроверяющий адрес принимает поддельные вердикты об успешной проверке.
Модель доступа: API-ключ
Их лимиты и что они означают для вас
Одна проверка порождает несколько отчётов, у каждого свой результат, плюс выведенный из них общий итог.
Правила доступа можно писать по отдельным отчётам, а не по сводке. Ради этой дробности Onfido и выбирают, и она пропадает впустую, если читать только общий результат.
Базовые адреса API зависят от региона, и токен одного региона не действует в другом.
Регион задаётся явной настройкой и проверяется при старте. Как и у нескольких других провайдеров, несовпадение выглядит ошибкой авторизации и отправляет людей перепроверять доступы, с которыми всё было в порядке.
Сценарии проверки версионируются, и правка одного влияет на проверки, созданные после неё.
Изменение сценария — событие того же класса, что и выкатка. Двух заявителей с разницей в сутки могут оценить по разным правилам, и это становится важным ровно тогда, когда кто-то спрашивает почему.
События вебхука подписаны и доставляются не менее одного раза.
Нужна проверка подписи по сырому телу и идемпотентная обработка по идентификатору проверки. И то и другое невелико по объёму, и то и другое регулярно пропускают.
Как это ломается и что происходит потом
Приходит итог consider, а очередью ручного разбора никто не владеет.
Заявитель ждёт бесконечно. Это самый частый операционный провал с Onfido, и решается он расстановкой людей, а не техникой, — потому и согласуется до запуска.
Плохая фотография даёт consider по подлинности документа.
Заявителю предлагают повторить съёмку с конкретными подсказками, а не отказывают. Заметная доля промежуточных итогов — это освещение и фокус, а не мошенничество.
Проверка подписи вебхука отказывает после того, как прокси изменил тело запроса.
Проверка идёт по сырым байтам, как они пришли. Любая прослойка, переформатирующая JSON, её ломает, и знать об этом лучше до того, как такую прослойку добавили.
Проверка завершилась, но вебхук потерялся.
Сверочная задача опрашивает проверки, висящие дольше порога. Завершённая проверка, по которой никто ничего не сделал, для заявителя неотличима от отказа.
Доступность в ОАЭ и остальных странах Залива
Весь мир
Широкое покрытие по документам и хостинг по регионам. Проверяйте покрытие по гражданствам, которые реально есть у ваших пользователей, а не по стране, в которой работаете вы.
Объединённые Арабские Эмираты и страны Залива
Используется регулируемыми компаниями региона. Обязанности идут от вашей собственной лицензии; провайдер даёт доказательства, но обязанностей с вас не снимает.
Финансовые услуги
Контекст, в котором Onfido обычно предпочитают провайдерам с криптоуклоном, — прежде всего из-за дробности отчётов и сверки со списками.
Место хранения данных
Выбор региона определяет, где лежат данные о личности. Регион выбирают до создания аккаунта, потому что менять его потом не предполагается.
Когда эту интеграцию делать не нужно
- Очередью ручного разбора никто не будет владеть. Промежуточные итоги — обычная часть модели, и бесхозная очередь означает, что заявители ждут вечно.
- Вы всё равно читаете только общий итог. Тогда вы платите за дробность отчётов, которую выбрасываете, и вам подошёл бы провайдер попроще.
- Вам нужен сбор документов, а не проверка личности. Это другая задача и заметно более дешёвая разработка.
- Вы ещё не выбрали регион хранения данных. После создания аккаунта его не поменять, и решить проще, чем потом переезжать.
На чём это работает
| Компонент | Версия | Зачем |
|---|---|---|
| Cloudflare Workers | current | Создание заявителей и проверок, сверка подписей, обработка вебхуков. |
| Cloudflare D1 | current | Результаты по каждому отчёту, состояние очереди разбора и след доказательств. |
| Zod | 4.4 | Проверка полезной нагрузки вебхука после того, как проверена подпись. |
| grammY | 1.45 | Разговор с заявителем, подсказки для повторной съёмки и сам допуск. |
Вопросы, которые возникают при оценке
Что означает промежуточный итог consider и что с ним делать?
Что автоматические проверки нашли повод показать заявку человеку. Это не провал. Для него нужна очередь ручного разбора с названным владельцем и целевым сроком ответа, согласованными до запуска, иначе за пару недель интеграция тихо сползёт в «всегда одобряем» или «всегда отказываем».
Чем это отличается от связки с Sumsub?
Onfido возвращает дробные результаты по каждому отчёту и чаще встречается в финансовых услугах; Sumsub чаще берут криптокомпании, и покрытие у него в этом сегменте шире. Модель вебхуков рабочая у обоих, а выбор обычно диктуют ваша отрасль и уже заключённые договоры.
Почему проверки отваливаются по авторизации, хотя токен верный?
Несовпадение региона. Базовые адреса привязаны к региону, а токены между регионами не переносятся, и ошибка при этом выглядит как проблема доступа, а не маршрутизации. Проверка при старте превращает день недоумения в сообщение на выкатке.
Надо ли отказывать заявителю из-за плохой фотографии?
Нет. Заметная доля промежуточных итогов — это освещение и фокус, а не мошенничество, поэтому заявителю предлагают повторить съёмку с конкретными подсказками. Отказ здесь теряет реальных клиентов по причине, которую легко устранить.
Что будет, если сценарий проверки поменяли посреди проекта?
Созданные после этого проверки оцениваются по новой версии, так что двух заявителей с разницей в сутки могут судить по разным правилам. Поэтому правка сценария считается событием уровня выкатки: разница становится важна, когда спрашивают, почему одного пустили.
Нужна ли нам сверка по спискам наблюдения?
Это вопрос к вашему юристу, а не предпочтение в настройках. Технически она доступна как часть проверки; обязаны ли вы её запускать, зависит от вашей лицензии и от того, чем вы занимаетесь.
Что почитать дальше
Если нужна альтернатива с криптоуклоном и более широким покрытием в этом сегменте, смотрите интеграцию с Sumsub.
Исполнение правила и след доказательств описывает разбор бота доступа по KYC.
Когда нужно собрать файлы, а не проверить личность, более дешёвый вариант — это разбор бота сбора документов.
Остальные провайдеры, которых обычно касается регулируемый сценарий, разобраны в полном списке интеграций.