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