Сервис SMS / Документация

Если вам на этой странице совсем ничего непонятно — напишите на infoihub.by.

Описание

API для идентификации телефонных номеров и отправки сервисных сообщений.

География работы

API предназначен в первую очередь для сайтов из Беларуси с аудиторией внутри страны. По запросу в службу поддержки мы дополнительно активируем вам возможность отправлять сообщения во все страны мира.

Стоимость

Для проверки работы у вас будет 10 бесплатных сообщений. SMS на номера белорусских операторов lifecell, velcom и мтс: 0,02 руб. Стоимость СМС в другие страны зависит от операторов и определяется шлюзом.

Начало работы

Сейчас мы в тестовом режиме, поэтому проекты подключаются вручную. Напишите на infoihub.by. Мы проверяем почту регулярно — подключение не затянется, для ускорения не забудьте упомянуть адрес вашего сайта.

После тестирования будет возможность подключиться и начать работу самостоятельно.

JS Библиотека

Для подтверждения телефонного номера мы подготовили javascript-библиотеку, которая упростит и ускорит интеграцию.

<script src="https://cdn.jsdelivr.net/gh/ihubby/js-api@master/v1.js"></script>

Запуск проверки номера

SMS_API.checkPhone(phone, success, fail)

При вызове сервис сгенерирует и отправит на номер абонента уникальный проверочный код.

  • phone строка с номером телефона
  • success(data) функция, выполняемая в случае успеха
  • fail(errCode, text) функция, выполняемая при ошибке (полный перечень см. ниже в разделе Ошибки)

Вам не обязательно обрабатывать данные, которые вернёт сервис в случае успеха. Там будет уникальный id сообщения и информация о его стоимости.

Статус отправки сообщения

SMS_API.checkStatus(success, fail, id)

При желании можно узнать о судьбе SMS, отправленной на номер.

  • success(data). Объект data имеет свойства id и status (SENT | DELIVERED | ERROR)
  • fail(errCode, text)
  • id сообщения (указывать не обязательно, библиотека использует id последнего отправленного сообщения)

Проверка кода

Для завершения проверки номера предложите пользователю ввести полученный в смс код. Проверить его можно из библиотеки методом SMS_API.checkPhoneCode(phone, code, success, fail).

  • phone номер телефона
  • code код, указанный посетителем
  • success функция выполнится, если код правильный
  • fail(errCode, text)

Более безопасно: отправить код сначала к себе на сервер, а уже там направить межсерверный запрос:

[POST] https://sms.ihub.by/api/v1/check-phone-answer-server

Пример такого запроса на языке PHP (CURL):

     $phone  = $_POST['phone'];       // номер телефона
     $code   = $_POST['code'];        // код, указанный посетителем

     $domain = 'mysite.tld';          // ваш домен
     $key    = 'my-very-secret-key';  // секретный ключ

     $curl = curl_init();
     curl_setopt($curl, CURLOPT_URL, 'https://sms.ihub.by/api/v1/check-phone-answer-server');
     curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);
     curl_setopt($curl, CURLOPT_POST, true);
     curl_setopt($curl, CURLOPT_POSTFIELDS, "domain={$domain}&key={$key}&phone={$phone}&code={$code}");
     return @json_decode(curl_exec($curl), true);

В ответ придёт JSON объект с полем status. Если status == "OK", значит код был правильный.

В обратном случае поле будет содержать ERROR, а детали ошибки можно найти в полях code и error.

Ошибки

Иногда по разным причинам сервис не сможет выполнить запрос и вернёт ошибку. Вам не обязательно разбирать текст ошибки в клиентском приложении. Достаточно проверять HTTP-код и поле code. С HTTP всё просто — успешная работа сервера вне зависимости от результата означает 200. Любое другое значение следует трактовать как временные неполадки на сервере.

Вот список возможных вариантов ошибок в поле code:

  • 0 Ошибка протокола. Встречается в JS библиотеке, если не удалось выполнить запрос (например, браузер блокирует соединение по какой-то причине)
  • 500 Ошибка на сервере. Можно попробовать повторить запрос.
  • 501 Ошибка на стороне смс-шлюза (провайдера). В таком случае в поле error будет дополнительный код ошибки. Самый распространённый вариант BAD_PHONE — когда что-то не так с номером телефона. Например слишком короткий или неверный код страны.
  • 101. Все ошибки, начинающиеся с 1 связаны с административными вопросами. 101 означает, что домен, с которого отправляется запрос не зарегистрирован в системе.
  • 102 Домен не активен
  • 103 Закончились деньги
  • 201 Неверный номер телефона
  • 202 Страна не поддерживается
  • 203 Запись не найдена (при проверке статуса SMS, когда отправили неверный id)
  • 204 Неверный проверочный код
  • 301 Сработала защита по IP (слишком много запросов с одного IP)
  • 302 Сработала защита по номеру (слишком много запросов на один номер)
  • 303 Сработала защита от перебора кода
  • 601 Не отправлены авторизационные данные
  • 602 Неверные авторизационные данные (например, когда key не подходит)

Продолжение

Мы всё ещё работаем над созданием более широкого функционала API. Следите за обновлениями.