Предстартовый чек-лист для приёма кодов подтверждения +375 из Беларуси

Что должно быть готово до запроса номера +375?

Прежде чем использовать номер +375 для тестирования, отметьте следующее:

• Аккаунт и пополненный кошелёк. Создайте его на странице регистрации по email и 6-значному коду из письма или через вход Google, затем внесите небольшой баланс. Включите двухфакторную защиту TOTP для аккаунта, в котором хранятся API-ключи.
• Bearer-ключ с префиксом or_live_, созданный в консоли разработчика. Выделите отдельные ключи для CI и локальной разработки; в аккаунте их может быть до 10.
• Два идентификатора, которые вы будете отправлять. Беларусь в API — это by, а идентификатор сервиса — значение api_service, возвращаемое GET /api/v1/services.
• Принимающий эндпоинт, если планируете вебхуки, с секретом подписи, хранящимся вне репозитория.
• Тестовый аккаунт в вашем продукте, которому разрешено менять или добавлять номер телефона.
• Библиотека телефонных номеров, настроенная на регион BY, чтобы номер, вставленный в форму регистрации, разбирался так, как его набрал бы настоящий белорусский пользователь.

Как записываются белорусские номера и как их хранить в приложении?

Беларусь использует код страны +375 и девятизначный национальный номер. Мобильные линии начинаются с кодов операторов, таких как 25, 29, 33 или 44, так что сохранённое значение выглядит как +37529XXXXXXX.

Сложность — в местной привычке. Внутри страны мобильный номер часто пишут с ведущим 80, например 8 029 XXX-XX-XX; это происходит от префикса междугородной связи. Этот 80 нужно убрать до добавления кода страны: форма, которая его сохраняет, порождает некорректную строку E.164, которую некоторые сервисы верификации молча отклоняют. Хорошие тесты нормализации для белорусского номера верификации:

• принимайте +375 29 ..., 375 29 ... и 8 029 ... и сохраняйте все три одинаково;
• показывайте номер в удобной для местных группировке, но отправляйте в слой SMS или верификации только E.164;
• отклоняйте номер, в котором после 375 всё ещё стоит 80.

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

Для каких сервисов белорусский номер может принимать коды?

OTP-маршрутизация для Беларуси в OTP Route сейчас охватывает более 1 400 сервисов под идентификатором by. Среди популярных маршрутов в текущем срезе: Telegram, Viber, WhatsApp, Signal, Google (Gmail & YouTube), Instagram, TikTok, Microsoft & Outlook, LinkedIn, Discord, Amazon и AliExpress.

Доступность на любом отдельном маршруте меняется в течение дня, поэтому считайте такой список отправной точкой, а не обещанием. Перед прогоном запросите GET /api/v1/prices?country=by&service=<id>, чтобы узнать текущую цену и может ли маршрут принять заказ прямо сейчас. При выборе между странами см. материал об OTP-маршрутизации по странам.

Шаг за шагом: сценарий OTP API для Беларуси из тестового скрипта

Каждый запрос уходит на https://otproute.com/api/v1 с вашим Bearer-ключом. SMS verification API достаточно мал, чтобы обернуть его в один вспомогательный метод:

1. Вызовите GET /api/v1/balance и остановите задачу заранее, если средств на кошельке не хватает для набора тестов.
2. Вызовите GET /api/v1/prices?country=by&service=telegram (подставьте свой идентификатор сервиса) и запишите в лог цену, которую собираетесь заплатить.
3. Создайте заказ через POST /api/v1/activations с телом вида {"service": "telegram", "country": "by"}. Сохраните идентификатор активации и номер +375 из ответа.
4. Отправьте этот номер на шаг ввода телефона вашего приложения и запустите отправку кода.
5. Получите код из события activation.sms_received или опрашивайте GET /api/v1/activations/{id}. Лимит — 300 запросов в минуту.
6. Если тест прерван, вызовите POST /api/v1/activations/{id}/cancel, чтобы удержанная сумма сразу вернулась на кошелёк.

Для вебхуков прочитайте заголовок X-OTPRoute-Signature (t=<unix>,v1=<hex>), вычислите HMAC-SHA256 от <t>.<raw body> секретом эндпоинта, сравните за постоянное время и отбросьте доставки с устаревшими метками времени. Привяжите обработчик к идентификатору активации, чтобы повторная доставка была безвредна. Подробности есть в документации API и в руководстве по защите вебхуков OTP с помощью HMAC.

Шаг за шагом: та же задача из панели

Сотрудники поддержки, которым время от времени нужен код, могут обойтись без API:

1. Откройте OTP Gateway в панели и выберите Беларусь.
2. Выберите сервис; цена для этого маршрута показывается до подтверждения.
3. Скопируйте номер +375 и введите его в тестируемом приложении.
4. Следите за карточкой заказа. Код появится там, как только придёт.

Если за 20 минут ничего не пришло, заказ закрывается, а вся сумма возвращается. Вы платите только тогда, когда код доставлен.

Устранение неполадок: код +375 не пришёл

Обычные причины и следующий шаг для каждой:

• Сервис отклонил номер. Некоторые платформы не принимают виртуальные номера. Правило возврата существует именно для такого случая; попробуйте маршрут другого сервиса или другую страну, если тест это допускает.
• Номер введён в местной форме. Проверьте, что форма отправила +375 и девять цифр без 80.
• Маршрут занят. Дайте окну отработать, а не отменяйте заказ через минуту, затем повторите позже.
• Ваш скрипт заказывает номера заново в плотном цикле. Добавьте задержку между попытками; быстрые повторные заказы на одном сервисе редко помогают и могут выглядеть для целевой платформы как злоупотребление.

Другие сценарии сбоев при заказах +375 разобраны в материале о том, как снизить число неудачных доставок OTP.

Есть ли долгосрочная белорусская линия и как устроена оплата?

Нет. Самостоятельно оформляемого долгосрочного номера для Беларуси в OTP Route нет. Если команде он нужен для операционной задачи или поддержки, напишите на [email protected] и опишите её; возможность что-либо предложить зависит от местных правил, и ничего не обещается. Выделенные виртуальные номера (Dedicated Virtual Numbers) — продукт для США и Канады, от $1.95/month, со входящими и исходящими SMS и звонками из браузера.

Белорусские заказы списываются с того же предоплаченного кошелька в USD, что и все остальные маршруты, без ежемесячной платы и без выбора тарифа. Пополняйте картой или стейблкоинами USDT/USDC; PDF-счёт за каждое пополнение приходит на почту. Разработчики могут запросить песочницу, которая возвращает имитированные номера и коды, — это самый дешёвый способ проверить интеграцию до реальных заказов. Используйте каждый номер только для своего продукта или своих законных аккаунтов, соблюдайте условия каждого сервиса и помните, что действует политика допустимого использования OTP Route (Acceptable Use Policy). Актуальные цены — на странице тарифов.

Частые вопросы

Можно ли протестировать регистрацию в моём приложении для Беларуси без местной SIM-карты?

Да. Закажите номер +375 для вашего сервиса в OTP Gateway, отправьте его в форму регистрации и прочитайте код в панели или через API.

Какой идентификатор страны у Беларуси в API OTP Route?

Это by. Используйте его в GET /api/v1/prices и в теле POST /api/v1/activations.

Нужно ли хранить белорусские номера с префиксом 80?

Нет. Храните их в E.164 как +375 и девять цифр, отбросив внутренний 80, иначе многие сервисы сочтут номер недействительным.

Что будет с деньгами, если на номер +375 так и не придёт код?

Когда 20-минутное окно заканчивается без SMS или вы отменяете заказ, вся сумма автоматически возвращается на кошелёк.

На каком языке придёт проверочное SMS?

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

Можно ли оставить номер +375 за собой для будущих входов?

Самостоятельно нельзя. Долгосрочные выделенные номера существуют только для США и Канады; по Беларуси можно написать на [email protected], без обещания доступности.

Можно ли протестировать интеграцию, не тратя средства кошелька?

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

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