| SOAP протоколОписФайл опису методів веб-сервісу: https://smsc.ua/sys/soap.php?wsdl
У Сервісі доступні методи для відправки повідомлень і отримання вартості, перевірки статусів і стану балансу.
Всі параметри повинні передаватися в кодуванні UTF-8.Відправка повідомлення
Для відправки SMS-повідомлень використовуються методи send_sms і send_sms2.
У методі send_sms2 є можливість додавання додаткових параметрів.
$client = new SoapClient('https://smsc.ua/sys/soap.php?wsdl'); $ret = $client->send_sms(array('login'=>'alex', 'psw'=>'123', 'phones'=>'79999999999', 'mes'=>'Hello world!', 'id'=>'', 'sender'=>'ivan', 'time'=>0));
Опис параметрів, що передаються Серверу :
Параметр | Значення
|
---|
login | Логін Клієнта.
|
---|
psw | Пароль Клієнта (можна додати або редагувати на даннійсторінці).
|
---|
apikey | Спеціальний API-ключ, який використовується для спрощеної авторизації замість пари "логін + пароль" (можна створити на даний сторінка).
|
---|
phones | Номер або розділений комою або крапкою з комою список номерів мобільних телефонів в міжнародному форматі,
на які відправляється повідомлення. Номери можуть передаватися без знака "+".
Якщо номер переданий без знака "+", то він може бути виправлений автоматичним форматуванням
і приведений до правильного міжнародного формату. Таким чином, деякі
помилки при введенні номерів телефонів можуть бути виправлені автоматично.
Для відключення автовиправлення передайте номер зі знаком "+".
Також можна відправляти повідомлення на групу номерів, вказавши спеціальний код "G<номер группы>".
Повідомлення буде відправлено на всі номери, що належать цій групі. Для E-mail повідомлення передається список e-mail адрес одержувачів. Для telegram в якості одержувача повідомлення можлива вказівка Ніка абонента або його ID у вигляді #ID.
|
---|
mes | Текст повідомлення, що відправляється. Максимальний розмір – 1000 символів. Повідомлення при
необхідності буде розбите на кілька SMS, відправлених абоненту і оплачених окремо. Розмір одного
SMS – 160 символів у латиниці або 70 символів у кирилиці. При розбивці повідомлення на кілька SMS в кожну частину
додається заголовок для об'єднання частин в одне повідомлення на телефоні одержувача, і максимальна довжина стає
67 для кирилиці і 153 для латинських букв. У текст повідомлення можна додавати коментарі,
призначені для перегляду відправником історії в особистому кабінеті.
|
---|
id | Ідентифікатор повідомлення. Призначається Клієнтом. Служить для подальшої ідентифікації повідомлення. Якщо не вказувати, то буде призначений автоматично. Не обов'язково унікальний. Ідентифікатор являє собою 32-бітне число в діапазоні від 1 до 2147483647, або рядок довжиною до 40 символів, який складається із латинських букв, цифр і символів ".-_".
|
---|
sender | Ім'я відправника, що відображається в телефоні одержувача.
Дозволені англійські букви, цифри, пробіл і деякі символи. Довжина – 11 символів або 15 цифр.
Всі імена реєструються в особистому кабінеті на даній сторінці.
|
---|
time | Час відправки SMS-повідомлення абоненту.
Формати:
- DDMMYYhhmm або DD.MM.YY hh: mm.
- h1-h2. Задає діапазон часу в годиннику. Якщо поточний час менше h1, то SMS-повідомлення
буде відправлено абоненту при настанні часу h1, якщо поточний час потрапляє в проміжок від h1 до h2,
то повідомлення буде відправлено негайно, в іншому випадку відправка буде виконана на наступний день при
досягненні часу h1. Ця функція, наприклад, корисна для того, щоб не допустити отримання SMS-повідомлень
абонентами в нічний час.
- 0ts, де ts-timestamp, час у секундах, що минув з 1 січня 1970 року.
- +m. задає відносне зміщення часу від поточного в хвилинах. Символ + повинен кодуватися як %2B в http-запиті.
Якщо time = 0 або вказано вже минулий час, то повідомлення буде відправлено негайно.
|
---|
query | Рядок додаткових параметрів (тільки в send_sms2),
переданих у форматі: 'параметр1=значення-1&параметр2=значення-2'.
|
---|
Додаткові параметри передаються в ' query'
|
---|
tz | Часовий пояс, в якому задається параметр time. Вказується щодо московського часу.
Параметр tz може бути як позитивним, так і негативним. Якщо tz дорівнює 0, то буде використаний московський часовий
пояс, якщо ж параметр tz не заданий, то часовий пояс буде взятий із налаштувань клієнта.
|
---|
period | Проміжок часу, протягом якого необхідно відправити розсилку. Являє собою число
в діапазоні від 0.1 до 720 годин. Застосовується спільно з параметром freq. Даний параметр дозволяє розтягнути розсилку в
часі для поступового отримання SMS-повідомлень абонентами.
|
---|
freq | Інтервал або частота, з якою потрібно відправляти SMS-розсилку на чергову групу номерів. Кількість
номерів у групі розраховується автоматично на основі параметрів period і freq. Задається в проміжку від 1 до 1440 хвилин.
Без параметра period параметр freq ігнорується.
|
---|
flash | Ознака Flash повідомлення, що відображається одразу на екрані телефону.
0 (за замовчуванням) – звичайне повідомлення. 1 – Flash повідомлення.
|
---|
bin | Ознака бінарного повідомлення. 0 (за замовчуванням) – звичайне повідомлення.
1 – бінарне повідомлення. У http-запиті потрібно кодувати за допомогою функції urlencode.
2 – бінарне повідомлення, представлене у вигляді шістнадцяткового рядка (hex).
Бінарне повідомлення передається разом з UDH заголовком на початку в параметрі mes, в якому перший байт задає довжину заголовка.
Щоб передати бінарне повідомлення без UDH заголовка, вкажіть нульовий байт на початку повідомлення (00 в hex).
Для можливості передачі параметрів pid і dcs необхідно в кінець бінарного повідомлення додати спеціальну комбінацію
"\n~~~ \ n "(переклад рядка, 3 символу тильди і знову переклад рядка) і потім текст "pid: значеніе1, dcs: значеніе2" з точним збереженням
пробіл.
|
---|
push | Ознака WAP-push повідомлення, за допомогою якого можна відправити інтернет-посилання на телефон. 0 (за замовчуванням) – звичайне повідомлення.
1 – wAP-push повідомлення. В параметрі mes необхідно передати посилання і заголовок через переведення рядка.
|
---|
hlr | Ознака HLR-запиту для отримання інформації про номер із бази оператора без відправки реального SMS. 0 (за замовчуванням) – звичайне повідомлення.
1 – HLR-запит. Буде виконано HLR-запит для кожного номера телефону в списку. Параметр mes не використовується.
|
---|
ping | Ознака спеціального SMS, що не відображається в телефоні, для перевірки номерів на доступність в реальному часі за статусом доставки.
0 (за замовчуванням) – звичайне повідомлення. 1 – ping-sms. Буде надіслано ping-SMS на кожен номер телефону у списку.
Параметр mes не використовується.
|
---|
mms | Ознака MMS-повідомлення, за допомогою якого можна передавати текст (txt), зображення різних форматів (jpg, gif, png),
музику (wav, amr, mp3, mid) і відео (mp4, 3gp). Файли передаються в тілі http-запиту.
0 (за замовчуванням) – звичайне повідомлення. 1 – MMS-повідомлення. Буде надіслано MMS на кожен номер телефону у списку.
|
---|
mail | Ознака e-mail повідомлення. Файли, що прикріплюються до повідомлення, передаються методом POST в тілі http-запиту.
0 (за замовчуванням) – звичайне повідомлення. 1 – e-mail повідомлення.
|
---|
soc | Ознака soc-повідомлення, що відправляється користувачам соціальних мереж "Однокласники", "ВКонтакті" або користувачам "Mail.Ru Агент".
0 (за замовчуванням) – звичайне повідомлення. 1 – soc-повідомлення.
|
---|
viber | Ознака viber-повідомлення, що відправляється користувачам месенджера Viber.
0 (за замовчуванням) – звичайне повідомлення. 1 – viber-повідомлення.
|
---|
whatsapp | Ознака whatsapp-повідомлення, що відправляється користувачам месенджера WhatsApp.
0 (за замовчуванням) – звичайне повідомлення. 1 – whatsapp-повідомлення.
|
---|
tg | При вказівці значення даного параметра рівним 1 буде відправлено telegram-повідомлення з кодом підтвердження, переданим в параметрі mes.
|
---|
bot | Ім'я бота (telegram), в який необхідно відправити повідомлення у форматі "@botname_bot".
|
---|
smsreq | При вказівці даного параметра, система не буде відображати текст повідомлення, відправленого користувачеві і виводити попередження про необхідність підтвердження номера телефону, якщо з моменту останнього підтвердження пройшло більше smsreq днів. Діапазон значень від 10 до 999.
|
---|
fileurl | Повний http-адреса файлу для завантаження і передачі в повідомленні. Мінімальний розмір файлу становить 101 байт.
|
---|
call | Ознака голосового повідомлення. При формуванні голосового повідомлення можна передавати як текст, так і прикріплювати файли.
Файли, що додаються до повідомлення, повинні передаватися методом POST у тілі http-запиту.
0 (за замовчуванням) – звичайне повідомлення. 1 – голосове повідомлення.
|
---|
voice | Голос, який використовується для озвучування тексту (тільки для голосових повідомлень).
m – чоловічий голос. m2 – чоловічий голос 2. m3 (за замовчуванням) - чоловічий голос 3. m4 – чоловічий голос 4.
w – жіночий голос. w2 – жіночий голос 2. w3 – жіночий голос 3. w4 – жіночий голос 4.
При відправці повідомлень також можливе зазначення мови озвучування тексту у вигляді: "m, en", "w, fr", "w, de" і т. п.
|
---|
param | Розділений комою список параметрів для голосового повідомлення у форматі "param=w,i,n".
Тут:
- w – час очікування підняття трубки абонентом після початку дзвінка в секундах. Якщо протягом зазначеного часу абонент не підніме трубку,
то дзвінок піде на повтор із помилкою "абонент зайнятий". Робочий діапазон значень параметра від 10 до 35, але можна вказувати інтервал від 0 до 99
(у випадку, якщо значення менше 10, то воно буде приведене до 10, аналогічно для верхньої межі).
- i – інтервал повтору, тобто проміжок часу, після закінчення якого відбудеться повторний дзвінок (в секундах). Робочий діапазон параметра
від 10 до 3600 (у випадку, якщо значення менше 10, то воно буде приведене до 10).
- n – загальна кількість спроб дозвону. Робочий діапазон значень від 1 до 9 (0 буде приведений до 1).
При вказівці значення будь-якого параметра, відмінного від можливих, будуть використані значення всіх параметрів за замовчуванням (n = 8, w = 25, i від 3 до 14 секунд по наростаючій), крім повідомлень рекламного характеру.
|
---|
subj | Тема MMS або e-mail повідомлення. При відправці e-mail вказання теми, тексту і адреси відправника обов'язкове. Для MMS обов'язковим
є указання теми або тексту. Якщо не вказати тему MMS, то в її якості буде використане ім'я відправника, передане в запиті або
те, що використовується за замовчуванням.
|
---|
cost | Ознака необхідності отримання вартості розсилки.
0 (за замовчуванням) – звичайна відправка. 1 –
отримати вартість розсилки без реальної відправки.
2 – звичайна відправка, але додати у відповідь вартість виконаної розсилки.
3 – звичайна відправка, але додати у відповідь вартість і новий баланс клієнта.
|
---|
list | Список номерів телефонів і відповідних їм повідомлень, розділених двокрапкою або крапкою з комою і
представлений у вигляді:
phones1:mes1
phones2:mes2
...
Рядки розділяються через символ нового рядка (%0A). В якості phones можна вказати кілька номерів телефонів через
кому. Якщо в повідомленні mes потрібно передати символ нового рядка, то вкажіть його через \n. у разі неможливості коригування тексту мультистрокового повідомлення можливе включення спеціального режиму для передачі такого типу повідомлень. Для цього необхідно додатково передавати в запиті параметр nl, рівний 1.
У разі необхідності передачі різних імен відправників (і, можливо, різних часових поясів абонентів (працює тільки для запитів, в яких параметр time представлений у вигляді DDMMYYhhmm або DD.MM.YY hh: mm)) для різних повідомлень можна використовувати наступний формат передачі:
sender1,tz1|phones1:mes1
sender2,tz2|phones2:mes2
...
В даному випадку параметр tz є необов'язковим.
Параметр list дозволяє виконувати множинну розсилку з різними повідомленнями на кілька телефонів одним
http-запитом. Повідомленням у запиті присвоюється єдиний ідентифікатор. Весь параметр повинен бути закодований за
допомогою функції urlencode.
|
---|
valid | Термін" життя " SMS-повідомлення. Визначає час, протягом якого оператор буде намагатися доставити
повідомлення абоненту. Діапазон від 1 до 24 годин. Також можливо передавати час у форматі чч: мм в діапазоні від 00:01 до 24:00.
|
---|
tinyurl | Автоматично скорочувати посилання в повідомленнях. Дозволяє замінювати посилання в тексті
повідомлення на короткі для скорочення довжини, а також для відстеження кількості переходів на
цій сторінці.
0 (за замовчуванням) – залишити посилання в тексті повідомлення без змін. 1 – скоротити посилання.
|
---|
maxsms | Максимальна кількість SMS, на які може розбитися довге повідомлення.
Занадто довгі повідомлення будуть обрізатися так, щоб не переповнити кількість SMS, необхідних
для їх передачі. Цим параметром ви можете обмежити максимальну вартість повідомлень,
так як за кожне SMS знімається окрема плата.
|
---|
imgcode | Значення буквено-цифрового коду, введеного з "captcha" при використанні антиспам перевірки.
Даний параметр повинен використовуватися спільно з параметром userip.
|
---|
userip | Значення IP-адреси, для якої буде діяти ліміт на максимальну кількість повідомлень з однієї IP-адреси на добу,
встановлений в налаштування особистого кабінету в пункті "Ліміти та обмеження".
|
---|
err | Ознака необхідності додавання у відповідь сервера списку помилкових номерів.
0 (за замовчуванням) – не додавати список (звичайна відповідь сервера).
1 – у відповідь додається список помилкових номерів телефонів з відповідними статусами, що передається в параметрі errors.
|
---|
op | Ознака необхідності додавання у відповідь сервера інформації по кожному номеру.
0 (за замовчуванням) – не додавати список (звичайна відповідь сервера).
1 – у відповідь додається список всіх номерів телефонів з відповідними статусами, значеннями mcc і mnc, вартістю, і, в разі помилкових номерів, кодами помилок.
|
---|
pp | Здійснює прив'язку Клієнта як реферала до певного ID партнера для поточного запиту.
При передаче данного параметра в виде "pp=<ID партнера>" Клиент с логином login временно становится рефералом партнера
с ID <ID партнера>. Відрахування за партнерською програмою будуть зроблені саме для поточного запиту, постійної прив'язки не відбувається.
Даний параметр дозволяє тимчасово встановлювати Клієнта як реферала зі своїх сервісів і програм, де немає можливості
зареєструвати Клієнта за реферальним посиланням.
|
---|
Параметри, що повертаються:
Значення | Опис
|
---|
id | Ідентифікатор повідомлення, переданий Клієнтом або призначений Сервером автоматично.
|
---|
balance | Новий баланс Клієнта.
|
---|
cost | Вартість розсилки.
|
---|
cnt | Кількість відправлених SMS, що обчислюється як кількість SMS в повідомленні, помножене на кількість одержувачів.
|
---|
error | Код помилки.
|
---|
Код помилки може приймати наступні значення:
Значення | Опис
|
---|
1 | Помилка в параметрах.
|
---|
2 | Невірний логін або пароль. Також виникає при спробі відправки повідомлення з IP-адреси, що не входить в список дозволених Клієнтом (якщо такий список був налаштований Клієнтом раніше).
|
---|
3 | Недостатньо коштів на рахунку Клієнта.
|
---|
4 | IP-адреса тимчасово заблокована через часті помилки у запитах. Докладніше
|
---|
5 | Невірний формат дати.
|
---|
6 | Повідомлення заборонене (за текстом або по імені відправника).
|
---|
7 | Неправильний формат номера телефону.
|
---|
8 | Повідомлення на вказаний номер не може бути доставлене.
|
---|
9 | Відправка більше одного однакового запиту на передачу SMS-повідомлення протягом хвилини.
|
---|
Сервер не приймає більше одного однакового запиту на відправку SMS-повідомлень протягом хвилини для захисту від помилок і зациклень в програмі на стороні клієнта для того, щоб знизити навантаження і не витрачати кошти клієнта, а також не допустити багаторазової відправки повідомлення одному абоненту.
Сервер також блокує надсилання більше 50 повідомлень одному абоненту, які були відправлені з перервою
між повідомленнями менше 2-х хвилин, для захисту від флуду і зайвого списання коштів з рахунку клієнта,
так як багато операторів не пропускають велику кількість повідомлень одному абоненту за короткий проміжок часу.
Отримання вартостіДля отримання вартості SMS можна використовувати метод get_sms_cost або get_sms_cost2.
В get_sms_cost2 є можливість додавати додаткові параметри.
$client = new SoapClient ('https://smsc.ua/sys/soap.php?wsdl'); $ret = $client->get_sms_cost(array('login'=>'alex', 'psw'=>'123', 'phones'=>'79999999999', 'mes'=>'Hello world!'));
Серверу передаються наступні параметри:
Параметр | Значення
|
---|
login | Логін Клієнта.
|
---|
psw | Пароль Клієнта (можна додати або редагувати на даннійсторінці).
|
---|
apikey | Спеціальний API-ключ, який використовується для спрощеної авторизації замість пари "логін + пароль" (можна створити на даний сторінка).
|
---|
phones | Номер телефону.
|
---|
mes | Ідентифікатор повідомлення.
|
---|
query | Рядок додаткових параметрів (тільки в get_sms_cost2),
переданих у форматі: 'параметр1=значення-1&параметр2=значення-2'.
Детальний опис параметрів дивіться в описі методу send_sms.
|
---|
Параметри, що повертаються:
Параметр | Значення
|
---|
cost | Вартість розсилки.
|
---|
cnt | Кількість відправлених SMS, що обчислюється як кількість SMS в повідомленні, помножене на кількість одержувачів.
|
---|
error | Код помилки.
|
---|
Перевірка статусу
Для перевірки статусу доставки SMS використовуються методи get_status і get_status2.
У методі get_status2 є можливість додавання додаткових параметрів.
$client = new SoapClient ('https://smsc.ua/sys/soap.php?wsdl'); $ret = $client->get_status(array('login'=>'alex', 'psw'=>'123', 'phone'=>'79999999999', 'id'=>'999', 'all'=>'0'));
Серверу передаються наступні параметри:
Параметр | Значення
|
---|
login | Логін Клієнта.
|
---|
psw | Пароль Клієнта (можна додати або редагувати на даннійсторінці).
|
---|
apikey | Спеціальний API-ключ, який використовується для спрощеної авторизації замість пари "логін + пароль" (можна створити на даний сторінка).
|
---|
phone | Номер телефону.
|
---|
id | Ідентифікатор повідомлення.
|
---|
all | 0 – (за замовчуванням) отримати статус повідомлення в звичайному форматі.
1 – отримати повну інформацію про відправлене повідомлення.
2 – додати в інформацію про повідомлення дані про оператора і Регіон абонента.
|
---|
query | Рядок додаткових параметрів (тільки в get_status2),
переданих у форматі: 'параметр1=значення-1&параметр2=значення-2'.
|
---|
Параметри, що повертаються:
Параметр | Значення
|
---|
status | Код статусу (список).
|
---|
last_date | Дата останньої зміни статусу. Формат DD.MM.YYYY HH:mm: ss.
|
---|
err | Код помилки, якщо повідомлення не може бути доставлене (список).
|
---|
error | Код помилки, якщо статус не може бути запитаний.
|
---|
all = 1
|
---|
send_date | Дата відправки повідомлення (формат DD.MM.YYYY hh:mm:ss).
|
---|
phone | Номер телефону абонента.
|
---|
cost | Вартість повідомлення.
|
---|
sender_id | Ім'я відправника.
|
---|
status_name | Назва статусу.
|
---|
message | Текст повідомлення.
|
---|
sms_cnt | Кількість частин в SMS-повідомленні (або секунд в голосовому повідомленні).
|
---|
all = 2
|
---|
operator | Назва оператора абонента.
|
---|
region | Регіон реєстрації номера абонента.
|
---|
Код помилки (error) може приймати такі значення:
Значення | Опис
|
---|
1 | Помилка в параметрах.
|
---|
2 | Невірний логін або пароль. Також виникає при спробі відправки повідомлення з IP-адреси, що не входить в список дозволених Клієнтом (якщо такий список був налаштований Клієнтом раніше).
|
---|
3 | Повідомлення не знайдене.
|
---|
4 | IP-адреса тимчасово заблокована.
|
---|
9 | Спроба відправки більше п'яти запитів на отримання статусу одного і того ж повідомлення протягом хвилини.
|
---|
Перевірка стану балансу
Для запиту балансу використовуйте метод get_balance.
$client = new SoapClient ('https://smsc.ua/sys/soap.php?wsdl'); $ret = $client->get_balance(array('login'=>'alex', 'psw'=>'123'));
Серверу передаються наступні параметри:
Параметр | Значення
|
---|
login | Логін Клієнта.
|
---|
psw | Пароль Клієнта (можна додати або редагувати на даннійсторінці).
|
---|
apikey | Спеціальний API-ключ, який використовується для спрощеної авторизації замість пари "логін + пароль" (можна створити на даний сторінка).
|
---|
У відповідь повертається поточний баланс balance і номер помилки error.
Номер помилки може приймати такі значення:
Значення | Опис
|
---|
0 | Помилок немає.
|
---|
1 | Помилка в параметрах.
|
---|
2 | Невірний логін або пароль. Також виникає при спробі відправки повідомлення з IP-адреси, що не входить в список дозволених Клієнтом (якщо такий список був налаштований Клієнтом раніше).
|
---|
4 | IP-адреса тимчасово заблокована.
|
---|
9 | Спроба відправки більше десяти запитів на отримання балансу протягом хвилини.
|
---|
|