Протокол интеграции Flash call and Voice code
ВНИМАНИЕ!
Для использования данного вида интеграции вам необходимоПолучение услуги доступно только по API.
Пароль для интеграции задается в настройках пользователя во вкладке Настройки API.
ОПИСАНИЕ УСЛУГИ
Данная услуга позволяет передавать абоненту четырёхзначный код доступа одним из двух способов:
- Flash Call – передача кода подтверждения, как последние 4 цифры номера телефона, с которого осуществляется вызов конечному абоненту.
- Voice Code – передача кода подтверждения путем диктовки кода в рамках звонка конечному абоненту.
Код может быть передан в запросе или сгенерирован на стороне сервиса. При передаче кода в запросе отправка кодов Flash Call и Voice Code возможна только на телефонные номера РФ. При генерации кода на стороне сервиса отправка может быть осуществлена на международные направления.
Вы можете использовать каскадную отправку кода подтверждения: при неполучении кода описанными выше способами он будет отправлен абоненту посредством СМС. При передаче кода в запросе каскадная отправка СМС возможна только на мобильные телефонные номера РФ. При генерации кода на стороне сервиса отправка может быть осуществлена на международные мобильные телефонные номера. Для отправки СМС необходимо зарегистрировать имя отправителя. Зарегистрировать имя отправителя вы можете в разделе «СМС» личного кабинета или обратившись к менеджеру Stream Telecom.
По умолчанию для услуги настроен следующий AntiFraud-механизм: блокируется отправка более 1 кода на один номер телефона чаще одного раза в минуту и 100 кодов на любые номера за 10 минут. Для изменения настроек AntiFraud-механизмов обратитесь в техническую поддержку.
ОБЩИЕ ПОЛОЖЕНИЯ
Серверная платформа Stream Telecom (далее Платформа) и клиент сервиса (далее Клиент) обмениваются HTTPS URL – encoded запросами, используя форматы передач данных JSON в соответствии с принципами REST. Действие над данными задается с помощью методов GET или POST в кодировке UTF-8.
ТОЧКА ДОСТУПА
Запросы Клиента должны передаваться на Платформу по URL:
ПРОВЕРКА КОРРЕКТНОСТИ ЗАПРОСОВ
Корректность формирования запросов и ответов можно проверить по адресу:
Функции
ЗАПРОС НА ИНИЦИАЦИЮ FLASH CALL ИЛИ VOICE CODE
Примеры запросов
-
Пример GET-запроса Flash Сall с генерацией кода на стороне сервиса
https://gateway.api.sc/flash/?login=testuser&pass=userpassword&type=flash&code_gen=true &phone=79999999999&callback_url=https://my.site.com/
-
Пример GET-запроса Voice Code с передачей кода в запросе
https://gateway.api.sc/flash/?login=testuser&pass=userpassword&type=voice&code=2424 &phone=79999999999&callback_url=https://my.site.com/
-
Пример POST запроса Flash Сall с передачей кода в запросе
HTTP/1.1 HOST: http://gateway.api.sc/flash/ Content-Type: application/x-www-form-urlencoded HTTP/1.1 100 Continue login=testuser &pass=userpassword &type=flash &code=2424 &phone=79999999999 &callback_url=https://my.site.com/
-
Пример POST запроса Voice Code с генерацией кода на стороне сервиса
HTTP/1.1 HOST: http://gateway.api.sc/flash/ Content-Type: application/x-www-form-urlencoded HTTP/1.1 100 Continue login=testuser &pass=userpassword &type=voice &code_gen=true &phone=79999999999 &callback_url=https://my.site.com/
Описание параметров запроса
Название |
Обязательное поле |
Тип данных |
Описание |
---|---|---|---|
login |
Да |
String |
Логин от учетной записи Stream Telecom |
pass |
Да |
String |
Пароль API от учетной записи Stream Telecom |
type |
Да |
String |
Способ передачи кода: |
code_gen |
Нет |
Boolean |
Параметр, при передаче значения true в котором, код будет сгенерирован на стороне сервиса. При генерации кода на стороне сервиса код (параметр code) передавать не нужно. Отправка может быть осуществлена на международные направления |
code |
Нет |
Integer |
Четырёхзначный код для передачи |
phone |
Да |
String |
Номер телефона конечного абонента |
callback_url |
Нет |
String |
URL-адрес для получения информации о статусе оказания услуги |
Примеры ответов
{
"result": "Success",
"code": "2424",
}
{
"result": "Error",
"message": "Tariff error. No price for this direction."
}
Описание параметров ответа
Параметр |
Описание |
---|---|
result |
Описание результата |
code |
Код, сгенерированный сервисом |
message |
Текст сообщения об ошибке (при возникновении) |
ЗАПРОС НА ИНИЦИАЦИЮ FLASH CALL ИЛИ VOICE CODE C ИСПОЛЬЗОВАНИЕМ КАСКАДНОЙ ОТПРАВКИ СМС
Вы можете использовать каскадную отправку кода подтверждения: при неполучении кода с помощью Flash Сall или Voice Code он будет отправлен абоненту посредством СМС. Для отправки СМС необходимо зарегистрировать имя отправителя. Зарегистрировать имя отправителя вы можете в разделе «СМС» личного кабинета, или обратившись к менеджеру Stream Telecom.
Для использования каскадной отправки кода подтверждения необходимо указать в запросе значение параметра sms_originator.
Текст СМС с кодом определяется следующим образом:
- Если в запросе указан текст СМС для каскадной отправки (параметр sms_text), будет отправлен этот текст.
- Вы можете задать общий текст СМС для каскадной отправки. Для этого обратитесь в службу поддержки. Этот текст будет отправлен, если текст сообщения не передан в запросе.
- В случае если текст не передан в запросе и не задан общий текст, будет отправлен единый для всех текст сообщения: "Ваш код авторизации: #code#".
Примеры запроса
-
Пример GET-запроса Flash Сall с генерацией кода на стороне сервиса с каскадной отправкой СМС
https://gateway.api.sc/flash/?login=testuser&pass=userpassword&type=flash &code_gen=true&phone=79999999999&sms_originator=RUSInfo&sms_text="Ваш код подтверждения #code#" &callback_url=https://my.site.com/
-
Пример GET-запроса Voice Code с каскадной отправкой СМС
https://gateway.api.sc/flash/?login=testuser&pass=userpassword&type=voice &code=2424&phone=79999999999&sms_originator=RUSInfo&sms_text=&Ваш код подтверждения 2424 &callback_url=https://my.site.com/
-
Пример POST запроса Flash Сall с каскадной отправкой СМС
HTTP/1.1 HOST: http://gateway.api.sc/flash/ Content-Type: application/x-www-form-urlencoded HTTP/1.1 100 Continue login=testuser &pass=userpassword &type=flash &code=2424 &phone=79999999999 &sms_originator=RUSInfo &sms_text="Ваш код подтверждения 2424" &callback_url=https://my.site.com/
-
Пример POST запроса Voice Code с генерацией кода на стороне сервиса с каскадной отправкой СМС
HTTP/1.1 HOST: http://gateway.api.sc/flash/ Content-Type: application/x-www-form-urlencoded HTTP/1.1 100 Continue login=testuser &pass=userpassword &type=voice &code_gen=true &phone=79999999999 &sms_originator=RUSInfo &sms_text="Ваш код подтверждения #code#" &callback_url=https://my.site.com/
Описание параметров запроса
Название |
Обязательное поле |
Тип данных |
Описание |
---|---|---|---|
login |
Да |
String |
Логин от учетной записи Stream Telecom |
pass |
Да |
String |
Пароль API от учетной записи Stream Telecom |
type |
Да |
String |
Способ передачи кода: |
code_gen |
Нет |
Boolean |
Параметр, при передаче значения true в котором, код будет сгенерирован на стороне сервиса. При генерации кода на стороне сервиса код (параметр code) передавать не нужно. Отправка может быть осуществлена на международные направления |
code |
Нет |
Integer |
Четырёхзначный код для передачи |
phone |
Да |
String |
Номер телефона конечного абонента |
sms_originator |
Нет |
String |
Имя отправителя для каскадной отправки СМС. Передача данного параметра определяет, будет ли отправлено каскадное сообщение. Если параметр не передан, то СМС отправлено не будет |
sms_text |
Нет |
String |
Текст СМС для каскадной отправки. Код в тексте СМС обозначается тегом #code# |
callback_url |
Нет |
String |
URL-адрес для получения информации о статусе оказания услуги |
Примеры ответа
{
"result": "Success",
"code": "2424",
}
{
"result": "Error",
"message": "Tariff error. No price for this direction."
}
Описание параметров ответа
Параметр |
Описание |
---|---|
result |
Описание результата |
code |
Код, сгенерированный сервисом |
message |
Текст сообщения об ошибке (при возникновении) |
СТАТУС ОКАЗАНИЯ УСЛУГИ
Для получения конечного статуса оказания услуги укажите в запросе значение параметра callback_url.
Примеры сообщений о статусе оказания услуги
-
Успешная отправка кода методом Voice Code
{ id: "171", user_id: 0, status: "ANSWERED", phone: "79999999999", time_change_state: 2022-06-04 11:03:00, type: "voice_code" }
-
Неуспешная отправка кода методом Flash Call
{ id: "171", user_id: 0, status: "NO ANSWER", phone: "79999999999", time_change_state: 2022-06-04 11:03:00, type: "flash_call" }
-
Успешная доставка каскадного СМС
{ id: "12313212380892930409", user_id: 0, status: "deliver", phone: "79999999999", time_change_state: 2022-06-04 11:03:00, type: "sms" }
Параметр |
Описание |
---|---|
id |
Идентификатор фактически оказанной услуги |
user_id |
Пользовательский идентификатор |
status |
Значение итогового статуса |
phone |
Номер телефона, на который осуществлялась отправка |
time_change_state |
Дата и время последнего изменения статуса оказания услуги |
type |
Тип итоговой услуги |
ПЕРЕЧЕНЬ ТИПОВЫХ СООБЩЕНИЙ ОБ ОШИБКАХ И ИХ ОПИСАНИЕ
Message | Описание | Error during request processing | Ошибка при выполнении запроса |
---|---|
Not correct phone | Некорректный номер телефона |
Invalid source address | Неверное имя отправителя |
Invalid SMS text | Неверный текст SMS |
Tariff error. No price for this direction | Не указан тариф для выбранного направления |
Direction is closed | Данное направление закрыто |
No input data | Нет входящих данных |
%Field% cannot be empty or not string | Поле не может быть пустым, значение поля должно быть строкой %Field% - имя поля |
Incorrect login or password | Неправильный логин или пароль |
Access denied | Доступ запрещен |
User blocked | Ваш аккаунт заблокирован |
Too many requests | Превышен лимит количества запросов |
System Failed | Ошибка сервера |
Code must be four digits | Код должен быть из 4-х цифр |
Type must be flash or voice | Тип должен быть flash или voice |