Тарифи  Послуги  API  Партнерам  Про сервіс  Контакти 
0 (800) 30 7672
Безкоштовно по Україні
 

Інтеграція з сервісом (API)

API дозволяє розсилати повідомлення через ваші проекти і сервіси по протоколах HTTP, HTTPS, SMTP та SMPP. Готові бібліотеки на різних мовах програмування підключаються до вашому проекту і допомагають відправляти повідомлення з будь-якого місця за допомогою однієї команди.


HTTP/HTTPS SMTP SMPP SOAP OMS SMS-команди Бібліотеки і приклади коду

Протокол 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Пароль Клієнта (можна додати або редагувати на даннійсторінці).
phonesНомер або розділений комами або крапками з комами список номерів мобільних телефонів в міжнародному форматі, на які відправляється повідомлення. Номери можуть передаватися без знака "+". Якщо номер переданий без знака "+", то він може бути виправлений автоматичним форматуванням і приведено до належного міжнародного формату. Таким чином, деякі помилки при введенні номерів телефонів можуть бути виправлені автоматично. Для відключення автоматичного виправлення передайте номер зі знаком "+".
Також можна відправляти повідомлення на групу номерів, вказавши спеціальний код "G<номер группы>". Повідомлення буде відправлено на всі номери, що належать даній групі. E-mail повідомлення передається список e-mail адрес одержувачів.
mesТекст повідомлення, що надсилається. Максимальний розмір – 1000 символів. Повідомлення необхідності буде розбито на кілька SMS, відправлених абоненту та оплачені окремо. Розмір одного SMS – 160 символів у латиниці або 70 символів у кирилиці. При розбивці повідомлення на кілька SMS на кожну частину додається заголовок для об'єднання частин в одне повідомлення на телефоні одержувача, і максимальна довжина стає 67 для кирилиці і 153 для латинських літер. У текст повідомлення можна додавати коментарі призначені для перегляду відправником історії у особистому кабінеті.
idІдентифікатор повідомлення. Призначається Клієнтом. Служить для подальшої ідентифікації повідомлення. Якщо не вказувати, то буде призначений автоматично. Не обов'язково унікальний. Ідентифікатор представляє собою 32-бітове число в діапазоні від до 1 2147483647, або рядок довжиною до 40 символів, що складається з латинських букв, цифр і символів ".-_".
senderІм'я відправника, який відображається в телефоні одержувача. Можна англійські літери, цифри, пробіл і деякі символи. Довжина – 11 символів або 15 цифр. Всі імена реєструються в особистому кабінеті на сторінки.
timeЧас відправлення SMS-повідомлення абоненту.
Формати:
  1. DDMMYYhhmm або DD.MM.YY hh:mm.
  2. h1-h2. Задає діапазон часу в годинах. Якщо поточний час менше h1, то SMS-повідомлення буде відправлено абоненту при настанні часу h1, якщо поточний час потрапляє в проміжок від h1 до h2, повідомлення буде надіслано негайно, в іншому разі надсилання буде виконана на наступний день при досягненні часу h1. Дана функція, наприклад, корисна для того, щоб не допустити отримання SMS-повідомлень абонентами в нічний час.
  3. 0ts, де ts – timestamp, час у секундах, що минув з 1 січня 1970 року.
  4. +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-повідомлення. Буде відправлено sms на кожен номер телефону в списку.
mailОзнака e-mail повідомлення. Файли, що прикріплюються до повідомлення, передаються методом POST в тілі http-запиту.
0 (за замовчуванням) – звичайне повідомлення.
1 – e-mail повідомлення.
socОзнака soc-повідомлення, що відправляється користувачам соціальних мереж "Однокласники", "ВКонтакте" або користувачам "Mail.Ru Агент".
0 (за замовчуванням) – звичайне повідомлення.
1 – soc-повідомлення.
viberОзнака viber-повідомлення, що надсилається користувачам месенджера Viber.
fileurlПовний http-адреса файлу для завантаження та передачі в повідомленні.
callОзнака голосового повідомлення. При формуванні голосового повідомлення можна передавати як текст, так і прикріплювати файли. Файли, що додаються до повідомлення повинні передаватися методом POST в тілі http-запиту.
0 (за замовчуванням) – звичайне повідомлення.
1 – голосове повідомлення.
voiceГолос, який використовується для озвучування тексту (тільки для голосових повідомлень).
m (за замовчуванням) – чоловічий голос.
m2 – чоловічий альтернативний голос.
w – жіночий голос.
w2 – жіночий альтернативний голос.
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 обов'язковим є вказівка теми або тексту. Якщо не вказати тему повідомлення, в її якості буде використано ім'я відправника, передане в запиті або використовуване за замовчуванням.
costОзнака необхідності отримання вартості розсилки.
0 (за замовчуванням) – звичайна відправлення.
1 – отримати вартість розсилки без реальної відправлення.
2 – звичайна відправлення, але додати у відповідь вартість виконаної розсилки.
3 – звичайна відправлення, але додати у відповідь вартість і новий баланс Клієнта.
listСписок номерів телефонів і відповідних їм повідомлень, розділених двокрапкою або крапкою з комою представлений у вигляді:
phones1:mes1
phones2:mes2
...
Рядки розділяються через символ нового рядка (%0A). Як phones можна вказати кілька номерів телефонів через кому. Якщо в повідомленні mes потрібно передати символ нового рядка, то вкажіть його через \n. У разі неможливості коригування тексту мультистрокового повідомлення можливе включення спеціального режиму для передачі такого типу повідомлень. Для цього необхідно додатково передавати в запиті параметр nl, рівний 1.
Параметр 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Недостатньо коштів на рахунку Клієнта.
4IP-адреса тимчасово заблокована через часті помилки у запитах. Докладніше
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Пароль Клієнта (можна додати або редагувати на даннійсторінці).
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Пароль Клієнта (можна додати або редагувати на даннійсторінці).
phoneНомер телефону.
idІдентифікатор повідомлення.
all0 – (за замовчуванням) отримати статус повідомлення у звичайному форматі.
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Текст повідомлення.
all = 2
operatorНазва оператора абонента.
regionРегіон реєстрації номера абонента.

Код помилки (error) може приймати наступні значення:

ЗначенняОпис
1Помилка в параметрах.
2Невірний логін або пароль. Також виникає при спробі відправки повідомлення з IP-адреси, що не входить в список дозволених Клієнтом (якщо такий список був налаштований Клієнтом раніше).
3Повідомлення не знайдено.
4IP-адреса тимчасово заблокований.
9Спроба відправки більше п'яти запитів на отримання статусу одного і того ж повідомлення протягом хвилини.

Перевірка стану балансу

Для запиту балансу використовуйте метод get_balance.

$client = new SoapClient ('https://smsc.ua/sys/soap.php?wsdl');
$ret = $client->get_balance(array('login'=>'alex', 'psw'=>'123'));

Сервера передаються наступні параметри:

ПараметрЗначення
loginЛогін Клієнта.
pswПароль Клієнта (можна додати або редагувати на даннійсторінці).

У відповідь повертається поточний баланс balance і номер помилки error.

Номер помилки може приймати наступні значення:

ЗначенняОпис
0Помилок немає.
1Помилка в параметрах.
2Невірний логін або пароль. Також виникає при спробі відправки повідомлення з IP-адреси, що не входить в список дозволених Клієнтом (якщо такий список був налаштований Клієнтом раніше).
4IP-адреса тимчасово заблокований.
9Спроба відправки більше десяти запитів на отримання балансу протягом хвилини.



© 2003–2021 ТОВ «СМСЦЕНТР»
Код за ЄДРПОУ 38404962
support@smsc.ua
Контакти
Дизайн — Студія Артемія Лебедєва
Інформація про сайт
Яндекс.Метрика