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

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

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

ВІДПРАВКА ПОВІДОМЛЕНЬ

Відправка SMS-повідомлення

Коментарі в SMS-повідомленнях

Відправка на групу номерів

Відправка HLR-запиту

Відправка e-mail повідомлення

Надсилання голосового повідомлення (дзвінок)

Відправка viber-повідомлення

Відправлення повідомлення в Telegram

Відправлення повідомлення в чат-бот Telegram

Використання префіксів при відправці повідомлень

Керування шаблонами повідомлень

Керування шаблонами операторів

Віртуальна відправка (режим тестування)

Повідомлення про події

УПРАВЛІННЯ РОЗСИЛКАМИ

СТАТУСИ ПОВІДОМЛЕНЬ

ПЕРЕВІРКА СТАНУ БАЛАНСУ

УПРАВЛІННЯ КОНТАКТАМИ

УПРАВЛІННЯ КЛІЄНТАМИ

КЕРУВАННЯ ІМЕНАМИ ВІДПРАВНИКІВ (SENDER ID)

ОТРИМАННЯ ДАНИХ

РІЗНЕ

Різне

Підключення виділених номерів для прийому повідомлень

Ви можете через спеціальні команди API отримувати список вільних виділених номерів для прийому SMS-повідомлень і підключати будь-який номер до свого логіну, оплачуючи вартість за залишок днів в поточному місяці. При підключенні виділеного номера ви автоматично погоджуєтесь із правилами використання таких номерів.

Для отримання списку доступних виділених номерів необхідно викликати методом GET або POST наступну адресу: https://smsc.ua/sys/receive_phones.php?get=1&login=<login>&psw=<password>
Для підключення виділеного номера необхідно викликати методом GET або POST адреси: https://smsc.ua/sys/receive_phones.php?buy=1&login=<login>&psw=<password>&phone=<phone>
Для зміни ознаки продовження виділеного номера на наступний місяць необхідно викликати методом GET або POST адресу: https://smsc.ua/sys/receive_phones.php?chg=1&login=<login>&psw=<password>&phone=<phone>&noprolong=<noprolong>
Опис параметрів, що передаються Серверу:

ПараметрЗначення
loginЛогін Клієнта.
pswПароль Клієнта (можна додати або редагувати на даннійсторінці).
apikeyСпеціальний API-ключ, який використовується для спрощеної авторизації замість пари "логін + пароль" (можна створити на даний сторінка).
phoneПідключається номер.
noprolongОзнака продовження виділеного номера на наступний місяць. Даний параметр також можна вказувати при підключенні номера в команді buy.
0 (за замовчуванням) – включити автоматичне продовження номера.
1 – відключити автоматичне продовження номера.

У разі помилки Сервер повертає наступний рядок:
  • ERROR = N (опис)

  • При fmt = 1:
    0,-N

  • При fmt = 2:
    <result>
    <error>опис</error>
    <error_code>N</error_code>
    </result>

  • При fmt = 3:
    {
    "error": "опис",
    "error_code": N
    }
N – номер помилки, може приймати наступні значення:

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

У разі успішного запиту Сервер повертає відповідь у вигляді рядка.

Для отримання списку доступних номерів:
  • при fmt = 0:
    phone = <phone>, type = <type>, cost = <cost>, current_cost = <current_cost>, info = <info>
    ...

  • при fmt = 1:
    <phone>,<type>,<cost>,<current_cost>,<info>
    ...

  • при fmt = 2:
    <list>
    <receive_phone>
    <phone>phone</phone>
    <type>type</type>
    <cost>cost</cost>
    <current_cost>current_cost</current_cost>
    <info>info</info>
    </receive_phone>
    ...
    </list>

  • при fmt = 3:
    [{
    "phone": "<phone>",
    "type": <type>,
    "cost": "<cost>",
    "current_cost": "<current_cost>"
    "info": "<info>"
    },
    ...]

Де:
<phone> – номер телефону.
<type> – тип номера: 1,4 – виділений віртуальний номер, 2 – номер на послузі SIM-хостингу.
<cost> – вартість оренди номера за повний місяць.
<current_cost> – вартість оренди номера за залишок днів до кінця поточного місяця.
<info> – назва оператора і підтримувані типи повідомлень.

Для оренди номера:
  • при fmt = 0: cost = <cost>

  • при fmt = 1: <cost>

  • при fmt = 2:
    <phone>
    <cost>cost</cost>
    </phone>

  • при fmt = 3:
    {
    "cost": "<cost>"
    }

Де:
<cost> – сума, списана з рахунку Клієнта за оренду номера.

Для зміни ознаки продовження номера:
  • при fmt = 0,1: OK

  • при fmt = 2:
    <result>OK</result>

  • при fmt = 3:
    {
    "result": "OK"
    }



Приклади:

Отримання списку вільних номерів для оренди:

https://smsc.ua/sys/receive_phones.php?get=1&login=alex&psw=123
Підключення номера "79999999999":

https://smsc.ua/sys/receive_phones.php?buy=1&login=alex&psw=123&phone=79999999999
Відключення можливості продовження виділеного номера "79999999999" на наступний місяць:

https://smsc.ua/sys/receive_phones.php?chg=1&login=alex&psw=123&phone=79999999999&noprolong=1

Сервер не приймає більше двох однакових запитів протягом хвилини на отримання списку вільних для оренди номерів або підключення номера, або зміна властивостей виділеного номера для зниження навантаження і захисту від помилок і зациклень в програмі на стороні клієнта.

Передача статусів і повідомлень на обробник Клієнта

В особистому кабінеті Клієнта в "Налаштуваннях користувача" є можливість вказати http(s)-адресу (URL) скрипта для обробки статусів доставки повідомлень, вхідних SMS-повідомлень, а також службових повідомлень (при використанні послуги "Підтвердження номеру за допомогою дзвінка") на стороні Клієнта. Зазначений скрипт буде викликатися Сервером після кожного отримання статусу доставки раніше відправленого Клієнтом повідомлення, після отримання вхідного SMS-повідомлення від абонента або дзвінка від абонента (при використанні послуги "Підтвердження номеру за допомогою дзвінка").

В адресі обробника можна вказати параметр charset для вибору кодування переданих параметрів: ?charset=utf-8
?charset=koi8-r
?charset=windows-1251 За замовчуванням використовується кодування windows-1251.

Також в адресі обробника статусів і вхідних повідомлень можна передавати параметр fmt для вказівки формату параметрів, що повертаються. Можливі значення: fmt=2 (для формату xml) і fmt=3 (для формату json). При передачі параметра fmt кодування koi8-r не використовується.

Для захисту даних, що передаються від підміни в адресі обробника, додатково можна вказати будь-який із параметрів md5, sha1, crc32, що визначають алгоритм підрахунку контрольного параметра з хешем рядку:
"id:phone:status:<секретная строка>" − для статусу доставки
"phone:mes:to:<секретная строка>" − для вхідного повідомлення
"phone:ts:<секретная строка>" − для підтвердження номера за допомогою дзвінка у вигляді:
?md5=<секретная строка>
?sha1=<секретная строка>
?crc32=<секретная строка> В якості символів секретного рядка можна використовувати латинські літери, цифри, мінус і підкреслення. Оброблювачу буде передано відповідний параметр, в якому секретний рядок буде замінено на значення хешу переданих даних.

Всі параметри передаються методом POST (для fmt=p1 і fmt=3 параметри передаються в тілі запиту). У разі необхідності передачі параметрів, зазначених в URL обробника методом GET потрібно прописати їх спеціальним чином через символ "!"(наприклад, у URL-адресі " https://mysite.ru/!param1&param2?param3&param4 " параметри param1 і param2 будуть передані методом GET, а param3 і param4 методом POST).

Параметри, що передані для статусу SMS-повідомлення:

ПараметрЗначення
idІдентифікатор повідомлення.
phoneНомер телефону.
statusСтатус повідомлення.
timeЧас зміни статусу (або доставки SMS-повідомлення абоненту).
Формат: DD.MM.YY hh:mm:ss (за часовим поясом, вказаним у настройках).
tsЧас зміни статусу у вигляді штампу в секундах.
errКод помилки, якщо повідомлення не може бути доставлено (список). Передається, якщо не дорівнює нулю.
syserrДодаткова помилка від оператора, наявна не завжди.
cntКількість частин (при відправці SMS-повідомлення) або кількість секунд (при голосовому повідомленні (дзвінку)).
typeТип повідомлення (0 – SMS, 1 – Flash-SMS, 2 – Бінарне SMS, 3 – Wap-push, 4 – HLR-запит, 5 – Ping-SMS, 6 – MMS, 7 – Дзвінок, 10 – Viber, 12 – Соцмережі).
costВартість повідомлення.
flagПрапор у вигляді 2-х байтового числа, що містить різну інформацію про повідомлення. Можливі комбінації значень бітів різних характеристик.

Біти 0-3 (тип повідомлення):
0 (за замовчуванням) – SMS.
1 – Flash-SMS.
2 – Бінарне SMS.
3 – Wap-push.
4 – HLR-запит.
5 – Ping-SMS.
6 – MMS.
7 – Дзвінок.
8 – E-mail.
10 – Viber.
12 – Соцмережі.

Біт 5 – оплата повідомлення з другого балансу.
Біт 8 – ознака шаблонного повідомлення.

Біти 10,9 - тип шаблонного повідомлення:
00 - сервісне.
01 - транзакційне.
10 - авторизаційне.
11 - рекламний.
senderІм'я відправника, що відображається в телефоні одержувача.
dtmfПослідовність символів, що набирається абонентом на цифровій клавіатурі під час прослуховування голосового повідомлення (дзвінка).
cmtКоментарі клієнта, що передаються при відправці повідомлення. У разі виникнення overtime при голосовому повідомленні він буде переданий у коментарі окремим рядком у вигляді "overtime: mm:ss".
md5MD5-хеш строки "id:phone:status:<секретная строка>". Передається, якщо був указаний в якості додаткового параметра в http(s)-адресі обробника.
sha1sha1-хеш строки "id:phone:status:<секретная строка>". Передається, якщо був указаний в якості додаткового параметра в http(s)-адресі обробника.
crc32Контрольная сумма crc32 строки "id:phone:status:<секретная строка>". Передається, якщо був указаний в якості додаткового параметра в http(s)-адресі обробника.
Розширені можливості пошуку для HLR-запитів
imsiУнікальний код IMSI SIM-карти абонента.
mscНомер сервіс-центру оператора, в мережі якого знаходиться абонент.
mccЧисловий код країни абонента.
mncЧисловий код оператора абонента.
cnНазва країни реєстрації абонента.
netНазва оператора реєстрації абонента.
rcnНазва роумінгової країни абонента при знаходженні в чужій мережі.
rnetНазва роумінгового оператора абонента при знаходженні в чужій мережі.

Передані параметри для вхідного SMS-повідомлення:

ПараметрЗначення
idУнікальний ідентифікатор вхідного повідомлення, який призначається сервером автоматично.
sms_idІдентифікатор повідомлення, на яке отримана відповідь. Даний параметр відсутній, якщо повідомлення від абонента було відправлене на виділений вхідний номер або при вказівці абонентом префікса "логін, двокрапка і пробіл".
phoneНомер телефону абонента.
mesТекст SMS-повідомлення.
toВхідний номер телефону, на який було відправлено повідомлення абонентом.
smscSMS-центр оператора, від якого було отримано вхідне повідомлення.
sentЧас відправки повідомлення абонентом у вигляді штампа в секундах.
timeЧас отримання повідомлення Сервером у вигляді штампу в секундах.
md5MD5-хеш строки "phone:mes:to:<секретная строка>". Передається, якщо був указаний в якості додаткового параметра в http(s)-адресі обробника.
sha1sha1-хеш строки "phone:mes:to:<секретная строка>". Передається, якщо був указаний в якості додаткового параметра в http(s)-адресі обробника.
crc32Контрольная сумма crc32 строки "phone:mes:to:<секретная строка>". Передається, якщо був указаний в якості додаткового параметра в http(s)-адресі обробника.

Передані параметри при використанні послуги "Підтвердження номеру за допомогою дзвінка":

ПараметрЗначення
waitcall1 – ознака службового повідомлення для послуги "Підтвердження номеру за допомогою дзвінка".
phoneНомер телефону абонента, з якого надійшов дзвінок.
tsЧас дзвінка.
md5MD5-хеш строки "phone:ts:<секретная строка>". Передається, якщо був указаний в якості додаткового параметра в http(s)-адресі обробника.
sha1sha1-хеш строки "phone:ts:<секретная строка>". Передається, якщо був указаний в якості додаткового параметра в http(s)-адресі обробника.
crc32Контрольная сумма crc32 строки "phone:ts:<секретная строка>". Передається, якщо був указаний в якості додаткового параметра в http(s)-адресі обробника.

Розширені можливості пошуку, що передаються при використанні функції голосового меню в дзвінках:

ПараметрЗначення
calltime Час розмови, після закінчення якого була натиснута клавіша на цифровій клавіатурі телефону абонента або загальний час розмови.
callmenuПослідовність клавіш цифрової клавіатури телефону, натиснуті абонентом під час проходження по голосовому меню.
ringtimeЧас очікування підняття трубки абонентом.

Крім описаних вище стандартних параметрів Сервер також буде передавати методом POST всі параметри, зазначені в http(s)-адресі обробника після знаку "?".

Для розрізення статусу повідомлення, вхідного SMS-повідомлення або службового повідомлення (при використанні послуги "Підтвердження номера за допомогою дзвінка") в одному обробнику можна виконати перевірку на наявність параметра mes (для вхідного повідомлення) та waitcall (для послуги підтвердження номеру): if (isset($_POST["mes"])) {
    // message
}
elseif (isset($_POST["waitcall"])) {
    // confirmation
}
else {
    // status
}

Пересилання статусів на обробник Клієнта здійснюється тільки при відправленні повідомлень по протоколах HTTP/HTTPS, SMTP або SMPP. При відправці повідомлень з особистого кабінету передача статусів на обробник Клієнта не відбувається.

У разі якщо від обробника Клієнта повернеться відповідь з кодом помилки, відмінним від 200 або 404, то Сервер з певною періодичністю буде повторювати запит на обробник (1 запит кожні 4 хвилини, всього 50 спроб).

Підключення антиспам перевірки (captcha) до сайту

Іноді виникає необхідність відправки повідомлень зі свого сайту за запитом користувачів, і в таких випадках для виключення автоматизованих спам-розсилок за допомогою роботів можна легко впровадити антиспам перевірку, використовуючи наш сервіс.

Для цього достатньо на формі для відправки повідомлень розмістити спеціальний код для виведення картинки (captcha) і поля для введення коду:

Код с картинки <img src="https://smsc.ua/sys/imgcode.php?1.1" onclick="src+=1" width="50" height="18" border="1">
<input type="text" size="9" name="code"> і передати його з іншими даними форми у відповідний скрипт відправки повідомлень в якості значення параметра imgcode.

Також із даним параметром необхідно передавати значення IP-адреси користувача, якому відображалась картинка в якості значення параметраuserip.

Приклади:

Приклад скрипта для відправки повідомлень, що використовує код з картинки( captcha), отриманий з форми:

include_once "smsc_api.php";

if ($_POST["sendsms"]) {
    $r = send_sms($_POST["phone"], "Ваш код для регистрации на сайте mysite.com 123321.", 0, 0, 0, 0, false, "imgcode=".$_POST["code"]."&userip=".$_SERVER["REMOTE_ADDR"]);

if ($r[1] > 0)
    echo "<script>alert('Сообщение отправлено на номер ".$_POST["phone"]."')</script>";
elseif ($r[1] == -10)
    echo "<script>alert('Вы ввели неверный код с картинки!')</script>";
}

Підтвердження номеру телефону за допомогою дзвінка

При різного роду операціях, таких як відновлення паролів, авторизація в соціальних мережах Wi-Fi, підтвердження грошових переказів, вхід в особистий кабінет і так далі потрібна відправка аутентифікаційних даних. Використовуючи наш API можливо організувати процедуру підтвердження номеру телефону за допомогою дзвінка самим абонентом.

Для створення запиту на отримання номеру телефону, за яким абонент повинен буде здійснити підтверджуючий дзвінок, необхідно викликати методом GET або POST адреса: https://smsc.ua/sys/wait_call.php?login=<login>&psw=<password>&phone=<phone>
Серверу передаються наступні параметри:

ПараметрЗначення
loginЛогін Клієнта.
pswПароль Клієнта (можна додати або редагувати на даннійсторінці).
apikeyСпеціальний API-ключ, який використовується для спрощеної авторизації замість пари "логін + пароль" (можна створити на даний сторінка).
phoneНомер телефону абонента, з якого буде здійснено підтверджує дзвінок.

У разі помилки Сервер повертає наступний рядок:
  • ERROR = N (опис)

  • При fmt = 1:
    0,-N

  • При fmt = 2:
    <result>
    <error>опис</error>
    <error_code>N</error_code>
    </result>

  • При fmt = 3:
    {
    "error": "опис",
    "error_code": N
    }
N – номер помилки, може приймати наступні значення:

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

У разі успішного запиту Сервер повертає відповідь у вигляді рядка.

  • при fmt = 0: phone = <phone>, all_phones = <all_phones>

  • при fmt = 1 (першим йде номер, на який необхідно зателефонувати абоненту): <all_phones>

  • при fmt = 2:
    <result>
    <phone>phone</phone>
    <all_phones>
    <phone>phone</phone>
    ...
    <phone>phone</phone>
    </all_phones>
    </result>

  • при fmt = 3:
    {
    "phone": "<phone>",
    "all_phones": [
    <phone>",
    ...
    "<phone>"
    ]
    }

Де:
<phone> – номер телефону, на який протягом 15 хвилин повинен здійснити дзвінок абонент для підтвердження свого номера телефону.
<all_phones> – список всіх можливих номерів телефонів, один з яких був призначений системою для дзвінка абонента (в залежності від країни).

Після дзвінка абонента Сервер зафіксує факт дзвінка у вигляді вхідного повідомлення з текстом "[waitcall]" і відправить на обробник Клієнта всю необхідну інформацію про даний дзвінок.

Сервер не приймає понад п'ятдесят однакових запитів на отримання номеру телефону для підтвердження протягом хвилини для зниження навантаження і захисту від помилок і зациклення в програмі на стороні Клієнта.

Дії з відкладеними завданнями

Для зниження навантаження на Сервер при вивантаженні великого пакету відправлених повідомлень в системі був реалізований механізм відкладених завдань. Даний механізм з певною періодичністю виробляє вибірку активних завдань на вивантаження пакетів повідомлень і виконує їх. Це дозволяє не тільки знизити навантаження на Сервер, але і виключити затримки з формуванням і вивантаженням пакетів повідомлень в браузері клієнта.

Для отримання списку відкладених завдань необхідно викликати методом GET або POST адресу: https://smsc.ua/sys/downloads.php?login=<login>&psw=<password>&get_list=1
Для отримання файлу завдання з відправленими повідомленнями необхідно викликати методом GET або POST адресу: https://smsc.ua/sys/downloads.php?login=<login>&psw=<password>&get_file=1&id=<id> або https://smsc.ua/sys/downloads.php?login=<login>&psw=<password>&get_file=1&name=<name>
Серверу передаються наступні параметри:

ПараметрЗначення
loginЛогін Клієнта.
pswПароль Клієнта (можна додати або редагувати на даннійсторінці).
apikeyСпеціальний API-ключ, який використовується для спрощеної авторизації замість пари "логін + пароль" (можна створити на даний сторінка).
cntКількість відкладених завдань, що повертаються Сервером.
after_idДаний параметр вказує Серверу на необхідність повернення у відповіді списку завдань з ідентифікаторами, наступними за after_id.
idЗавантажити файл завдання з ідентифікатором, рівним id.
nameЗавантажити файл завдання з ім'ям name.

У разі помилки Сервер повертає наступний рядок:
  • ERROR = N (опис)

  • При fmt = 1:
    0,-N

  • При fmt = 2:
    <result>
    <error>опис</error>
    <error_code>N</error_code>
    </result>

  • При fmt = 3:
    {
    "error": "опис",
    "error_code": N
    }
N – номер помилки, може приймати наступні значення:

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

У разі успішного запиту Сервер повертає відповідь у вигляді рядка.

При отриманні списку відкладених завдань:
  • при fmt = 0: id = <id>, name = <name>, status = <status>, created = <created>, time = <time>, file = <file>

  • при fmt = 1: <id>,<name>,<status>,<created>,<time>,<file>

  • при fmt = 2:
    <list>
    <task>
    <id>id</id>
    <name>name</name>
    <status>status</status>
    <created>created</created>
    <time>time</time>
    <file>file</file>
    </task>
    ...
    </list>

  • при fmt = 3:
    [{ "id": id,
    "name": "name",
    "status": "status",
    "created": "created",
    "time": "time",
    "file": "file"
    },
    ...]

Де:
<id> – ідентифікатор відкладеного завдання.
<name> – назва завдання.
<status> – статус завдання (0-очікує виконання, 1-виконується, 2-виконано, 3-скасовано, 4-помилка виконання).
<created> – дата створення завдання.
<time> – час запуску завдання.
<file> – назва файлу завдання.

Після присвоєння відкладеному завданням статусу 2 (виконано) з'явиться можливість завантажити файл з пакетом відправлених повідомлень у форматі csv.

Сервер не приймає більше трьох однакових запитів на отримання списку завдань або на скачування файлу протягом хвилини для зниження навантаження і захисту від помилок і зациклень в програмі на стороні клієнта.




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