Qatar OTP API: вебхуки, опрос и тестовые номера +974

Как выглядит последовательность вызовов Qatar OTP API?

Всё находится по адресу https://otproute.com/api/v1, а аутентификация идёт по Bearer-ключу с префиксом or_live_. У вас может быть до 10 ключей, поэтому выдайте CI, staging и операционному скрипту отдельные ключи и отзывайте любой из них, не затрагивая остальные. Полная активация +974 занимает не более четырёх вызовов:

1. GET /api/v1/prices?country=qa&service=<id> возвращает актуальную цену и сообщает, что маршрут для этого сервиса сейчас открыт.
2. POST /api/v1/activations с телом {"service": "<id>", "country": "qa"} резервирует катарский номер и возвращает идентификатор активации.
3. GET /api/v1/activations/{id} — вызов для опроса: он показывает состояние заказа по Катару и содержит код после доставки.
4. POST /api/v1/activations/{id}/cancel досрочно завершает заказ и возвращает сумму на кошелёк.

Картину дополняют два вспомогательных вызова: GET /api/v1/services сопоставляет названия с идентификаторами сервисов, а GET /api/v1/balance позволяет пайплайну остановиться до того, как средства закончатся. Не превышайте 300 запросов в минуту на аккаунт. Справочные страницы собраны в обзоре для разработчиков.

Как обработчик вебхуков должен учитывать события активации для Катара?

Опрос работает, но вебхук позволяет вашему тестовому раннеру реагировать сразу, как только что-то происходит. Зарегистрируйте до пяти эндпоинтов и подпишитесь на activation.sms_received, activation.expired и activation.cancelled: первое событие несёт код, а два других сообщают раннеру, что ждать больше не нужно.

Каждый запрос содержит X-OTPRoute-Signature в виде t=<unix>,v1=<hex>. Соберите подписываемую строку из метки времени, точки и сырого тела запроса, посчитайте HMAC-SHA256 с секретом эндпоинта и сравните за постоянное время. Отклоняйте всё, у чего устаревшая метка времени. Поскольку повторные попытки могут доставить одно и то же событие несколько раз, сохраняйте идентификатор активации и игнорируйте повторы. Эталонную реализацию смотрите в статье о приёме OTP через вебхуки.

Какие сервисы могут направить код на номер +974?

Катар — один из самых широких маршрутов: по последнему снимку доступно более 1600 сервисов. Среди популярных — WhatsApp, Google (Gmail & YouTube), Microsoft & Outlook, Telegram, Instagram, Facebook, LinkedIn, Snapchat, TikTok, Uber, Airbnb, ChatGPT (OpenAI), Claude и Discord.

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

Нормализация катарских номеров в тестовых фикстурах

В катарских номерах после +974 идёт восемь цифр, префикса для внутренних звонков нет, поэтому при переводе местного номера в международный формат ничего отбрасывать не нужно. Храните фикстуры в E.164 (+974 и восемь цифр) и очищайте ввод, который пользователи набирают с 00974, пробелами или лишним нулём в начале по привычке из другой страны.

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

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

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

Не каждой верификации нужен скрипт. В панели откройте OTP Gateway, выберите Катар и сервис, проверьте показанную цену и подтвердите заказ. Скопируйте номер +974 в приложение, запросите SMS — и код появится в заказе. 20-минутное окно отсчитывается с момента оформления заказа, а платить нужно только в том случае, если код пришёл.

Коды не приходят: список для отладки

• Достаточно ли подождали? Дайте активации отработать всё окно, прежде чем считать её неудачной.
• Принимает ли сервис виртуальные номера? Некоторые их блокируют, и повторные попытки этого не изменят.
• Разумна ли политика повторов? Делайте паузы и повторяйте позже или переключитесь на другой маршрут для того же сервиса. Повторные заказы в плотном цикле расходуют лимит запросов и редко помогают.
• Здоров ли обработчик? Если проверка подписи не проходит или эндпоинт возвращает ошибку, опросите GET /api/v1/activations/{id}, чтобы выяснить, был ли код доставлен, пока ваш вебхук его пропустил.

Активация, закончившаяся без SMS — по истечении времени или по отмене, — возвращается полностью.

Есть ли долгосрочная катарская линия и как тарифицируется использование?

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

Использование по Катару списывается с единого предоплаченного кошелька в USD, ежемесячных платежей нет. Пополняйте картой или USDT/USDC, получайте PDF-счёт за каждое пополнение и запрашивайте режим песочницы для тестового аккаунта, если хотите проверить интеграцию на симулированных номерах. Используйте номера +974 только для собственных продуктов и законных бизнес-аккаунтов, уважайте условия каждого сервиса и следуйте Политике допустимого использования OTP Route.

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

Как получать SMS OTP-коды из Катара в автоматическом тесте?

Создайте активацию со страной qa, введите полученный номер в тестируемом приложении и дождитесь вебхука activation.sms_received. OTP Route также поддерживает опрос активации, если ваш тестовый раннер не принимает входящие запросы.

Можно ли использовать номер +974 для тестирования без катарской SIM-карты?

Да. OTP Gateway выдаёт номер для верификации в Катаре на один код, так что сценарии регистрации и входа можно проверять без местной SIM-карты и устройства.

Как узнать цены по Катару до заказа?

Вызовите GET /api/v1/prices?country=qa&service=<id> или посмотрите в панели. Ставки начинаются от $0.20 за код и зависят от сервиса.

Списываются ли деньги за неудачные активации по Катару?

Нет. Оплата взимается только за пришедший код; истёкшие и отменённые активации автоматически возвращаются на кошелёк.

Почему стоит тестировать на катарском номере, а не на номере соседней страны?

Выбирайте страну, соответствующую реальному рынку аккаунта. Если ваш продукт запускается в Катаре, номер +974 проверяет именно ту обработку кода страны, язык и OTP-маршрутизацию, которые увидят ваши клиенты, — подробнее в материале о маршрутизации по странам для OTP.

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

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

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

Не в режиме самообслуживания, поскольку выделенные линии доступны только в США и Канаде. Напишите на [email protected], если хотите узнать о долгосрочной линии в Катаре.

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