Протокол интеграции Flash call and Voice code

Протокол интеграции Flash call and Voice code

ВНИМАНИЕ!

Для использования данного вида интеграции вам необходимо зарегистрироваться на серверной платформе Stream Telecom либо с помощью менеджера компании.

Получение услуги доступно только по 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: http://gateway.api.sc/ (ssl: https://gateway.api.sc/).

ПРОВЕРКА КОРРЕКТНОСТИ ЗАПРОСОВ

Корректность формирования запросов и ответов можно проверить по адресу: https://gateway.api.sc/test_post.php

Stream_Telecom_FlashCall__1.0.5.pdf

Функции

ЗАПРОС НА ИНИЦИАЦИЮ FLASH CALL ИЛИ VOICE CODE

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

  1. Пример 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/
  2. Пример GET-запроса Voice Code с передачей кода в запросе

    https://gateway.api.sc/flash/?login=testuser&pass=userpassword&type=voice&code=2424
            &phone=79999999999&callback_url=https://my.site.com/
  3. Пример 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/
  4. Пример 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

Способ передачи кода:
"flash" – Flash Call
"voice" – Voice Code

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.

Текст СМС с кодом определяется следующим образом:

  1. Если в запросе указан текст СМС для каскадной отправки (параметр sms_text), будет отправлен этот текст.
  2. Вы можете задать общий текст СМС для каскадной отправки. Для этого обратитесь в службу поддержки. Этот текст будет отправлен, если текст сообщения не передан в запросе.
  3. В случае если текст не передан в запросе и не задан общий текст, будет отправлен единый для всех текст сообщения: "Ваш код авторизации: #code#".

Примеры запроса

  1. Пример 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/
  2. Пример 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/
  3. Пример 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/
  4. Пример 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

Способ передачи кода:
"flash" – Flash Call
"voice" – Voice Code

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.

Примеры сообщений о статусе оказания услуги

  1. Успешная отправка кода методом Voice Code

    
          {
            id: "171",
            user_id: 0,
            status: "ANSWERED",
            phone: "79999999999",
            time_change_state: 2022-06-04 11:03:00,
            type: "voice_code"
          }
        
  2. Неуспешная отправка кода методом Flash Call

    
          {
            id: "171",
            user_id: 0,
            status: "NO ANSWER",
            phone: "79999999999",
            time_change_state: 2022-06-04 11:03:00,
            type: "flash_call"
          }
        
  3. Успешная доставка каскадного СМС

    
          {
            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