OTP API для Самоа: тестируем регистрации по номерам +685 в Тихом океане

Самоа в двух словах для продуктовых команд и QA

Самоа — независимое островное государство в Тихом океане, где официальными языками являются самоанский и английский. Большая самоанская диаспора живёт в Новой Зеландии, Австралии и США, поэтому приложениям для денежных переводов, обмена сообщениями и путешествий часто нужно работать у людей, которые перемещаются между этими странами и родиной.

Стоит знать две особенности. Во-первых, Самоа (+685) — это не Американское Самоа, которое входит в североамериканский план нумерации под кодом +1 684; если перепутать их в списке стран, коды уйдут не туда. Во-вторых, в 2011 году Самоа перешло на западную сторону линии перемены дат и живёт со сдвигом далеко вперёд относительно UTC, что делает страну удобным случаем для проверки границ дат в логике срока действия.

Для продуктовой команды Самоа редко бывает отдельным рынком запуска. Обычно эта страна появляется в рамках выхода на Тихоокеанский регион, как требование приложения для диаспоры или потому, что партнёрской организации в Апиа нужно подтвердить бизнес-аккаунт. Задача везде одна: доказать, что пользователь с номером +685 может пройти вашу регистрацию.

Как обрабатывать номер +685 в коде?

Национальные номера Самоа короткие по сравнению с большинством рынков, поэтому валидаторы, настроенные на девять-десять цифр, могут отклонить настоящий номер. Сохраняйте номер как +685 и национальные цифры без разделителей и убирайте ноль, который пользователь добавляет по привычке. Метки времени вебхуков — это секунды Unix, поэтому сравнивайте их в UTC, а не в местном времени: так вы избежите сюрпризов, когда ваш сервер и тестировщик на Самоа находятся в разных календарных днях.

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

Какие сервисы доступны на маршрутах Самоа?

В каталоге Самоа сейчас значится более 600 сервисов. Среди часто запрашиваемых — WhatsApp, Facebook, Instagram, Telegram, Google (Gmail & YouTube), Viber, Signal, TikTok, Microsoft & Outlook, Amazon и Discord. Покрытие здесь скромнее, чем на крупных рынках, и меняется в течение дня, поэтому перед каждым прогоном проверяйте GET /api/v1/services и GET /api/v1/countries. Если нужного сервиса нет, для теста может подойти соседний маршрут, например Фиджи или Тонга.

Небольшой каталог — хороший повод сделать тестовый стенд терпимым к таким случаям: если нужного сервиса нет на момент запуска, помечайте кейс как пропущенный, а не проваленный, и записывайте это, чтобы кто-нибудь повторил проверку позже.

Запрос кода для Самоа через API

Имея Bearer-ключ (or_live_…) для https://otproute.com/api/v1, узнайте цену запросом GET /api/v1/prices?country=ws&service=<id>, а затем отправьте {"service": "<id>", "country": "ws"} на POST /api/v1/activations. Следите за идентификатором активации: опрашивайте GET /api/v1/activations/{id} или слушайте событие activation.sms_received. Проверяйте HMAC в заголовке X-OTPRoute-Signature для каждого вебхука, отклоняйте устаревшие метки времени и делайте обработчик безопасным для повторного запуска по одной и той же активации. Полную схему показывает руководство по интеграции.

Для рынка такого размера лимиты щедрые: на аккаунт приходится до 10 ключей, 5 эндпоинтов вебхуков и 300 запросов в минуту. Если вы опрашиваете API, достаточно интервала в несколько секунд.

Делаем всё вручную в панели

1. Войдите в аккаунт и откройте OTP Gateway.
2. Выберите сервис, затем Самоа.
3. Проверьте актуальную цену и подтвердите заказ.
4. Вставьте номер +685 в тестируемое приложение и запросите код.
5. Прочитайте код на экране или отмените активацию, если она больше не нужна.

Если код +685 приходит медленно или не приходит

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

Записывайте идентификатор активации при каждой попытке, чтобы видеть, молчит ли конкретное приложение или весь маршрут.

Долгосрочные номера и оплата

OTP Route не продаёт самообслуживаемый долгосрочный номер Самоа. Dedicated Numbers стоят от $1.95/месяц и доступны только в США и Канаде; по линии для Самоа напишите на [email protected] — без обещания, что её удастся организовать. Предоплаченный кошелёк в долларах США принимает карты и USDT/USDC, присылает PDF-счёт за каждое пополнение и не требует абонентской платы. Запросите режим песочницы для аккаунта разработки, чтобы отработать сценарий с ws без расхода средств.

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

Самоа — это то же самое, что Американское Самоа, если говорить о номерах?

Нет. Самоа использует код +685, а Американское Самоа — +1 684. Выбирайте правильную страну и в списке стран, и в API.

Какой идентификатор страны для Самоа в API?

Используйте ws в запросе цен и в запросе на активацию.

Сколько стоит код подтверждения для Самоа?

От $0.20 за код; точная цена зависит от сервиса и показывается до заказа.

Можно ли протестировать регистрацию самоанского пользователя из Новой Зеландии или Австралии?

Да. Номер +685 принимает SMS, а OTP Route показывает его вам, где бы ни работала ваша команда.

Платить ли, если сообщение не пришло?

Нет. Истёкшие или отменённые активации автоматически возвращаются на кошелёк.

На каком языке приходят коды для Самоа?

Обычно на английском, который является официальным наряду с самоанским. Разбирайте цифры, а не окружающий текст.

Можно ли использовать эти номера, чтобы открывать много аккаунтов?

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

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