Предстартовый чек-лист для приёма кодов подтверждения +372 в Эстонии

Что должно быть в чек-листе перед первым заказом +372?

Большинство неудачных тестовых прогонов связано с тем, чего не хватало ещё до запроса номера. Отметьте сначала следующее:

• API-ключ, созданный в консоли разработчика. Каждый ключ имеет префикс or_live_ и передаётся как Bearer-токен; в аккаунте их может быть 10, так что CI-раннеру стоит выдать отдельный ключ.
• Эндпоинт вебхука с секретом, хранящимся на сервере, если вы предпочитаете получать вызовы, а не опрашивать. На аккаунт допускается пять эндпоинтов.
• Правильные идентификаторы. Estonia во всех запросах — это ee, а идентификатор сервиса берётся из GET /api/v1/services.
• Проверка актуальной цены. Вызовите GET /api/v1/prices?country=ee&service=<id>, чтобы задача знала стоимость, прежде чем списывать средства кошелька.
• Песочница, если вы ещё настраиваете интеграцию. По запросу аккаунт разработки переключается в режим песочницы, где сквозные сценарии идут на имитированных номерах и кодах без затрат с баланса.
• Бюджет запросов. API принимает 300 запросов в минуту на аккаунт — этого хватает, если только тестовый набор не опрашивает бездумно.

Каждый из пунктов подробнее разобран в руководстве по интеграции OTP API.

Как выполнить запрос Estonia OTP API от начала до конца?

Когда чек-лист пройден, последовательность вызовов короткая:

1. POST /api/v1/activations с телом {"service": "<id>", "country": "ee"}. В ответе придут id активации и номер +372, который нужно вписать в форму регистрации или входа, проходящую тест.
2. Запустите отправку проверочного SMS из тестируемого приложения.
3. Дождитесь кода. Либо ваш эндпоинт получит activation.sms_received, либо вы с разумным интервалом вызываете GET /api/v1/activations/{id}.
4. Введите код в приложении и сохраните результат вместе с id активации.
5. Если сценарий теста изменился и номер больше не нужен, вызовите POST /api/v1/activations/{id}/cancel, чтобы резерв сразу снялся.

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

Какие сервисы могут присылать коды на эстонский номер подтверждения?

В актуальном срезе по Estonia указано более 1,700 сервисов. Среди популярных направлений WhatsApp, Telegram, Google (Gmail & YouTube), Facebook, Instagram, LinkedIn, Microsoft & Outlook, Amazon, Discord, Signal, Uber, Airbnb и ChatGPT (OpenAI).

Наличие меняется в течение дня, так что маршрут, отвечавший утром, к вечеру может оказаться скудным. Считайте источником истины GET /api/v1/countries и эндпоинт цен, а не зашивайте список в тестовые фикстуры.

Как хранить и проверять номера +372?

Эстонская нумерация — одна из самых простых, и именно поэтому на ней ломаются ленивые валидаторы. Префикса для внутренних звонков, который нужно убирать, нет: номер, записанный в национальном формате, — это те же цифры, что добавляются после +372. Мобильные номера обычно начинаются с 5 и состоят из семи или восьми цифр, поэтому регулярное выражение с жёстко заданной национальной длиной отвергнет корректные значения.

Практические правила для ваших форм и базы данных:

• Храните полную строку E.164, например +3725xxxxxxx, а исходный ввод пользователя держите отдельно, если он нужен поддержке.
• Никогда не добавляйте ноль: убирать или добавлять здесь нечего.
• Проверяйте в масках ввода и семизначные, и восьмизначные мобильные номера.

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

Зачем командам тестировать регистрацию на эстонских номерах?

Эстония заметна среди софтверных команд куда сильнее, чем можно ожидать от её размеров. Репутация цифрового государства и программа e-Residency означают, что у многих основателей и удалённых компаний есть связь со страной, даже если сотрудники живут в другом месте, а продукты для региона Балтии и Северной Европы нередко стартуют именно там.

Типовые причины, по которым QA-лид просит номер +372 для тестов:

• Проверить, как ведут себя списки стран, маски телефона и SMS-шаблоны для рынка ЕС с короткой нумерацией.
• Локализационные проверки эстонских текстов перед региональным релизом.
• Воспроизвести обращение эстонского клиента, у которого код так и не пришёл.

Как команды встраивают такие проверки в релизный цикл, описано в разделе QA-тестирование.

Что проверить, если код не приходит?

Разбирайтесь по порядку, а не заказывайте номер за номером:

1. Дайте окну отработать. Активация открыта 20 минут, а некоторые сервисы ставят сообщения в очередь.
2. Убедитесь, что сервис принимает виртуальные номера. Некоторые отклоняют их по политике; именно для этого существует возврат.
3. Посмотрите итоговый статус. Событие activation.expired или состояние «истекла» в ответе GET означает, что SMS не пришло, а деньги уже вернулись в кошелёк.
4. Повторите с терпением. Попробуйте чуть позже или возьмите другой маршрут для того же сервиса, вместо быстрого цикла повторных заказов.
5. Проверьте собственный триггер. Тест, который на деле не запрашивал SMS, выглядит так же, как потерянный код.

В материале про снижение числа неудачных доставок OTP перечислены другие причины, которые стоит исключить.

Можно ли сохранить эстонскую линию надолго и как устроена оплата?

Самостоятельно оформить долгосрочный эстонский номер нельзя. Dedicated Numbers — продукт для США и Канады от $1.95/месяц; по Estonia напишите на [email protected], если команде нужна постоянная линия, и специалисты подскажут, что допускают местные правила, не обещая доступности.

Оплата маршрутизации OTP идёт через один предоплаченный кошелёк в USD: ни абонентской платы, ни тарифа на выбор. Пополняйте картой либо USDT или USDC, и на каждое пополнение по почте приходит PDF-счёт. Актуальные ставки — на странице цен, а справочник по эндпоинтам — в документации.

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

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

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

Какой идентификатор у Estonia в API OTP Route?

Используйте ee как значение country в запросах активации и цен.

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

Нет. В Estonia такого префикса нет, поэтому национальные цифры идут после +372 без изменений.

Спишут ли деньги, если эстонский код не пришёл?

Нет. Если за 20 минут ничего не пришло или вы отменили активацию раньше, вся сумма автоматически вернётся в кошелёк.

Может ли сотрудник без навыков разработки заказать номер подтверждения для Estonia?

Да. В дашборде выберите Estonia и сервис, подтвердите показанную цену, скопируйте номер в приложение и дождитесь появления кода на том же экране.

Можно ли отработать эстонскую интеграцию, не тратя реальные средства?

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

Какие правила действуют при использовании этих номеров?

Соблюдайте правила каждого сервиса и Политику допустимого использования OTP Route; номера предназначены для тестирования и работы с вашими собственными легитимными продуктами и аккаунтами.

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