ua

Описание работы со шлюзом TurboSMS с помощью SOAP протокола

SOAP является расширением протокола XML-RPC, который позволяет вызывать удалённые процедуры. Более подробно об этом можно прочитать в Википедии. Для связи с нашим сервером по SOAP протоколу Вам понадобится установить необходимые модули и библиотеки для его поддержки в Вашей среде разработки. Если необходимые модули и библиотеки отсутствуют, Вы можете генерировать XML нужной структуры, который нужно отправлять на наш сервер методом RAW POST. Описание структуры SOAP запросов Вы можете найти в Википедии.

Для того, чтобы иметь возможность подключаться к нашему шлюзу по протоколу SOAP, Вы должны в разделе настроек шлюза поставить галочку "SOAP" в поле «Способы подключения».

Файл описания доступных процедур и их прототипов находится по адресу:
http://turbosms.in.ua/api/wsdl.html.

Обратите внимание!

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

Наш сервер поддерживает следующие процедуры:

  1. Auth — авторизирует пользователя на сервере
  2. GetCreditBalance — возвращает остаток на счёте пользователя
  3. SendSMS — отправляет сообщения
  4. GetMessageStatus — возвращает статус доставки сообщения

1. Auth — авторизирует пользователя на сервере

Входящие параметры

Параметр Тип Назначение Обязателен
login string Ваш логин для работы со шлюзом Да
password string Ваш пароль для работы со шлюзом Да

Выходящие параметры

Параметр Тип Назначение Варианты значений Описание
AuthResult string Результат авторизации Вы успешно авторизировались Авторизация прошла успешно
Не достаточно параметров для выполнения функции Не были переданы все необходимые параметры
Неверный логин или пароль Переданные логин с паролем не найдены. Обратите внимание, что логин с паролем должны быть не те, что Вы используете для авторизации на сайте, а те, что Вы указали в разделе «Подключение к шлюзу». Так же, данное сообщение возвращается, когда метод подключения «SOAP» не отмечен в пользовательских настройках шлюза
Ваша учётная запись не активирована, свяжитесь с администрацией По каким-то причинам Ваша учётная запись не активирована. Вы не можете пользоваться никаким сервисом TurboSMS пока не активируете учётную запись
Ваша учётная запись заблокирована за нарушения, свяжитесь с администрацией Ваш аккаунт заблокирован администратором. Вам не доступен ни один сервис TurboSMS
Ваша учётная запись отключена, свяжитесь с администрацией Администратор отключил Ваш аккаунт. Также Вам не доступны сервисы TurboSMS

2. GetCreditBalance — возвращает остаток на счёте пользователя

Входящие параметры

Отсутствуют.

Выходящие параметры

Параметр Тип Назначение Варианты значений Описание
GetCreditBalanceResult string Остаток кредитов на счету пользователя Число Количество кредитов
Вы не авторизированы
  • Метод был вызван без вызова метода Auth
  • Метод Auth не вернул успешную авторизацию
  • Потеряна сессия авторизации

3. SendSMS — отправляет сообщения

Входящие параметры

Параметр Тип Назначение Обязателен
sender string Номер телефона или подпись отправителя Да
destination string Номер телефона получателя (в международном формате).
Также, можно указать несколько номеров через запятую
Да
text string Текст смс Нет 1
wappush string Ссылка WAP Push Нет 1

1 Обратите внимание, один из параметров text или wappush должен быть передан обязательно. Если они оба не переданы, Вы получите ошибку недостатка параметров

Выходящие параметры

Параметр Тип Назначение Варианты значений Описание
SendSMSResult[0] string Результат отправки сообщений Сообщения успешно отправлены 1
Не достаточно параметров для выполнения функции Не были переданы все необходимые параметры
Вы не авторизированы
  • Метод был вызван без вызова метода Auth
  • Метод Auth не вернул успешную авторизацию
  • Потеряна сессия авторизации
Неправильная подпись.\nПодпись отправителя не должна быть длиннее 11 символов и может содержать буквы латинского алфавита, цифры, а также знаки: .-& Подпись отправителя не соответствует стандартам GSM
Данная подпись запрещена администратором Вы не можете использовать данную подпись отправителя
Не хватает X кредитов для отправки SMS Не достаточно кредитов на счёте для отправки сообщения
Не удалось распознать номер получателя 1 Какой-то из номеров получателей не соответствует стандарту
Невозможно отправить SMS
При отправке SMS возникли ошибки. Если ошибка будет повторяться, сообщите об этом в службу поддержки, указав свой логин, время отправки, подпись отправителя и текст сообщения.
Возможны нарушения связи между нашей платформой и платформой операторов
Не удалось отправить сообщение на некоторые номера 1 Какие-то из номеров не были определены или их отправку отклонил оператор
Не удалось сохранить данные сообщения, свяжитесь с администрацией Возможно наша база данных перегружена или сообщение содержит некорректные символы
Не удалось распознать статус отправки сообщения, свяжитесь с администрацией, указав тип подключения, время отправки и данные отправляемого сообщения Результат отправки смс не опознан
SendSMSResult[1..X] 2 string ID отправленного сообщения c9482a41-27d1-44f8-bd5c-d34104ca5ba9 ID сообщений предоставляются в формате UUID

1 С сообщением «Сообщения успешно отправлены» может быть также сообщение «Не удалось распознать номер получателя» или «Не удалось отправить сообщение на некоторые номера»

2 Если было передано несколько номеров, то в ответном параметре ключ 1 будет содержать ID сообщения для первого номера, ключ 2 - для второго и т.д. В случаях, когда по какой-то причине на переданный номер невозможно отправить сообщение, в соответствующем ключе будет указана эта причина

4. GetMessageStatus — возвращает статус доставки сообщения

Входящие параметры

Параметр Тип Назначение Обязателен
MessageId string ID сообщения в формате UUID Да

Выходящие параметры

Параметр Тип Назначение Варианты значений Описание
GetMessageStatusResult string Текущий статус доставки сообщения Сообщение с ID X не найдено 1 ID сообщения отсутствует в базе
Не достаточно параметров для выполнения функции Не были переданы все необходимые параметры
Вы не авторизированы
  • Метод был вызван без вызова метода Auth
  • Метод Auth не вернул успешную авторизацию
  • Потеряна сессия авторизации
Отправлено У сообщения ещё не обновлялся статус доставки
В очереди Сообщение ещё не отправлено
Сообщение передано в мобильную сеть Сообщение доставлено на сервер оператора
Сообщение доставлено получателю
Истек срок сообщения Статус доставки не был получен некоторое время, сообщение потерялось
Удалено оператором Сообщение нарушает какие-то правила оператора
Не доставлено
Сообщение доставлено на сервер Сообщение на сервере отправки
Отклонено оператором Сообщение нарушает какие-то правила оператора или невозможно доставить смс абоненту
Неизвестный статус Свяжитесь с техническим отделом для большей информации
Ошибка, сообщение не отправлено Отправка сообщения закончилась неудачей, свяжитесь с техническим отделом для большей информации
Не достаточно кредитов на счете Сообщение не отправлено, пополните свой внутренний счёт
Отправка отменена Отправка сообщения была отозвана пользователем или администратором
Отправка приостановлена Отправка сообщения была прервана пользователем или администратором
Удалено пользователем Пользователь или администратор удалил данное сообщение

1 Обратите внимание, если Вы имеете доступ к нескольким аккаунтам, то проверять доставку сообщения Вы должны с того же аккаунта, с которого и отправляли

Примеры работы с нашим сервисом:

  1. PHP код
  2. Проект для .NET
  3. Модуль подключения рассылки в yii2 framework
  4. Реализация подключения к шлюзу на Ruby
  5. Реализация подключения к шлюзу на Golang

1. PHP код

<?php
/**
 * Данный пример предоставляет возможность отправлять СМС сообщения
 * с подменой номера, просматривать остаток кредитов пользователя,
 * просматривать статус отправленных сообщений.
 * -----------------------------------------------------------------
 * Для работы данного примера необходимо подключить SOAP-расширение.
 */

// Все данные возвращаются в кодировке UTF-8
header('Content-type: text/html; charset=utf-8');

echo '<pre>';
try {

    // Подключаемся к серверу
    $client = new SoapClient('http://turbosms.in.ua/api/wsdl.html');

    // Можно просмотреть список доступных методов сервера
    print_r($client->__getFunctions());

    // Данные авторизации
    $auth = [
        'login' => 'ваш_логин',
        'password' => 'ваш_пароль'
    ];

    // Авторизируемся на сервере
    $result = $client->Auth($auth);

    // Результат авторизации
    echo $result->AuthResult . PHP_EOL;

    // Получаем количество доступных кредитов
    $result = $client->GetCreditBalance();
    echo $result->GetCreditBalanceResult . PHP_EOL;

    // Текст сообщения ОБЯЗАТЕЛЬНО отправлять в кодировке UTF-8
    $text = iconv('windows-1251', 'utf-8', 'Это сообщение будет доставлено на указанный номер');

    // Отправляем сообщение на один номер.
    // Подпись отправителя может содержать английские буквы и цифры. Максимальная длина - 11 символов.
    // Номер указывается в полном формате, включая плюс и код страны
    $sms = [
        'sender' => 'Rassilka',
        'destination' => '+380XXXXXXXXX',
        'text' => $text
    ];
    $result = $client->SendSMS($sms);

    // Отправляем сообщение на несколько номеров.
    // Номера разделены запятыми без пробелов.
    $sms = [
        'sender' => 'Rassilka',
        'destination' => '+380XXXXXXXX1,+380XXXXXXXX2,+380XXXXXXXX3',
        'text' => $text
    ];
    $result = $client->SendSMS($sms);

    // Выводим результат отправки.
    echo $result->SendSMSResult->ResultArray[0] . PHP_EOL;

    // ID первого сообщения
    echo $result->SendSMSResult->ResultArray[1] . PHP_EOL;

    // ID второго сообщения
    echo $result->SendSMSResult->ResultArray[2] . PHP_EOL;

    // Отправляем сообщение с WAPPush ссылкой
    // Ссылка должна включать http://
    $sms = [
        'sender' => 'Rassilka',
        'destination' => '+380XXXXXXXXX',
        'text' => $text,
        'wappush' => 'http://super-site.com'
    ];
    $result = $client->SendSMS($sms);

    // Запрашиваем статус конкретного сообщения по ID
    $sms = ['MessageId' => 'c9482a41-27d1-44f8-bd5c-d34104ca5ba9'];
    $status = $client->GetMessageStatus($sms);
    echo $status->GetMessageStatusResult . PHP_EOL;

} catch(Exception $e) {
    echo 'Ошибка: ' . $e->getMessage() . PHP_EOL;
}
echo '</pre>';
?>

2. Проект для .NET

Скачать архив

3. Модуль подключения рассылки в yii2 framework

Смотреть на GitHub

4. Реализация подключения к шлюзу на Ruby

Смотреть на GitHub

5. Реализация подключения к шлюзу на Golang

Смотреть на GitHub

Ошибка