Опис роботи зі шлюзом 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
Ваша учётная запись отключена, свяжитесь с администрацией Адміністратор вимкнув ваш аккаунт. Також у вас не має доступу до сервісів 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 Якісь із номерів не були визначені або їх відправлення відхилив оператор
Не удалось сохранить данные сообщения, свяжитесь с администрацией Можливо наша база даних перевантажена або повідомлення містить некоректні символи
Не удалось распознать статус отправки сообщения, свяжитесь с администрацией, указав тип подключения, время отправки и данные отправляемого сообщения Результат відправлення SMS не впізнано
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 не повернув успішну авторизацію
  • Втрачена сесія авторизації
Отправлено У повідомлення ще не оновлювався статус доставки
В очереди Повідомлення ще не надіслано
Сообщение передано в мобильную сеть Повідомлення доставлене на сервер оператора
Сообщение доставлено получателю
Истек срок сообщения Статус доставки не був отриманий деякий час, повідомлення загубилося
Удалено оператором Повідомлення порушує якісь правила оператора
Не доставлено
Сообщение доставлено на сервер Повідомлення на сервері відправлення
Отклонено оператором Повідомлення порушує якісь правила оператора або неможливо доставити SMS абоненту
Неизвестный статус Зв’яжіться з технічним відділом для детальної інформації
Ошибка, сообщение не отправлено Відправка повідомлення закінчилася невдачею, зв’яжіться з технічним відділом для детальної інформації
Не достаточно кредитов на счете Повідомлення не відправлено, поповніть свій внутрішній рахунок
Отправка отменена Відправка повідомлення була відкликана користувачем або адміністратором
Отправка приостановлена Відправка повідомлення була перервана користувачем або адміністратором
Удалено пользователем Користувач або адміністратор видалив дане повідомлення

1 Зверніть увагу, якщо ви маєте доступ до декількох акаунтів, то перевіряти доставку повідомлення ви повинні з того ж аккаунта, з якого і надсилали.

Приклади роботи з нашим сервісом:

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

1. PHP код

<?php
/**
 * Даний приклад надає можливість відправляти SMS-повідомлення
 * з заміною номера, переглядати залишок коштів користувача,
 * переглядати статус відправлених повідомлень.
 * -----------------------------------------------------------------
 * Для роботи даного прикладу необхідно підключити 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

Ошибка