LoginBot

Данное API позволяет встроить авторизацию по звонку в ваше приложение или сайт.

Документ описывает детали и возможные схемы интеграции.

Мы также предоставляем описание в формате OpenAPI. Это позволит быстро сгенерировать программный код для клиентской части. Подробнее смотрите соответствующий раздел документации.

Принцип авторизации

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

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

Вы сообщаете сервисный номер пользователю и просите позвонить на него со своего телефона.

Если на сервисный номер поступает вызов с телефона пользователя, то авторизация считается пройденной. Сам вызов система сразу сбрасывает без “поднятия трубки”. Операторы такие звонки не тарифицируют.

Если за отведенное время вызов от пользователя не поступает, то авторизация считается не пройденной.

Быстрый старт

1. Получите персональный ключ для доступа к сервису
2. Зарегистрируйте запрос на авторизацию номера телефона (метод /auth)
3. Спустя некоторое время проверьте результат авторизации (метод /status)
4. Если результат положительный, авторизуйте пользователя в своем приложении

Как работать с API

API представляет собой REST API. Параметры, передаваемые в теле HTTP-запроса, должны быть закодированы в виде JSON.

Базовый URL

Вызов методов API осуществляется по протоколу HTTPS по ссылке вида:

https://api.loginbot.ru/api/v1/{token}/{method}/{params}?{query}

Где:

• {token} – Ваш токен доступа, полученный при регистрации
• {method} – название метода API, который необходимо вызвать
• {params} – обязательные параметры, передающиеся непосредственно в URL
• {query} – дополнительные параметры в виде HTTP query string

Токен доступа

Токен доступа обеспечивает доступ к методам API. Получить его можно после регистрации.

Токен указывается в URL при каждом обращении к сервису (если не указано иное). Токен нельзя публиковать в открытом доступе и необходимо хранить в тайне.

Вызов методов

Для вызова метода необходимо указать его в конце базового URL. Параметры метода могут быть переданы разными способами, в зависимости от конкретного метода. А именно:

• Непосредственно в самом URL
• В параметрах URL (query string)
• В теле запроса, отправленного HTTP-методом POST. Параметры передаются в виде структуры JSON

Пример вызова метода с параметрами:

https://api.loginbot.ru/api/v1/{token}/call/auth/79XX9999999?timeout=180

В примере выше вызывается метод /auth. Номер телефона является обязательным параметром и передается непосредственно в самом URL. А параметр timeout является дополнительным и передается в query string.

Набор параметров, который можно указать непосредственно в URL строго ограничен и зависит от конкретного метода (смотрите описание swagger).

Некоторые методы позволяют передавать параметры как HTTP-методом GET в query, так и в теле запроса POST. Но комбинировать способы передачи нельзя. Это значит, что если вызов производится с помощью HTTP-метода POST, то все параметры должны быть переданы в теле запроса.

Ответы от методов API передаются в виде структуры в формате JSON.

Сценарий интеграции

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

Шаги для авторизации

Чтобы авторизовать пользователя по номеру телефона необходимо выполнить следующие шаги:

Получение состояния в цикле

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

Вашему приложению необходимо узнать результат авторизации. Один из способов это сделать – периодический вызов метода /status до тех пор, пока состояние запроса равно “pending”.

Не рекомендуется проверять статус чаще 1 раза в 3 секунды.

Пример (псевдокод)

requestId = http.post('call/auth/${phone}');

do {
  wait(3);
  response = http.get('call/status/${requestId}');
} while (response.status == 'pending');

if (response.status == 'accepted')
  print("Авторизация пройдена успешно");

Сигнальная ссылка (signal url)

В ответе на запрос авторизации call/auth выдается специальная ссылка signalUrl. С ее помощью можно на стороне клиентского приложения узнать о том, что пользователь завершил процесс авторизации (успешно или нет).

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

Работает сигнальная ссылка по принципу запросов long-polling. Установите обычное http-соединение методом GET с сервером по адресу из ссылки. Соединение будет висеть до тех пор, пока пользователь не авторизуется или не выйдет время, отведенное для прохождения процедуры. Не забудьте в используемом HTTP-клиенте увеличить таймауты по умолчанию на ожидание ответа.

В ответ по ссылке сервер выдаст единственный параметр “complete”. Если он false, значит авторизация еще не завершилась, и вам надо повторно установить соединение по сигнальной ссылке. Такое возможно, только если вы вручную уменьшили в сигнальной ссылке параметр timeout.

Если complete имеет значение true, значит авторизация, так или иначе, завершена. Далее вам надо узнать, как именно завершилась авторизация. Сделать это можно с бэкенда, запросив данные с помощью метода /status. Или использовать данные из вебхука, который к этому времени уже должен был сработать.

Пример (псевдокод)

authRequest = http.post('call/auth/${phone}');

http.get(authRequest.signalUrl);
response = http.get('call/status/${authRequest.requestId}');

if (response.status == 'accepted')
  print("Авторизация пройдена успешно");

Webhook (callback)

Другой способ получить информацию о том, что пользователь завершил авторизацию – это дождаться, когда система сама вызовет вебхук (webhook).

Чтобы система вызвала вебхук, его URL необходимо указать при регистрации запроса на авторизацию (см. метод /auth). Вебхук вызывается при любом исходе авторизации: пройдена, отклонена или отменена.

Ответ от обработчика вебхука игнорируется. Если в течение 5 секунд обработчик не завершит соединение, то оно прерывается автоматически.

Вебхук вызывается только один раз. При возникновении ошибок на стороне обработчика вебхука вызов не повторяется.

Вызов вебхука осуществляется HTTP-методом POST. Параметры передаются в теле запроса в виде JSON-структуры:

{
  requestId: string,
  status: string,
  phone: string,
  callToPhone: string,
  createdAt: Date,
  payload: string
}

где:

1. requestId – уникальный идентификатор запроса на авторизацию, присвоенное при регистрации запроса (метод /auth).
2. status – финальное состояние авторизации (см. описание метода /status)
3. phone – номер телефона пользователя, который проходил авторизацию
4. callToPhone – сервисный номер телефона, на который надо было позвонить
5. createdAt – дата регистрации запроса на авторизацию
6. payload – произвольные пользовательские данные, переданные при регистрации запроса на авторизацию (метод /auth)

Передача контекста (payload)

При регистрации запроса на авторизацию (метод /auth) есть возможность в параметре payload передать произвольные служебные данные. Эти данные будут доступны при завершении авторизации – в вебхуке или в ответе метода /status.

Этот механизм удобно использовать для восстановления контекста приложения. Например, таким образом можно передать внутренний идентификатор пользователя приложения в вебхук. Таким образом, в обработчике вебхука будет полная информация, какой конкретно аккаунт приложения надо авторизовать.

Обратите внимание, что данные в payload должны быть указаны в виде строки. Если вы хотите передать более сложную структуру, то ее предварительно надо сериализовать.

Пример (псевдокод)

В данном примере показан принцип передачи пользовательских данных в вебхук.

// Регистрируем запрос на авторизацию. В payload кладем внутренний ID пользователя
http.post('call/auth/${phone}', {
  payload: JSON.encode({ user_id: APP.user_id }),
  webhook: 'https://examle.com/mywebhookhandler'
});

// Говорим приложению, какая функция обрабатывает URL вебхука
APP.route('https://examle.com/mywebhookhandler', my_webhook_handler);

// ********************************************** 
// * Обработчик вебхука                         * 
// ********************************************** 
function my_webhook_handler(post) {
  // Если авторизация пройдена успешно...
  if (post.status == 'accepted') {
    // ... то авторизуем пользователя в приложении по его внутреннему ID
    payload = JSON.decode(post.payload);
    APP.do_login(payload.user_id);
  }
}

Методы API

/auth: регистрация запроса

Метод регистрирует запрос на авторизацию через звонок. После регистрации система будет ожидать звонок с телефона пользователя на сервисный номер callToPhone в течение времени, заданного параметром timeout (задается в секундах).

Полное описание метода: call/auth
HTTP-метод: POST или GET

Пример вызова:

POST /api/v1/{token}/call/auth/{phone}
Content-Type: application/json

{"timeout": 300, "webhook": "https://app.example.com/webhook", "payload": "userid=2"}

Параметры

Обязательные параметры:

• {phone} – обязательный параметр. Передается Номер телефона пользователя в формате 7XXXXXXXXXX

Опциональные параметры (передавать не обязательно):

• webhook – URL, который будет вызван автоматически сразу, как запрос на авторизацию завершится. Вебхук вызывается всегда, независимо от того успешно ли завершилась авторизация или нет. Подробнее про webhook см. соответствующий раздел.
• timeout – время в секундах, отведенное пользователю на контрольный звонок. По умолчанию – 180 секунд.
• payload – строка, в которой можно передать любые данные. Эти данные будут добавлены при вызове вебхука, а также в ответ метода /status при завершении авторизации. Может быть использован, например, для передачи ID пользователя в Вашем приложении.

Ответ

{
  "requestId": "ff1232130982131",
  "callToPhone": "79110010203",
  "validTill": "2023-05-05T16:21:51.330Z",
  "timeout": 180,
  "signalUrl": "https://api.loginbot.ru/public/status/ff1232130982131?timeout=180"
}

В ответ выдаются следующие данные…

1. callToPhone (строка) – сервисный номер телефона, на который должен быть совершен звонок. Этот номер необходимо транслировать пользователю.
2. requestId (строка) – уникальный идентификатор запроса. Он может быть использован в дальнейшем для проверки статуса авторизации и, если потребуется, для отмены запроса.
3. timeout (число) – интервал времени в секундах, за который пользователь должен завершить авторизацию
4. validTill (строка) – дата и время в формате ISO 8601, до которого надо завершить авторизацию.
5. signalUrl (строка) – публичная ссылка для запроса long-polling, который позволяет получить уведомление об изменении статуса авторизации (подробнее см. выше)

/status: проверка состояния

Метод позволяет выяснить, в каком состоянии находится зарегистрированный ранее запрос на авторизацию.

Полное описание метода: call/status
HTTP-метод: GET

Пример вызова:

GET /api/v1/{token}/call/status/{requestId}

Параметры

1. {requestId} (строка, обязательный параметр) – уникальный номер запроса, полученный при вызове метода /auth. Передается непосредственно в URL

Возможные состояния запроса

Запрос может быть в одном из состояний:

1. pending – система ожидает звонок от пользователя на сервисный номер
2. accepted – пользователь позвонил и подтвердил свой номер, тем самым успешно завершил авторизацию
3. rejected – звонок от пользователя не получен за отведенное время. Авторизация завершена отказом
4. canceled – запрос на авторизацию был отменен до его завершения. Авторизация завершена. Запрос может быть отменен вручную (см. метод см. /cancel) или автоматически. Например, если поступил новый запрос на авторизацию этого же номера, хотя старый еще не был завершен. В этом случае, старый запрос отменяется.

Ответ

{
  "status": "accepted",
  "phone": "79XX9001234",
  "payload": "my_user_id=123&user_session_id=fafbfe12"
}

Данные в ответе:

1. status (строка) – текущее состояние запроса (см. выше). Всегда присутствует в ответе
2. phone (строка) – номер телефона пользователя, который проходит проверку. Присутствует в ответе только если авторизация завершена.
3. payload (строка) – произвольные данные, переданные при формировании запроса на авторизацию (метод call/auth). Присутствует в ответе только если авторизация завершена. Предполагается, что эти данные могут быть использованы для связывания запроса с конкретными данными в приложении. Например, можно передать id пользователя приложения, который проходит авторизацию.

/cancel: отмена запроса

Метод отменяет зарегистрированный ранее запрос на авторизацию. Отмена возможна если авторизация еще не была завершена (ее статус “pending”). Отмененные запросы не тарифицируются.

Полное описание метода: call/cancel
HTTP-метод: GET

Пример вызова:

GET /api/v1/{token}/call/cancel/{requestId}

Параметры

1. {requestId} (строка, обязательный параметр) – уникальный номер запроса, полученный при вызове /auth. Передается непосредственно в URL

Ответ

{
  "success": true,
  "status": "pending"
}

Данные в ответе:

1. success (bool) – “true”, если запрос удалось отменить. Иначе “false”
2. status (строка) – состояние запроса до попытки отмены.

Особенности использования

В мобильном приложении

Авторизация звонком идеально подходит для встраивания в мобильные приложения.

Вызов на сервисный номер сбрасывается автоматически. В некоторых ситуациях пользователь остается в “программе-звонилке”. Чтобы помочь ему вернуться в приложение, рекомендуется после успешной авторизации отправить на устройство пуш-уведомление. Нажав на него, пользователь вернется в приложение.

Получив сервисный номер для контрольного звонка, можно легко открыть его в стандартной программе для набора. Человеку не придется набирать номер вручную. Для этого используйте URI вида:

tel:<номер-телефона>

Примеры

fun dialPhoneNumber(phoneNumber: String) {
    val intent = Intent(Intent.ACTION_DIAL).apply {
        data = Uri.parse("tel:$phoneNumber")
    }
    if (intent.resolveActivity(packageManager) != null) {
        startActivity(intent)
    }
}

private func callNumber(phoneNumber:String) {
  if let phoneCallURL:NSURL = NSURL(string:"tel://\(phoneNumber)") {
    let application:UIApplication = UIApplication.sharedApplication()
    if (application.canOpenURL(phoneCallURL)) {
      application.openURL(phoneCallURL);
    }
  }
}

<a href="tel:79XX1234567">Позвонить</a>

Ссылки

1. https://developer.android.com/guide/components/intents-common
2. https://developer.apple.com/library/archive/featuredarticles/iPhoneURLScheme_Reference/PhoneLinks/PhoneLinks.html

Авторизация для сайта

Авторизация звонком подходит для использования на веб-сайтах. В том числе, для так сценариев, как вход без пароля, подтверждение номера при регистрации, двухфакторная авторизация и пр.

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

1. Сценарий “Мобильный браузер”

Первое, что нужно проверить, открыта ли страница в мобильном браузере. Если это так, то для автоматического набора номера в стандартной программе для звонков используйте обычные ссылки вида tel:<номер-телефона>

2. Сценарий “Стационарный Google Chrome”

Если страница открыта на стационарном устройстве в браузере Google Chrome, и пользователь вошел в аккаунт Google, то ссылки вида “tel:” автоматически открываются в привязанном мобильном устройстве. В этом случае вводить номер вручную так же не придется.
Подробнее здесь >>

Пример кода для проверки того, что браузер Google Chrome и пользователь вошел в аккаунт:

<script type="text/javascript">
  function isChrome() {
    return /Chrome/.test(navigator.userAgent) && /Google Inc/.test(navigator.vendor);
  }
  function google_login_status(status) {
    if(isChrome() && status) {
      console.log('Has google account and browser is Chrome');
    }
  }
</script>

<img 
  style="display:none;"
  onload="google_login_status(true)"
  onerror="google_login_status(false)"
  src="https://accounts.google.com/CheckCookie?continue=https%3A%2F%2Fwww.google.com%2Fintl%2Fen%2Fimages%2Flogos%2Faccounts_logo.png&followup=https%3A%2F%2Fwww.google.com%2Fintl%2Fen%2Fimages%2Flogos%2Faccounts_logo.png&chtml=LoginDoneHtml&checkedDomains=youtube&checkConnection=youtube%3A291%3A1"
/>

3. Сценарий “Универсальный QR-код”

Для прочих случаев, когда страница открыта на стационарном компьютере, рекомендуется сгенерировать и показать пользователю QR-код с ссылкой вида “tel:”. Считав QR-код камерой телефона номер автоматически подставится в программу для звонков.

OpenAPI (swagger)

Мы предоставляем файл с описанием API в формате OpenAPI (бывший Swagger). Вы можете использовать этот файл для генерации кода клиентского приложения. Это сэкономит время и позволит быстрее сделать интеграцию.

• https://api.loginbot.ru/swagger – описание API
• https://api.loginbot.ru/swagger-json – в формате JSON для генерации кода
• https://api.loginbot.ru/swagger-yaml – в формате YAML для генерации кода

Что такое OpenAPI

Как использовать

OpenAPI (ранее известный как Swagger) это стандарт, используемый для описания API.

Есть множество утилит, которые позволяют автоматически сгенерировать код клиента из файла с описанием в формате OpenAPI. Выбор конкретной утилиты зависит от Ваших требований и стека разработки. Наиболее популярные инструменты – это OpenAPI Generator и Swagger Codegen.