ru

Опис роботи зі шлюзом 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

Ошибка