API для приёма смс с кодом: быстрый старт

Первый: протокол handler_api. Это формат запросов, которым пользуются программы, написанные под SMS-Activate. Если ваша программа говорит на нём, вы меняете адрес API и ключ, а код оставляете как есть.

Второй: JSON API v2. В нём обычные запросы и ответы в JSON, webhooks и понятные статусы. Используйте его для всего, что пишете с нуля.

Каждый запрос идёт на один адрес, с вашим ключом и названием действия. Адрес указан в документации. Основные действия те же, что ваша программа уже отправляет.

• getNumber: купить номер для сервиса и страны.
• getStatus: узнать, пришёл ли код.
• setStatus: изменить состояние активации, например отменить её.
• getBalance: узнать баланс.

Ваш ключ находится на странице «Разработчикам» в вашем аккаунте. Отправляйте его как токен Bearer в заголовке Authorization каждого запроса.

Начните с GET /catalog. Он возвращает предложения, которые можно купить прямо сейчас, с вашей ценой, и его можно фильтровать по стране и по сервису. GET /balance возвращает баланс в долларах США. Баланс пополняется от $3.

Весь процесс состоит из нескольких вызовов.

У активации один из четырёх статусов: waiting, completed, expired или cancelled. Отменить её можно, только пока она в статусе waiting.

По умолчанию активация ждёт код десять минут, а затем истекает. В запросе на покупку можно задать ожидание короче или дольше, от двух до двадцати минут. GET /activations выводит список ваших активаций, сначала самые новые.

• POST /activations с сервисом и страной покупает номер.
• GET /activations/:id возвращает активацию. Опрашивайте его, пока не появится код.
• Или передайте в запросе на покупку адрес webhook, и мы вызовем ваш сервер, когда придёт код.
• POST /activations/:id/cancel отменяет активацию в статусе waiting с полным возвратом.

Сети дают сбои, и запрос на покупку, который завершился по тайм-ауту, мог всё же пройти. Отправляйте в POST /activations заголовок Idempotency-Key. Если повторить запрос с тем же ключом, вы получите первую активацию, а не вторую покупку.

У каждого метода свой лимит запросов, от 30 до 120 в минуту, и в документации указан каждый. Если пользоваться webhook, опрашивать почти не придётся. Webhooks подписаны, поэтому проверяйте подпись, прежде чем доверять вызову.

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

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

Большинство проблем на старте возникает из-за того, что эти шаги пропустили.

• Сначала сделайте одну активацию вручную и прочитайте каждое поле ответа.
• Намеренно дайте одной активации истечь и посмотрите, как деньги вернутся на баланс.
• Сверьте свои коды стран и сервисов с документацией. Неверный код может вернуть номер, который вам не нужен.
• Храните ключ на своём сервере и никогда не помещайте его в приложение или на веб-страницу.