| HTTP / HTTPS протокол
Адреса резервного серверу: www2.smsc.ua.
Відправка повідомленьВідправка SMS-повідомленняДля відправки SMS необхідно викликати методом GET або POST адресу:
https://smsc.ua/sys/send.php?login=<login>&psw=<password>&phones=<phones>&mes=<message>
Для отримання вартості SMS необхідно викликати методом GET або POST адресу:
https://smsc.ua/sys/send.php?login=<login>&psw=<password>&phones=<phones>&mes=<message>&cost=1
Для відправки SMS з передачею параметрів у форматі json в тілі запиту необхідно викликати методом POST адресу:
https://smsc.ua/rest/send/
Опис параметрів, що передаються Серверу :
Параметр | Значення
|
---|
login | Логін Клієнта.
|
---|
psw | Пароль Клієнта (можна додати або редагувати на даннійсторінці).
|
---|
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 цифр.
Всі імена реєструються в особистому кабінеті на даній сторінці.
|
---|
translit | Ознака того, що повідомлення необхідно перевести у трансліт.
0 (за замовчуванням) – не переводити в трансліт. 1 – перекласти в трансліт у вигляді "translit".
2 – перевести в трансліт у вигляді "mpaHc/Ium".
|
---|
tinyurl | Автоматично скорочувати посилання в повідомленнях. Дозволяє замінювати посилання в тексті
повідомлення на короткі для скорочення довжини, а також для відстеження кількості переходів на
цій сторінці.
0 (за замовчуванням) – залишити посилання в тексті повідомлення без змін. 1 – скоротити посилання.
|
---|
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 або вказано вже минулий час, то повідомлення буде відправлено негайно.
|
---|
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-повідомлення.
|
---|
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, то в її якості буде використане ім'я відправника, передане в запиті або
те, що використовується за замовчуванням.
|
---|
charset | Кодування переданого повідомлення, якщо використовується відмінна від кодування по
замовчування windows-1251. Варіанти: utf-8 і koi8-r.
|
---|
cost | Ознака необхідності отримання вартості розсилки.
0 (за замовчуванням) – звичайна відправка. 1 –
отримати вартість розсилки без реальної відправки.
2 – звичайна відправка, але додати у відповідь вартість виконаної розсилки.
3 – звичайна відправка, але додати у відповідь вартість і новий баланс клієнта.
|
---|
fmt | Формат відповіді сервера про успішну відправку.
0 – (за замовчуванням) у вигляді рядка (OK - 1 SMS, ID - 1234).
1 – повернути відповідь у вигляді чисел: ID і кількість SMS через кому (1234,1), при cost = 2 ще вартість через
кому (1234,1,1.40), при cost = 3 ще новий баланс клієнта (1234,1,1.40,100.50) , при cost = 1 вартість і кількість
SMS через кому (1.40,1).
2 – відповідь у xml форматі.
3 – відповідь у json форматі.
|
---|
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.
|
---|
maxsms | Максимальна кількість SMS, на які може розбитися довге повідомлення.
Занадто довгі повідомлення будуть обрізатися так, щоб не переповнити кількість SMS, необхідних
для їх передачі. Цим параметром ви можете обмежити максимальну вартість повідомлень,
так як за кожне SMS знімається окрема плата.
|
---|
imgcode | Значення буквено-цифрового коду, введеного з "captcha" при використанні антиспам перевірки.
Даний параметр повинен використовуватися спільно з параметром userip.
|
---|
userip | Значення IP-адреси, для якої буде діяти ліміт на максимальну кількість повідомлень з однієї IP-адреси на добу,
встановлений в налаштування особистого кабінету в пункті "Ліміти та обмеження".
|
---|
err | Ознака необхідності додавання у відповідь сервера списку помилкових номерів.
0 (за замовчуванням) – не додавати список (звичайна відповідь сервера).
1 – у відповідь додається список помилкових номерів телефонів із відповідними статусами.
|
---|
op | Ознака необхідності додавання у відповідь сервера інформації по кожному номеру.
0 (за замовчуванням) – не додавати список (звичайна відповідь сервера).
1 – у відповідь додається список всіх номерів телефонів з відповідними статусами, значеннями mcc і mnc, вартістю, і, в разі помилкових номерів, кодами помилок.
|
---|
pp | Здійснює прив'язку Клієнта як реферала до певного ID партнера для поточного запиту.
При передаче данного параметра у вигляді "pp=<ID партнера>" Клиент с логином login временно становится рефералом партнера
с ID <ID партнера>. Відрахування за партнерською програмою будуть зроблені саме для поточного запиту, постійної прив'язки не відбувається.
Даний параметр дозволяє тимчасово встановлювати Клієнта як реферала зі своїх сервісів і програм, де немає можливості
зареєструвати Клієнта за реферальним посиланням.
|
---|
Обов'язковими параметрами є login, psw, phones і mes або login,
psw і list.
Після прийняття та обробки даних Сервер повертає Клієнту підтвердження із зазначенням результату обробки.
Всі параметри, які містять спеціальні символи (плюс, пробіл і т. д.), повинні бути закодовані за допомогою функції urlencode для передачі в HTTP-запиті.
Відправлення повідомлень. Відповідь сервера та коди помилок
Сервер відправляє відповідь у вигляді рядка:
Якщо сталася помилка, то відповідь буде однією із наступних:
При fmt = 0:
- ERROR = N (описание) – для помилок 1,2,4,5,9;
- ERROR = N (опис), ID - <id сообщения> – для помилок 3,6,7,8.
При fmt = 1:
- 0,-N - для помилок 1,2,4,5,9;
- <id сообщения>,-N – для помилок 3,6,7,8.
При fmt = 2:
- Для помилок 1,2,4,5,9:
<result>
<error>опис</error>
<error_code>N</error_code>
</result> |
- Для помилок 3,6,7,8:
<result>
<error>опис</error>
<error_code>N</error_code>
<id>id сообщения</id>
</result> |
При fmt = 3:
- Для помилок 1,2,4,5,9:
{
"error": "опис",
"error_code": N
} |
- Для помилок 3,6,7,8:
{
"error": "опис",
"error_code": N,
"id": <id сообщения>
} |
N – номер помилки, може приймати наступні значення:
Значення | Опис
|
---|
1 | Помилка в параметрах.
|
---|
2 | Невірний логін або пароль. Також виникає при спробі відправки повідомлення з IP-адреси, що не входить в список дозволених Клієнтом (якщо такий список був налаштований Клієнтом раніше).
|
---|
3 | Недостатньо коштів на рахунку клієнта.
|
---|
4 | IP-адреса тимчасово заблокована через часті помилки у запитах. Докладніше
|
---|
5 | Невірний формат дати.
|
---|
6 | Повідомлення заборонено (за текстом або по імені відправника). Також дана помилка виникає при спробі відправки масових
та (або) рекламних повідомлень без укладеного договору.
|
---|
7 | Неправильний формат номера телефону.
|
---|
8 | Повідомлення на вказаний номер не може бути доставлене.
|
---|
9 | Надсилання більше одного однакового запиту на передачу SMS-повідомлення
або більше п'яти однакових запитів на отримання вартості повідомлення протягом хвилини.
Дана помилка виникає також при спробі відправки п'ятнадцяти і більше запитів одночасно з різних підключень під одним логіном (too many concurrent requests).
|
---|
У разі успішної обробки запиту повертається рядок наступного виду:
- при cost = 0 і fmt = 0: OK - <n> SMS, ID - <id>
- при cost = 1 і fmt = 0: <cost> (<n> SMS)
- при cost = 2 і fmt = 0: OK - <n> SMS, ID - <id>, COST - <cost>
- при cost = 3 і fmt = 0: OK - <n> SMS, ID - <id>, COST - <cost>, BALANCE - <balance>
- при cost = 0 і fmt = 1: <id>,<n>
- при cost = 1 і fmt = 1: <cost>,<n>
- при cost = 2 і fmt = 1: <id>,<n>,<cost>
- при cost = 3 і fmt = 1: <id>,<n>,<cost>,<balance>
- при cost = 0 і fmt = 2:
<result>
<id>id</id>
<cnt>n</cnt>
</result> |
- при cost = 1 і fmt = 2:
<result>
<cost>cost</cost>
<cnt>n</cnt>
</result> |
- при cost = 2 і fmt = 2:
<result>
<id>id</id>
<cnt>n</cnt>
<cost>cost</cost>
</result> |
- при cost = 3 і fmt = 2:
<result>
<id>id</id>
<cnt>n</cnt>
<cost>cost</cost>
<balance>balance</balance>
</result> |
- при cost = 0 і fmt = 3:
{
"id": <id>,
"cnt": <n>
} |
- при cost = 1 і fmt = 3:
{
"cost": "<cost>",
"cnt": <n>
} |
- при cost = 2 і fmt = 3:
{
"id": <id>,
"cnt": <n>,
"cost": "<cost>"
} |
- при cost = 3 і fmt = 3:
{
"id": <id>,
"cnt": <n>,
"cost": "<cost>",
"balance": "<balance>"
} |
- при op = 1 і fmt = 0 або 1, інформація додається в кінець звичайного виводу з нового рядка:
<phone>,<mccmnc>,<cost>,<status>,<error>
- при op = 1 та fmt = 2, у відповідь додається масив:
<phones>
<phone mccmnc="mccmnc" cost="cost" status="status" error="error">phone</phone>
...
</phones> |
- при op = 1 та fmt = 3, у відповідь додається масив:
"phones": [{
"phone": "<phone>",
"mccmnc": "<mccmnc>",
"cost": "<cost>",
"status": "<status>",
"error": "<error>"
},
...
] |
Де:
<n> - це кількість відправлених SMS, обчислюється як кількість SMS в повідомленні, помножене на кількість
одержувач.
<id> – ідентифікатор повідомлення, переданий Клієнтом або призначений Сервером автоматично.
<cnt> – кількість частин (при відправці SMS-повідомлення) або кількість секунд (при голосовому повідомленні (дзвінку)).
<balance> – новий баланс Клієнта.
<phone> – номер телефону.
<mccmnc> – числовий код країни абонента плюс числовий код оператора абонента.
<cost> – вартість SMS-повідомлення.
<status> – код статусу SMS-повідомлення.
<error> – код помилки в статусі.
Сервер не приймає більше одного однакового запиту на відправку SMS-повідомлень протягом хвилини для захисту від помилок і зациклень в програмі на стороні клієнта для того, щоб знизити навантаження і не витрачати кошти клієнта, а також не допустити багаторазової відправки повідомлення одному абоненту.
Сервер також блокує надсилання більше 50 повідомлень одному абоненту, які були відправлені з перервою
між повідомленнями менше 60-ти секунд, для захисту від флуду і зайвого списання коштів із рахунку клієнта,
так як багато операторів не пропускають велику кількість повідомлень одному абоненту за короткий проміжок часу.
Приклади надсилання повідомленьПриклади:
Звичайне повідомлення:
https://smsc.ua/sys/send.php?login=alex&psw=123&phones=79999999999&mes=Hello!
https://smsc.ua/sys/send.php?login=alex&psw=123 &list=79999999999:Hello!%0A79999999999:Hello\nworld!
Flash повідомлення в кодуванні "utf-8" від відправника "ivan", переведене в трансліт, яке повинно бути доставлене абоненту 01.01.2012 р в 00:00:
https://smsc.ua/sys/send.php?login=alex&psw=123&phones=79999999999&mes=Hello%20world! &translit=1&time=0101120000&flash=1&sender=ivan &charset=utf-8
Бінарне EMS повідомлення з текстом "Hello, World!", в якому слово "World" виділене курсивом і підкреслене:
https://smsc.ua/sys/send.php?login=alex&psw=123&phones=79999999999 &mes=050A0307056048656C6C6F2C20576F726C6421&bin=2
Бінарне WAP-push повідомлення, що передає посилання на сайт "http://wap.ru/":
https://smsc.ua/sys/send.php?login=alex&psw=123&phones=79999999999 &mes=0605040B8423F0DC0601AE02056A0045C60C037761702E72752F0001037761702E7275000101&bin=2
WAP-push повідомлення в текстовому вигляді, що передає посилання на сайт "http://wap.ru"із заголовком "WAP.RU":
https://smsc.ua/sys/send.php?login=alex&psw=123&phones=79999999999 &mes=http://wap.ru%0AWAP.RU&push=1 Коментарі в SMS-повідомленнях
При відправці SMS-повідомлень можна додавати в кінець тексту будь-який коментар, уточнюючий або доповнюючий SMS-повідомлення для відправника.
Даний текст не буде відправлятися абонентам і впливати на вартість SMS і доступний для перегляду і фільтрації в списку відправлених повідомлень в особистому кабінеті.
Для додавання коментаря необхідно в кінці тексту SMS-повідомлення, призначеного для відправки, вказати спеціальну комбінацію "\n~~~\n"
(переклад рядка, 3 символу тильди і знову переклад рядка), і після цього будь-який текст, який буде вважатися коментарем, не буде відправлений абоненту,
але відобразиться в історії.
Приклади:
Надсилання одного повідомлення:
https://smsc.ua/sys/send.php?login=alex&psw=123&phones=79999999999%2C78888888888&mes=Hello!%0A~~~%0AComment
Надсилання кількох повідомлень через параметр list:
https://smsc.ua/sys/send.php?login=alex&psw=123&list=79999999999:Hello1!\n~~~\nComment1%0A78888888888:Hello2!\n~~~\nComment2 Відправка на групу номерівВ личном кабинете Клиента при создании або редактировании группы можно указать номер групи для розсилок сообщений.
Тогда при отправке сообщения вместо списка телефонов можно будет указывать короткий код у вигляді "G<номер группы>" або "g<номер группы>",
і повідомлення буде відправлено на всі номери телефонів, що належать даній групі.
Приклади:
Відправлення повідомлення на всі номери телефонів, що належать групам з призначеними номерами 777 і 888:
https://smsc.ua/sys/send.php?login=alex&psw=123&phones=G777%2Cg888&mes=Hello! Відправка HLR-запиту
Ви можете перевірити номери телефонів на наявність, надіславши спеціальний запит HLR. В результаті виконання запиту будуть отримані дані про країну і оператора абонента, про роумінговому оператора при знаходженні абонента в чужій мережі, а також про статус абонента (доступний чи ні). Абоненти, власники номерів, що перевіряються, не отримуватимуть ніяких повідомлень про виконані перевірки їх номера.
Виконання HLR-запиту по HTTP-протоколу виконується тим же способом, що і відправка SMS-повідомлення,
при цьому в запиті необхідно передати додатковий параметр hlr=1.
Для відправки HLR-запиту необхідно викликати методом GET або POST адресу:
https://smsc.ua/sys/send.php?login=<login>&psw=<password>&phones=<phones>&hlr=1
Також доступні й інші параметри, що використовуються для відправки звичайних SMS і описані на даній сторінці.
Результат HLR-запиту може бути відправлений на URL для прийому вхідних повідомлень і статусів,
заданий в налаштуваннях в особистому кабінеті, або може зчитуватися за запитом статусу відправленого SMS-повідомлення.
Приклад:
https://smsc.ua/sys/send.php?login=alex&psw=123&phones=79999999999&hlr=1 Надсилання MMS-повідомлення
Для відправки MMS-повідомлення необхідно викликати методом GET або POST адресу:
https://smsc.ua/sys/send.php?login=<login>&psw=<password>&phones=<phones>&mes=<message>&mms=1
Якщо при відправці планується передача будь-яких файлів (тексту, музики, аудіо, відео), то їх необхідно передавати методом POST в тілі
http (s)-запиту до сервера. Також можлива передача в запиті зовнішнього файлу через параметр fileurl, що містить
повну http (s)-адресу файлу або додавання до тексту повідомлення https-посилання раніше завантаженого файлу, дізнатися яку можна в особистому кабінеті
на сторінці відправки, натиснувши послідовно "прикріпити файл" - "Завантажені файли".
Максимальна кількість вкладень, переданих в запиті, дорівнює двадцяти, і сумарний розмір усіх вкладень не повинен
перевищувати 300 КБ. При перевищенні зазначених лімітів залишившиєся вкладення будуть передані у вигляді посилань. Для MMS-повідомлення вказівку теми або тексту
є обов'язковим.
Приклади:
Відправка MMS-повідомлення з темою "Privet" і текстом "Hello":
https://smsc.ua/sys/send.php?login=alex&psw=123&phones=79999999999&mes=Hello&subj=Privet&mms=1
Відправка MMS з темою "Holiday" і двома фотографіями через бібліотеку на основі cURL:
<?php include "smsc_api.php"; send_sms("79999999999", "", 0, 0, 0, 7, false, "subj=Holiday", array("/home/alex/1.jpg", "/home/alex/2.jpg")); ?>
Відправка e-mail повідомлення
Для відправки e-mail необхідно викликати методом GET або POST адресу:
https://smsc.ua/sys/send.php?login=<login>&psw=<password>&phones=<phones>&mes=<message>&sender=<sender>&subj=<subj>&mail=1
Якщо при відправці планується передача будь-яких файлів, то їх необхідно передавати методом POST в тілі http (s)-запиту до сервера. Позиції в тексті,
в які планується вставляти файли, необхідно позначати спеціальним чином у вигляді "<file n>", де n-номер файлу у формованому списку
починаючи з одиниці. Якщо не вказувати позиції, то відповідні файли будуть додаватися в кінець повідомлення.
При создании сообщения можно вставлять в текст http(s)-ссылки ранее загруженных файлов, узнать которые можно в личном кабинете на странице
отправки, нажав последовательно ссылки "прикрепить файл" – "Загруженные файлы". Также можно указывать локальные ссылки на загруженные файлы
на нашем сервере у вигляді "<file /upload/files/sms/каталог_загрузки/название_файла>". Для вложений-картинок можно устанавливать атрибуты, наприклад,
"<file /upload/files/sms/каталог_загрузки/название_файла width=200 height=400>". Для завантаження файлу з зовнішнього джерела можна в запиті передавати
додатковий параметр fileurl, що містить повну http (s)-адресу файлу.
Максимальна кількість вкладень, що передаються в запиті, дорівнює 20, і розмір кожного вкладення не повинен перевищувати 10 Мб.
При перевищенні зазначених лімітів буде повертатися помилка з кодом 1 (невірні параметри).
При відправці кожного листа максимальний загальний розмір вкладень, що прикріплюються, становить 15 Мб, вкладення,
не вміщаються в цей розмір, будуть передаватися посиланням на наш сайт.
За замовчуванням, в кінець тексту листа додається спеціальне посилання для відписки. Для відключення даного посилання необхідно додати в будь-яке місце тексту листа
спеціальний макрос {no_unsub}.
Для e-mail повідомлень вказівка теми, тексту і адреси відправника обов'язково.
Приклади відправки e-mail повідомленьПриклади:
Відправка e-mail на адресу " alex@mysite.com "з темою" Privet "і текстом" Hello "від відправника" alex2@mysite2.com":
https://smsc.ua/sys/send.php?login=alex&psw=123&phones=alex%40mysite.com&mes=Hello&subj=Privet&sender=alex2%40mysite2.com&mail=1
Відправка e-mail з темою "Holiday" і двома фотографіями через бібліотеки на основі cURL:
<?php include "smsc_api.php"; send_sms("alex@mysite.com", "Hello", 0, 0, 0, 8, "alex2@mysite2.com", "subj=Holiday", array("/home/alex/1.jpg", "/home/alex/2.jpg")); ?>
Відправка e-mail з темою "Hello" і фотографією, завантаженою раніше на сервер:
<?php include "smsc_api.php"; send_sms("alex@mysite.com", "Hello, this is my photo <file /upload/files/sms/123abc/photo.jpg width=200 height=400>", 0, 0, 0, 8, "alex2@mysite2.com", "subj=Hello"); ?>
Надсилання голосового повідомлення (дзвінок)Для відправки голосового повідомлення необхідно викликати методом GET або POST адресу:
https://smsc.ua/sys/send.php?login=<login>&psw=<password>&phones=<phones>&mes=<message>&call=1
При формуванні повідомлення можна вказувати як текст, так і додавати медіа-файли форматів wav і mp3.
Якщо планується передача файлів, то їх необхідно передавати методом POST в тілі http (s)-запиту до сервера. Позиції в тексті, в які
планується вставляти файли, необхідно позначати спеціальним чином у вигляді "<file n>", де n-номер файлу у формованому списку
починаючи з одиниці. Якщо не вказувати позиції, то відповідні файли будуть додаватися в кінець повідомлення.
При создании сообщения можно вставлять в текст http(s)-ссылки ранее загруженных файлов, узнать которые можно в личном кабинете на странице
отправки, нажав последовательно ссылки "прикрепить файл" – "Загруженные файлы". Также можно указывать локальные ссылки на загруженные файлы
на нашем сервере у вигляді "<file /upload/files/sms/каталог_загрузки/название_файла>". Для завантаження файлу з зовнішнього джерела можна в запиті передавати
додатковий параметр fileurl, що містить повний http (s)-адреса файлу. У цьому випадку передача в запиті параметра mes необов'язкова.
Так як телефонні лінії не можуть ідеально програвати складні медіа-файли, то при формуванні відправляється повідомлення передаються
файли перетворюються на простий формат.
При відправці голосового повідомлення початковий час і вартість розраховуються приблизно. Після відправки і прослуховування повідомлення абонентом тривалість і вартість дзвінка коригуються або в меншу сторону (наприклад, якщо абонент не дослухав повідомлення до кінця), або, якщо тривалість повідомлення перевищує розраховану, то різниця в секундах вказується в коментарі до повідомлення у вигляді додаткового часу overtime, яке в тому числі відображається в деталізації у вигляді окремого запису. Також overtime може виникати при використанні голосового меню (IVR).
Максимальна кількість вкладень, що передаються в запиті, дорівнює чотирьом, і розмір кожного вкладення не повинен перевищувати 5 Мб. При перевищенні
зазначених лімітів оброблювані вкладення будуть виключатися.
Для передачі свого номера телефону в якості імені відправника необхідно вказати його в параметрі sender. Вказаний номер раніше
повинен бути доданий і активований в особистому кабінеті на даний сторінка.
При формуванні запиту можна передавати спеціальний параметр param, в якому задаються деякі характеристики дзвінка
(більш детально можна ознайомитися в опис). Також додатково в запиті можна передати параметр voice,
який визначає голос, який використовується для озвучування тексту. Даний параметр може приймати наступні значення:
- voice = m – чоловічий голос.
- voice = m2 – чоловічий голос 2.
- voice = m3 – чоловічий голос 3 (за замовчуванням).
- voice = m4 – чоловічий голос 4.
- voice = w – жіночий голос.
- voice = w2 – жіночий голос 2.
- voice = w3 – жіночий голос 3.
- voice = w4 – жіночий голос 4.
При відправці повідомлень також можливе зазначення мови озвучування тексту у вигляді: "m, en", "w, fr", "w, de" і т. п.
Використання голосового меню (IVR)Для використання голосового меню необхідно на початку тексту повідомлення передати текст або голосовий файл з початковими інструкціями для абонента і далі вказати макрос, що містить службові команди меню {menu: <...>}, де <...> опис параметрів голосового меню.
Схематично повідомлення з використанням голосового меню, виглядає наступним чином:
СТАРТОВЫЙ ТЕКСТ
{menu: [ТЕКСТ МЕНЮ] 1: ТЕКСТ или КОМАНДА 2: ТЕКСТ2 или КОМАНДА2 ... }
КОНЕЧНЫЙ ТЕКСТ
Після підняття трубки абоненту озвучується "СТАРТОВИЙ ТЕКСТ", далі програється "ТЕКСТ МЕНЮ" з описом пунктів меню і допустимими діями. Після натискання клавіші на цифровій клавіатурі телефону, що відповідає необхідному пункту, абоненту може бути озвучений текст "ТЕКСТ" або виконана одна або декілька наступних одина за одною "КОМАНД". Після виходу з меню озвучується "КІНЦЕВИЙ ТЕКСТ".
Опис параметрів, використовуваних в макросі {menu: <...>}:
Параметр | Значення
|
---|
*: back | Для повернення до попереднього меню.
|
---|
#: start | Повернення в початок меню і повтор "ТЕКСТУ МЕНЮ".
|
---|
0: repeat | Повтор вибраного пункту.
|
---|
n: msg | Пункт меню, в який потрапляє абонент при натисканні на клавішу n, де n – номер пункту меню, який може набувати значень від 1 до 9, msg – повідомлення або команда. Пункти меню можна дублювати один за одним для виконання декількох дій при натисканні на одну клавішу.
|
---|
nm: msg | Підпункт m пункту n меню, в який потрапляє абонент при натисканні на клавішу m. Може приймати значення від 1 до 9. msg – повідомлення або команда. Підпункти меню можна дублювати один за одним для виконання декількох дій при натисканні на одну клавішу. Вкладеність підпунктів обмежена тільки розміром всього повідомлення (1000 символів).
|
---|
У пунктах і підпунктах можна використовувати наступні команди:
Команда | Значення
|
---|
url | Адреса http(s)-обробника Клієнта, на який буде передана інформація про поточний пункті і часу знаходження абонента в меню.
|
---|
call:phone wait=n ok:end err:n record | Перенаправлення дзвінка абонента на вказаний номер телефону, де обов'язковим параметром є phone – номер телефону або список номерів телефонів через кому. Можна вказати до 9 номерів. Номери, на які буде відбуватися перенаправлення дзвінка абонента необхідно зареєструвати на даній сторінці.
Необов'язковими параметрами є:
– wait=n – час очікування підняття трубки абонентом, якому був перенаправлений дзвінок, де n – час очікування в секундах. Діапазон можливих значень параметра від 0 до 120. За замовчуванням час очікування підняття трубки абонентом 120 секунд.
– ok:end – після успішного з'єднання із зазначеним номером та закінчення діалогу завершити голосове меню.
– err:n – якщо додзвонитись до вказаного номера не вдалось, то перейти на крок чи мітку n, що описана в тілі меню. Мітка може приймати значення будь-якого набору латинських літер та цифр.
– record – після успішного з'єднання з вказаним номером здійснити запис розмови. Час запису для одного дзвінка обмежений максимум 30 хвилинами. Також з'єднання і запис переривається через 30 секунд тиші з боку абонентів. Даний параметр вказується останнім. Посилання на запис відображається в історії повідомлень під текстом голосового меню.
|
---|
sms:phone,sender,msg | Відправка SMS-повідомлення на вказаний номер телефону, де phone - номер телефону, sender - ім'я відправника, msg - текст повідомлення. В якості номера телефону, а також в тексті повідомлення може бути вказана спеціальна змінна $phone, яка при відправці буде замінена на номер телефону абонента, який отримав дане голосове меню.
|
---|
record: n | Запис фрагмента голосової відповіді абонента, яка буде проведена з моменту активації до закінчення дії команди, де n - час для запису в секундах. За замовчуванням (без явного вказівки часу) запис обмежена 30 секундами. Також запис переривається після 10 секунд тиші з боку абонента.
|
---|
end | Ознака виходу з голосового меню. Після виходу буде прочитаний "КІНЦЕВИЙ ТЕКСТ".
|
---|
Приклади:
<?php $url = 'https://smsc.ua/sys/send.php?login=alex&psw=123&phones=79999999999,79999999998&call=1&charset=utf-8&mes=';
$msg = 'Здравствуйте!
{menu: Нажмите 1 для первого пункта, 2 для второго пункта, 3 для отправки заявки на обратный звонок, 5 для связи с оператором, решетка для перехода в начало, 0 для повтора, для возврата в предыдущее меню нажмите звёздочку. *: back #: start 0: repeat 1: пункт 1, нажмите 1 для подпункта 1, 2 для подпункта 2, 3 для подпункта 3 11: подпункт 1.1 12: подпункт 1.2 13: подпункт 1.3 2: пункт 2, нажмите 1 для подпункта 2.1 21: подпункт 2.1 3: sms:79999999999,Sender,текст 3: end 4: sms:$phone,Sender,Ваш номер: $phone 4: end 5: url 5: call:79999999999,79999999998 wait=10 ok:end err:6 6: call:79999999997 wait=60 ok:end err:callerr record 7: Сейчас начнется запись до 10 секунд 7: record: 10 7: Конец записи err: неверный номер, нажмите 0 для повтора callerr: Извините, не удалось дозвониться до оператора, выберите другой пункт или повторите попытку позже}
Всего вам доброго!';
echo file_get_contents($url.urlencode($msg)); ?>
Приклади відправки голосових повідомленьПриклади:
Надсилання голосового повідомлення з текстом "Hello":
https://smsc.ua/sys/send.php?login=alex&psw=123&phones=79999999999&mes=Hello&call=1
Відправка голосового повідомлення з текстом "Hello" від номера телефону "79991234567":
https://smsc.ua/sys/send.php?login=alex&psw=123&phones=79999999999&mes=Hello&call=1&sender=79991234567
Відправка голосового повідомлення з текстом "Hello world", озвученим чоловічим голосом, із часом очікування зняття трубки 20 секунд,
інтервалом повтору 10 секунд і кількістю спроб дозвону рівному 3:
https://smsc.ua/sys/send.php?login=alex&psw=123&phones=79999999999&mes=Hello%20world&call=1&voice=m¶m=20%2C10%2C3
Надсилання голосового повідомлення з текстом "Hello world", озвученим жіночим альтернативним голосом:
https://smsc.ua/sys/send.php?login=alex&psw=123&phones=79999999999&mes=Hello%20world&call=1&voice=w2
Відправка голосового повідомлення з прикріпленим через параметр fileurl голосовим файлом:
https://smsc.ua/sys/send.php?login=alex&psw=123&phones=79999999999&call=1&fileurl=http://mysite.com/voice.wav
Надсилання голосового повідомлення з текстом і двома звуковими файлами через бібліотеку на основі cURL:
<?php include "smsc_api.php"; send_sms("79999999999", "first file <file 1> and second file <file 2>", 0, 0, 0, 9, false, "", array("/home/alex/1.mp3", "/home/alex/2.wav")); ?>
Відправка viber-повідомлення
Для відправки viber-повідомлення необхідно викликати методом GET або POST адреси:
https://smsc.ua/sys/send.php?login=<login>&psw=<password>&phones=<phones>&mes=<message>&viber=1 Передача файлівПередача в повідомленні картинки, файлу документа або відео можлива одним з наступних способів:
- у вигляді полного http(s)-адреса внешнего файла, указанного в тексте сообщения, в формате <file http(s)://...> (тільки для картинок і файлів документів);
- методом POST в тілі http (s)-запиту до сервера. При даному способі відправки прикріплюються файли необхідно позначити в тексті повідомлення спеціальним чином у вигляді "<file n>", де n-номер файлу у формованому списку починаючи з одиниці;
- додаванням в http(S) - запит спеціального додаткового параметра fileurl, що містить повний http (s)-адреса переданого зовнішнього файлу. При використанні fileurl передача в запиті параметра mes необов'язкова;
- при відправці з Особистого кабінету або через API вставкою в текст повідомлення повної http (s)-посилання раніше завантаженого файлу, дізнатися яку можна в особистому кабінеті на сторінці відправки, натиснувши послідовно "прикріпити файл" – "завантажені файли".
Прикріплюється файл за розміром не повинен перевищувати 1 Мб (для API) або 10 Мб (для особистого кабінету) і задовольняти одному з наступних форматів:
- jpg, jpeg, gif, png – для картинок;
- doc, docx, rtf, dotx, dot, odf, fodt, odt, txt, info, pdf, xps, eps, pdax, xlsx, xlsm, fods, ods, csv, xltx – для файлів документів;
- 3gp, m4v, mov, mp4 – для відео.
Додавання кнопкиДля вставки в повідомлення кнопки, при натисканні на яку буде відбуватися відкриття браузера і перехід на вказану адресу, необхідно додати в текст повідомлення спеціальний макрос {button,url,text}, де:
<button> – назва макросу.
<url> – повна http-адреса посилання, по якій відбудеться перехід при натисканні кнопки.
<text> – текст кнопки. Довжина тексту не може перевищувати 30 символів.
Для вставки в повідомлення кнопки, при натисканні на яку буде відбуватися виклик абонента за вказаним номером телефону, необхідно додати в текст повідомлення спеціальний макрос {button,tel:79999999999,text}.Типи повідомленьСистемою підтримуються наступні типи viber-повідомлень:
- Тільки текст - абонент отримує текстове повідомлення.
- Тільки картинка - абонент отримує картинку.
- Текст + кнопка - абонент отримує текстове повідомлення, під яким розташована кнопка. При натисканні на кнопку відбувається перехід за заданим посиланням.
- Текст + кнопка + картинка - абонент отримує текстове повідомлення, під яким розташовані картинка і кнопка. При натисканні на кнопку відбувається перехід за заданим посиланням.
- Тільки файл - абоненту передається файл одного з підтримуваних форматів.
- Зображення + відео - абонент отримує відео-файл, заставкою до якого є передана картинка.
- Текст + картинка + відео - абонент отримує відео-файл з картинкою-заставкою і зазначеним текстом.
- Текст + картинка + відео + кнопка - абонент отримує відео-файл з картинкою-заставкою, зазначеним текстом і кнопкою. При натисканні на кнопку відбувається перехід за заданим посиланням.
Для налаштування програмного забезпечення і тестування відправки viber-повідомлень можна використовувати наше загальне ім'я відправника"SMSC"
і заздалегідь визначені шаблони:
- Hello! This is test message
- Вітаємо! Це тестове повідомлення
- Test
- Тест
- Test {button,https://smsc.ua,site}
- Тест {button,https://smsc.ua,сайт}
- Picture <file http://smsc.ua/im/smsc_logo_tiny.gif>
- Картинка <file http://smsc.ua/im/smsc_logo_tiny.gif>
Як і в шаблонах для операторів тут діють загальні правила створення повідомлень для зазначених шаблонів (внизу сторінки розкривається вкладка "Правила реєстрації шаблонів").Приклади відправки viber-повідомленьПриклади:
Відправка viber-повідомлення з текстом "Hello":
https://smsc.ua/sys/send.php?login=alex&psw=123&phones=79999999999&mes=Hello&viber=1
Відправка viber-повідомлення по одному з визначених шаблонів для тестування з текстом "Test", кнопкою "{button,http://smscentre.com,Site}" і картинкою, раніше завантажену в особистий кабінет, що має адресу "http://smscentre.com/upload/files/sms/1856f97d/6_1.jpg":
https://smsc.ua/sys/send.php?login=alex&psw=123&phones=79999999999&viber=1&mes=Test+%7Bbutton%2Chttp%3A%2F%2Fsmscentre.com%2CSite%7D+http%3A%2F%2Fsmscentre.com%2Fupload%2Ffiles%2Fsms%2F1856f97d%2F6_1.jpg
Відправка viber-повідомлення за одним із визначених шаблонів для тестування з текстом "test", кнопкою "{button,http://smscentre.com,Site}" і картинкою, розташованою на зовнішньому ресурсі "https://mysite.com/sms/picture.jpg":
https://smsc.ua/sys/send.php?login=alex&psw=123&phones=79999999999&viber=1&mes=test+%7Bbutton%2Chttp%3A%2F%2Fsmscentre.com%2CSite%7D+%3Cfile+https%3A%2F%2Fmysite.com%2Fsms%2Fpicture.jpg%3E
Відправка viber-повідомлення за одним із визначених шаблонів для тестування із текстом "test", кнопкою "{button,http://smscentre.com,Site}" і картинкою "https://mysite.com/sms/picture.jpg", що передана через параметр fileurl:
https://smsc.ua/sys/send.php?login=alex&psw=123&phones=79999999999&viber=1&mes=test+%7Bbutton%2Chttp%3A%2F%2Fsmscentre.com%2CSite%7D&fileurl=https%3A%2F%2Fmysite.com%2Fsms%2Fpicture.jpg
Відправка viber-повідомлення з текстом "відео і кнопка", кнопкою " {button, http://smscentre.com, Кнопка smsc}", картинкою " http://smscentre.com/upload/files/sms/123456/1.png "і відео"http://smscentre.com/upload/files/sms/123456/1.mp4":
https://smsc.ua/sys/send.php?login=alex&psw=123&phones=79999999999&viber=1&mes=%C2%E8%E4%E5%EE+%E8+%EA%ED%EE%EF%EA%E0+http%3A%2F%2Fsmscentre.com%2Fupload%2Ffiles%2Fsms%2F123456%2F1.png%0Ahttp%3A%2F%2Fsmscentre.com%2Fupload%2Ffiles%2Fsms%2F123456%2F1.mp4%0A%7Bbutton%2Chttp%3A%2F%2Fsmscentre.com%2C%CA%ED%EE%EF%EA%E0+smsc%7D Відправка telegram-повідомлення
Для відправки telegram-повідомлення необхідно викликати методом GET або POST адресу:
https://smsc.ua/sys/send.php?login=<login>&psw=<password>&phones=<phones>&mes=<message>&bot=<@botname_bot> Приклади відправки telegram-повідомленьПриклади:
Відправка telegram-повідомлення з текстом " Hello "на номер" 79999999999 "в telegram-бот"@mybot_bot":
https://smsc.ua/sys/send.php?login=alex&psw=123&phones=79999999999&mes=Hello&bot=@mybot_bot
Відправка telegram-повідомлення з текстом " Здрастуйте "по ніку" alex_nick "в telegram-бот"@mybot_bot":
https://smsc.ua/sys/send.php?login=alex&psw=123&phones=@alex_nick&mes = Привіт&bot=@mybot_bot
Відправка telegram-повідомлення з текстом " Hi " по ID 1122334455 в telegram-бот "@mybot_bot":
https://smsc.ua/sys/send.php?login=alex&psw=123&phones=#1122334455&mes=Hi&bot=@mybot_bot
Відправка telegram-повідомлення з текстом "Привіт" на номер " 79999999999 " в telegram-бот "@mybot_bot " із зазначенням в параметрі smsreq кількості днів,
після закінчення якого буде необхідно підтвердити номер телефону SMS-кодом:
р1привіт&bot = @mybot_bot & smsreq=25
Використання префіксів при відправці повідомленьДля відправки різних типів повідомлень можна скористатися можливістю вказівки спеціальних префіксів на початку або замість тексту повідомлення.
Підтримувані префікси:
Назва | Опис
|
---|
__CALL__: повідомлення | Відправка голосового повідомлення (дзвінка). При відправці голосового повідомлення в кінці тексту можна вказати
спеціальну комбінацію "\n~~~\n"(переклад рядка, 3 символу тильди і знову переклад рядка), після якої передати параметр param,
визначальний деякі характеристики дзвінка (більш детально можна подивитися в опис).
При формуванні повідомлення можна вказувати як текст, так і додавати медіа-файли форматів wav і mp3, а також вставляти
раніше завантажені файли. Більш детально по процесу створення голосового повідомлення можна прочитати на даний сторінка.
| __VIBER__: повідомлення | Відправка повідомлення користувачам месенджера Viber.
| __SOC__: повідомлення | Відправка повідомлення користувачам соціальних мереж "Однокласники", "ВКонтакте" або користувачам "Mail.Ru Агент".
| __MAIL__: повідомлення | Відправка e-mail повідомлення.
| __BOT__: повідомлення | Надсилання повідомлення користувачам чат-бота Telegram.
| __PING__ | Відправка спеціального SMS, що не відображається в телефоні, для перевірки номерів на доступність в реальному часі за статусом доставки.
| __HLR__ | Ознака HLR-запиту для отримання інформації про номер з бази оператора без відправки реального SMS. Більш детально
за HLR-запитами можна ознайомитися тут.
|
Приклади:
Надсилання голосового повідомлення з текстом " Privet":
https://smsc.ua/sys/send.php?login=alex&psw=123&phones=79999999999&mes=__CALL__%3A%20Privet
Відправка ping-SMS:
https://smsc.ua/sys/send.php?login=alex&psw=123&phones=79999999999&mes=__PING__
Відправка HLR-запиту:
https://smsc.ua/sys/send.php?login=alex&psw=123&phones=79999999999&mes=__HLR__ Керування шаблонами повідомленьДля управління шаблонами повідомлень необхідно викликати методом GET або POST відповідну адресу із зазначенням необхідної команди
і параметрів.
Для створення шаблону:
https://smsc.ua/sys/templates.php?add=1&login=<login>&psw=<password>&name=<name>&msg=<msg>
Для зміни шаблону:
https://smsc.ua/sys/templates.php?chg=1&login=<login>&psw=<password>&id=<id>
Для видалення шаблону:
https://smsc.ua/sys/templates.php?del=1&login=<login>&psw=<password>&id=<id>
Для отримання списку шаблонів:
https://smsc.ua/sys/templates.php?get=1&login=<login>&psw=<password>
Серверу передаються наступні параметри:
Параметр | Значення
|
---|
login | Логін Клієнта.
|
---|
psw | Пароль Клієнта (можна додати або редагувати на даннійсторінці).
|
---|
name | Назва шаблона.
|
---|
msg | Текст повідомлення.
|
---|
format | Формат повідомлення:
порожній рядок - не заданий.
sms – SMS-повідомлення.
flash – Flash-SMS.
bin – Бінарне SMS.
push – Wap-push.
mms – MMS.
call – Дзвінок.
mail – E-mail.
viber – Viber.
|
---|
sender | Ім'я відправника.
|
---|
fl[1] | Використовувати для автопідпису.
|
---|
У разі помилки Сервер повертає наступний рядок:
- при fmt = 0:
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 | Запис не знайдено.
|
---|
4 | IP-адреса тимчасово заблокована.
|
---|
5 | Помилка збереження або видалення.
|
---|
9 | Спроба відправки більше трьох однакових запитів на дії з шаблонами.
Дана помилка виникає також при спробі відправки п'ятнадцяти і більше запитів одночасно з різних підключень під одним логіном (too many concurrent requests).
|
---|
У разі успішного запиту Сервер повертає відповідь у вигляді рядка:
При створенні шаблону:
- при fmt = 0: ID - <id>
- при fmt = 1: <id>
- при fmt = 2:
<template>
<id>id</id>
</template>
|
- при fmt = 3:
При зміні або видаленні шаблону:
- при fmt = 0, 1: OK
- при fmt = 2:
<result>OK</result>
- при fmt = 3:
При запиті списку шаблонів повідомлень:
- при fmt = 0:
id = <id>, name = <name>, format = <format>, sender = <sender>, flag = <flag>, message = <message>
... |
- при fmt = 1:
<id>,<name>,<format>,<sender>,<flag>,<message>
... |
- при fmt = 2:
<list>
<template>
<id>id</id>
<name>name</name>
<format>format</format>
<sender>sender</sender>
<flag>flag</flag>
<message>message</message>
</template>
...
</list> |
- при fmt = 3:
[{
"id": <id>,
"name": "<name>",
"format": "<format>",
"sender": "<sender>",
"flag": <flag>,
"message": "<message>"
},
...] |
Де:
<id> – ідентифікатор шаблону, призначений системою автоматично.
<name> – назва шаблона.
<format> – формат повідомлення.
<sender> – ім'я відправника.
<flag> – прапор для шаблону. Установка першого біта прапора (fl[1]=1) призначає використання шаблону для автопідпису.
<message> – текст повідомлення.
Сервер не приймає більше трьох однакових запитів на дії з шаблонами протягом хвилини для зниження
навантаження і захисту від помилок і зациклень в програмі на стороні клієнта.
Керування шаблонами операторівДля управління шаблонами сервісних, транзакційних та інших шаблонованих повідомлень необхідно викликати методом GET або POST відповідну адресу із зазначенням необхідної команди
і параметрів.
Для створення шаблону (для всіх операторів):
https://smsc.ua/sys/op_templates.php?add=1&login=<login>&psw=<password>&sender=<sender>&msg=<msg>&mts_srv=1&mts_auth=1&mts_trn=1&mega_srv=1&mega_auth=1&mega_trn=1&mega_adv=1&bee_srv=1&bee_trn=1&tele2_srv=1&tele2_trn=1&motiv_srv=1&motiv_trn=1&soc=1
Для отримання інформації про шаблон (по всіх операторах):
https://smsc.ua/sys/op_templates.php?get=1&login=<login>&psw=<password>&sender=<sender>&msg=<msg>
Серверу передаються наступні параметри:
Параметр | Значення
|
---|
login | Логін Клієнта.
|
---|
psw | Пароль Клієнта (можна додати або редагувати на даннійсторінці).
|
---|
sender | Ім'я відправника для якого створюється шаблон.
|
---|
msg | Текст шаблону.
|
---|
charset | Кодування тексту шаблону, якщо використовується відмінна від кодування за замовчуванням windows-1251. Варіанти: utf-8 і koi8-r.
|
---|
mts_srv | Створити шаблон для оператора МТС (сервісні повідомлення).
|
---|
mts_auth | Створити шаблон для оператора МТС (авторизаційні повідомлення).
|
---|
mts_trn | Створити шаблон для оператора МТС (транзакційні повідомлення).
|
---|
mega_adv | Створити шаблон для оператора Мегафон (рекламні шаблоновані повідомлення).
|
---|
mega_srv | Створити шаблон для оператора Мегафон (Сервісні (інформаційні) повідомлення).
|
---|
mega_auth | Створити шаблон для оператора Мегафон (авторизаційні повідомлення).
|
---|
mega_trn | Створити шаблон для оператора Мегафон (транзакційні повідомлення).
|
---|
bee_srv | Створити шаблон для оператора Білайн (сервісні повідомлення).
|
---|
bee_trn | Створити шаблон для оператора Білайн (транзакційні повідомлення).
|
---|
tele2_srv | Створити шаблон для оператора Теле2 (сервісні повідомлення).
|
---|
tele2_trn | Створити шаблон для оператора Теле2 (транзакційні повідомлення).
|
---|
motiv_srv | Створити шаблон для оператора МОТИВ (сервісні повідомлення).
|
---|
motiv_trn | Створити шаблон для оператора МОТИВ (транзакційні повідомлення).
|
---|
soc | Створити шаблон для soc-повідомлення, що відправляється користувачам соціальних мереж "Однокласники"," ВКонтакті " або користувачам "Mail.Ru Агент".
|
---|
У разі помилки Сервер повертає наступний рядок:
- при fmt = 0:
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-адреси, що не входить в список дозволених Клієнтом (якщо такий список був налаштований Клієнтом раніше).
|
---|
4 | IP-адреса тимчасово заблокована.
|
---|
9 | Спроба відправки більше десяти однакових запитів на дії з шаблонами.
Дана помилка виникає також при спробі відправки п'ятнадцяти і більше запитів одночасно з різних підключень під одним логіном (too many concurrent requests).
|
---|
У разі успішного запиту Сервер повертає відповідь у вигляді рядка:
При створенні шаблону:
- при fmt = 0:
name = <status>, id = <id>
... |
- при fmt = 1:
<name>,<status>,<id>
... |
- при fmt = 2:
<result>
<template>
<name>name</name>
<status>status</status>
<id>id</id>
</template>
...
</result>
|
- при fmt = 3:
[{
"name": <status>,
"id": <id>
},
...] |
При запиті списку шаблонів:
- при fmt = 0:
name = <status>, id = <id>
... |
- при fmt = 1:
<name>,<status>,<id>
... |
- при fmt = 2:
<result>
<template>
<name>name</name>
<status>status</status>
<id>id</id>
</template>
...
</result> |
- при fmt = 3:
[{
"name": <status>,
"id": <id>
},
...] |
Де:
<name> – назва оператора і тип повідомлень.
<id> – ідентифікатор шаблону, призначений системою автоматично.
<status> – статус шаблону, може набувати таких значень:
для команди add:
-2 – неможливо зберегти вказаний шаблон;
-1 – ім'я відправника для даного шаблону, не знайдено або не прийнято оператором;
1 – шаблон успішно доданий;
для команди get:
-1 – шаблон для зазначеного оператора не знайдено;
0 – очікує реєстрації;
1 – відправлено на реєстрацію;
2 – допущено оператором;
3 – не прийнято оператором;
4 – тимчасово вимкнено.
Сервер не приймає більше десяти однакових запитів на дії з шаблонами протягом хвилини для зниження
навантаження і захисту від помилок і зациклення в програмі на стороні Клієнта.
Віртуальна відправка (режим тестування)Даний режим роботи дозволяє протестувати відправку повідомлень без реальної передачі операторам.
Може бути корисний при початковому налаштуванні і тестуванні різного програмного забезпечення і устаткування. Для
включення даного режиму необхідно в особистому кабінеті в пункті "Налаштування"
в спадному блоці
"Налаштування API" встановити галочку "Режим тестування (віртуальна відправка без оплати)".
При віртуальній відправці всі повідомлення будуть мати кінцевий статус "Доставлено", але в процесі відправки повідомлення будуть проходити всі стадії обробки по ланцюжку "Чекає відправки" - "Передано оператору" - "Доставлено". Отримувати статуси повідомлень можна як за запитом, так і на свій http-обробник. Відправляти можна і поодинокі повідомлення і масові розсилки. Тестувати при віртуальній відправці можливо різні типи повідомлень (SMS, бінарні повідомлення, HLR, MMS, дзвінок), крім e-mail.Повідомлення про подіїПри виникненні певних подій може знадобитися відправка споіщень у вигляді повідомлень, що містять інформацію, необхідну для обробки даних подій. Для вирішення подібних завдань можна скористатися розширенням нашої системи моніторингу, яке дозволяє відправляти різні повідомлення через наш сервіс із зовнішніх систем. Для цього в особистому кабінеті на сторінці "Створення групи завдань" потрібно створити відповідну групу, де вказати шаблони сповіщень, типи повідомлень, що відправляються при виникненні події, а також контакти для сповіщень (номери телефонів, e-mail адреси, jabber аккаунти).
Для відправки повідомлення необхідно викликати методом GET або POST адреса:
https://smsc.ua/sys/ping.php?login=<login>&psw=<password>&id=<id>
Серверу передаються наступні параметри:
Параметр | Значення
|
---|
login | Логін Клієнта.
|
---|
psw | Пароль Клієнта (можна додати або редагувати на даннійсторінці).
|
---|
id | Ідентифікатор групи завдань (колонка "ID").
|
---|
name | Назва правила або сервера в завданні. Замінює макрос {NAME} в тексті повідомлення.
|
---|
host | Адреса або IP сервера, що перевіряється. Замінює макрос {HOST}.
|
---|
info | Додаткова інформація про подію. Замінює макрос {INFO}.
|
---|
ok | При формуванні повідомлення використовувати наступний шаблон:
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 | Групу завдань не знайдено.
|
---|
4 | IP-адреса тимчасово заблокована.
|
---|
9 | Спроба відправки більше п'яти однакових запитів на відправку повідомлення протягом хвилини.
Дана помилка виникає також при спробі відправки п'ятнадцяти і більше запитів одночасно з різних підключень під одним логіном (too many concurrent requests).
|
---|
У разі успішного запиту Сервер повертає відповідь у вигляді рядка.
- при fmt = 0 и fmt = 1:
OK
- при fmt = 2:
<result>OK</result>
|
- при fmt = 3:
Сервер не приймає більше п'яти однакових запитів на відправку повідомлення протягом хвилини для зниження
навантаження і захисту від помилок і зациклення в програмі на стороні Клієнта.
Дії з розсилкамиДля створення розсилки необхідно викликати методом GET або POST адресу:
https://smsc.ua/sys/jobs.php?add=1&login=<login>&psw=<password>&name=<name>&phones=<phones>&mes=<message>
Для видалення розсилки необхідно викликати методом GET або POST адресу:
https://smsc.ua/sys/jobs.php?del=1&login=<login>&psw=<password>&id=<id>
Для відключення розсилки, що очікує відправки, необхідно викликати методом GET або POST адресу:
https://smsc.ua/sys/jobs.php?cancel=1&login=<login>&psw=<password>&id=<id>
Для отримання інформації про конкретну розсилку, необхідно викликати методом GET або POST адресу:
https://smsc.ua/sys/jobs.php?get=1&login=<login>&psw=<password>&id=<id>
Для отримання списку розсилок, необхідно викликати методом GET або POST адреса:
https://smsc.ua/sys/jobs.php?get_all=1&login=<login>&psw=<password>
Опис параметрів, що передаються Серверу при створенні розсилки (будь-який з додаткових параметрів застосовується до кожного повідомлення в розсилці; для роботи з e-mail розсилками необхідно в запиті передавати додатковий параметр):
Параметр | Значення
|
---|
login | Логін Клієнта.
|
---|
psw | Пароль Клієнта (можна додати або редагувати на даннійсторінці).
|
---|
name | Назва розсилки.
|
---|
phones | Номер або розділений комою або крапкою з комою список номерів мобільних телефонів в міжнародному форматі,
на які відправляється повідомлення. Номери можуть передаватися без знака "+".
Якщо номер переданий без знака "+", то він може бути виправлений автоматичним форматуванням
і приведений до правильного міжнародного формату. Таким чином, деякі
помилки при введенні номерів телефонів можуть бути виправлені автоматично.
Для відключення автовиправлення передайте номер зі знаком "+".
Також можна відправляти повідомлення на групу номерів, вказавши спеціальний код "G<номер группы>".
Повідомлення буде відправлено на всі номери, що належать цій групі. Для E-mail повідомлення передається список e-mail адрес одержувачів. Для telegram в якості одержувача повідомлення можлива вказівка Ніка абонента або його ID у вигляді #ID.
|
---|
mes | Текст повідомлення, що відправляється. Максимальний розмір – 1000 символів. Повідомлення при
необхідності буде розбите на кілька SMS, відправлених абоненту і оплачених окремо. Розмір одного
SMS – 160 символів у латиниці або 70 символів у кирилиці. При розбивці повідомлення на кілька SMS в кожну частину
додається заголовок для об'єднання частин в одне повідомлення на телефоні одержувача, і максимальна довжина стає
67 для кирилиці і 153 для латинських букв. У текст повідомлення можна додавати коментарі,
призначені для перегляду відправником історії в особистому кабінеті.
|
---|
Додаткові параметри
|
---|
sender | Ім'я відправника, що відображається в телефоні одержувача.
Дозволені англійські букви, цифри, пробіл і деякі символи. Довжина – 11 символів або 15 цифр.
Всі імена реєструються в особистому кабінеті на даній сторінці.
|
---|
sender2 | Даний параметр використовується в якості імені відправника при автоповторі по SMS в разі недоставки повідомлень через первинний варіант відправки.
|
---|
translit | Ознака того, що повідомлення необхідно перевести у трансліт.
0 (за замовчуванням) – не переводити в трансліт. 1 – перекласти в трансліт у вигляді "translit".
2 – перевести в трансліт у вигляді "mpaHc/Ium".
|
---|
tinyurl | Автоматично скорочувати посилання в повідомленнях. Дозволяє замінювати посилання в тексті
повідомлення на короткі для скорочення довжини, а також для відстеження кількості переходів на
цій сторінці.
0 (за замовчуванням) – залишити посилання в тексті повідомлення без змін. 1 – скоротити посилання.
|
---|
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 або вказано вже минулий час, то повідомлення буде відправлено негайно.
|
---|
rpt | Визначає періодичність відправки новостворюваної розсилки. 0 (за замовчуванням) – вручну.
1 – щогодини. 2 – кожен день. 3 – кожен робочий день. 4 – кожні вихідні. 5 – щотижня.
6 – кожен місяць. 7 – кожен рік.
|
---|
rptn | Встановлює максимальну кількість повторів для відкладеної періодичної розсилки.
|
---|
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-повідомлення.
|
---|
bot | Ім'я бота (telegram), в який необхідно відправити повідомлення у форматі "@botname_bot".
|
---|
smsreq | При вказівці даного параметра, система не буде відображати текст повідомлення, відправленого користувачеві і виводити попередження про необхідність підтвердження номера телефону, якщо з моменту останнього підтвердження пройшло більше smsreq днів. Діапазон значень від 10 до 999.
|
---|
fileurl | Повний http-адреса файлу для завантаження і передачі в повідомленні. Мінімальний розмір файлу становить 101 байт.
|
---|
mes2 | Даний параметр задає варіант повідомлення для пересилання по SMS в режимі автоматичного повтору при недоставці на альтернативні маршрути, наприклад, відправка в месенджери. Для включення автоматичного повтору необхідно в запиті додатково передати прапор fl[5], рівний 1.
|
---|
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, то в її якості буде використане ім'я відправника, передане в запиті або
те, що використовується за замовчуванням.
|
---|
charset | Кодування переданого повідомлення, якщо використовується відмінна від кодування по
замовчування windows-1251. Варіанти: utf-8 і koi8-r.
|
---|
cost | Ознака необхідності отримання вартості розсилки.
0 (за замовчуванням) – звичайна відправка. 1 –
додати у відповідь вартість розсилки.
|
---|
fmt | Формат відповіді сервера про успішну відправку.
0 – (за замовчуванням) у вигляді рядка (OK - 1 SMS, ID - 1234).
1 – повернути відповідь у вигляді чисел: ID і кількість SMS через кому (1234,1), при cost = 2 ще вартість через
кому (1234,1,1.40), при cost = 3 ще новий баланс клієнта (1234,1,1.40,100.50) , при cost = 1 вартість і кількість
SMS через кому (1.40,1).
2 – відповідь у xml форматі.
3 – відповідь у json форматі.
|
---|
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.
|
---|
tpl | ID шаблону, який буде використаний в якості тексту повідомлення. Для використання шаблону необхідно,
щоб параметр mes був порожнім.
|
---|
valid | Термін" життя " SMS-повідомлення. Визначає час, протягом якого оператор буде намагатися доставити
повідомлення абоненту. Діапазон від 1 до 24 годин. Також можливо передавати час у форматі чч: мм в діапазоні від 00:01 до 24:00.
|
---|
Обов'язковими параметрами є login, psw, name, phones і mes або login, psw, name і list.
Опис параметрів, що передаються на Сервер при видаленні, відключенні або отриманні списку розсилок:
Параметр | Значення
|
---|
login | Логін Клієнта.
|
---|
psw | Пароль Клієнта (можна додати або редагувати на даннійсторінці).
|
---|
id | Ідентифікатор розсилки. Повертається Сервером після створення і використовується для подальшої ідентифікації розсилки.
|
---|
Додаткові параметри
|
---|
start | Дата, з якої потрібно отримати список розсилок. Якщо цей параметр не вказано, повертає список розсилок за останні 2 місяці, але не більше 10. Застосовується спільно з параметром get_all. Формат: 'дд.мм.рррр'.
|
---|
end | Дата, до якої потрібно отримати список розсилок. Якщо цей параметр не вказано, то повертається список розсилок до поточної дати, але не більше 10. Застосовується спільно з параметром get_all. Формат: 'дд.мм.рррр'.
|
---|
Обов'язковими параметрами є login, psw і id.
Після прийняття та обробки даних Сервер повертає Клієнту підтвердження із зазначенням результату обробки.
Всі параметри, які містять спеціальні символи (плюс, пробіл і т. д.), повинні бути закодовані за допомогою функції urlencode для передачі в HTTP-запиті.
Розсилання. Відповідь сервера та коди помилок
Сервер відправляє відповідь у вигляді рядка:
Якщо сталася помилка, то відповідь буде однією із наступних:
При fmt = 0:
- ERROR = N (описание) – для помилок 1,2,3,4,5,9.
При fmt = 1:
- 0,-N - для помилок 1,2,3,4,5,9.
При fmt = 2:
- Для помилок 1,2,3,4,5,9:
<result>
<error>опис</error>
<error_code>N</error_code>
</result> |
При fmt = 3:
- Для помилок 1,2,3,4,5,9:
{
"error": "опис",
"error_code": N
} |
N – номер помилки, може приймати наступні значення:
Значення | Опис
|
---|
1 | Помилка в параметрах.
|
---|
2 | Невірний логін або пароль. Також виникає при спробі відправки повідомлення з IP-адреси, що не входить в список дозволених Клієнтом (якщо такий список був налаштований Клієнтом раніше).
|
---|
3 | Помилка збереження запису.
|
---|
4 | IP-адреса тимчасово заблокована через часті помилки у запитах. Докладніше
|
---|
5 | Невірний формат дати.
|
---|
9 | Надсилання більше одного однакового запиту на дії з розсилками протягом хвилини.
Дана помилка виникає також при спробі відправки п'ятнадцяти і більше запитів одночасно з різних підключень під одним логіном (too many concurrent requests).
|
---|
У разі успішної обробки запиту повертається рядок наступного виду:
При створенні розсилки:
- при cost = 0 і fmt = 0: OK, ID - <id>
- при cost = 1 і fmt = 0: OK, ID - <id>, COST - <cost>
- при cost = 0 і fmt = 1: <id>
- при cost = 1 і fmt = 1: <id>,<cost>
- при cost = 0 і fmt = 2:
<result>
<id>id</id>
</result> |
- при cost = 1 і fmt = 2:
<result>
<id>id</id>
<cost>cost</cost>
</result> |
- при cost = 0 і fmt = 3:
- при cost = 1 і fmt = 3:
{
"id": <id>,
"cost": "<cost>"
} |
При відключенні або видаленні розсилки:
- при fmt = 0,1: OK
- при fmt = 2:
<result>OK</result> |
- при fmt = 3:
При отриманні інформації про конкретну розсилку (при mail=1 параметр "phones" змінюється на "emails"):
- при fmt = 0: <id>|<name>|<subject>|<repeat_send>|<repeat_cnt>|<created>|<changed>|<need_date>|<last_sent>|<phones>|<message>|<format>|<validity>|<period>|<frequency>|<status>|<sender_id>
- при fmt = 1: <id>;<name>;<subject>;<repeat_send>;<repeat_cnt>;<created>;<changed>;<need_date>;<last_sent>;<phones>;<message>;<format>;<validity>;<period>;<frequency>;<status>;<sender_id>
- при fmt = 2:
<job>
<id>id</id>
<name>name</name>
<subject>subject</subject>
<repeat_send>repeat_send</repeat_send>
<repeat_cnt>repeat_cnt</repeat_cnt>
<created>created</created>
<changed>changed</changed>
<need_date>need_date</need_date>
<last_sent>last_sent</last_sent>
<phones>phones</phones>
<message>message</message>
<format>format</format>
<validity>validity</validity>
<period>period</period>
<frequency>frequency</frequency>
<status>status</status>
<sender_id>sender_id</sender_id>
</job> |
- при fmt = 3:
[ {
"id": <id>,
"name": "<name>",
"subject": "<subject>",
"repeat_send": <repeat_send>,
"repeat_cnt": <repeat_cnt>,
"created": "<created>",
"changed": "<changed>",
"need_date": "<need_date>",
"last_sent": "<last_sent>",
"phones": "<phones>",
"message": "<message>",
"format": <format>,
"validity": <validity>,
"period": "<period>",
"frequency": <frequency>,
"status": <status>,
"cost": "<cost>",
"sms_sent": <sms_sent>,
"sms_ok": <sms_ok>,
"sender_id": "<sender_id>"
} ] |
При отриманні списку розсилок (при mail=1 параметр "phones" змінюється на "emails"):
- при fmt = 0: <id>|<name>|<changed>|<need_date>|<last_sent>|<phones>|<message>|<phones_cnt>|<cost>|<status>|<sender_id>|<format>
- при fmt = 1: <id>;<name>;<changed>;<need_date>;<last_sent>;<phones>;<message>;<phones_cnt>;<cost>;<status>;<sender_id>;<format>
- при fmt = 2:
<sms_jobs>
<job>
<id>id</id>
<name>name</name>
<changed>changed</changed>
<need_date>need_date</need_date>
<last_sent>last_sent</last_sent>
<phones>phones</phones>
<message>message</message>
<phones_cnt>phones_cnt</phones_cnt>
<cost>cost</cost>
<status>status</status>
<sender_id>sender_id</sender_id>
<format>format</format>
</job>
...
</sms_jobs>
|
- при fmt = 3:
[ {
"id": <id>,
"name": "<name>",
"changed": "<changed>",
"need_date": "<need_date>",
"last_sent": "<last_sent>",
"phones": "<phones>",
"message": "<message>",
"phones_cnt": <phones_cnt>,
"cost": "<cost>",
"status": <status>,
"sender_id": "<sender_id>",
"format": <format>,
"sms_sent": <sms_sent>,
"sms_ok": <sms_ok>
}, ... ] |
Де:
<id> – ідентифікатор розсилки, переданий клієнтом або призначений Сервером автоматично.
<name> – назва розсилки.
<subject> – тема (для e-mail розсилок).
<repeat_send> – період повтору.
<repeat_cnt> – кількість повторів розсилки.
<created> – дата створення розсилки.
<changed> – дата зміни розсилки.
<need_date> – призначена дата відправки.
<last_sent> – дата останньої відправки.
<phones> (<emails>) – список телефонів (e-mail адрес) одержувачів повідомлень.
<message> – текст повідомлення.
<format> – формат повідомлення.
<validity> – "час життя" повідомлення.
<period> – інтервал відправки повідомлень.
<frequency> – частота відправки повідомлень.
<status> – статус розсилки.
<sender_id> – ім'я відправника.
<phones_cnt> – кількість одержувачів.
<cost> – вартість розсилки.
<sms_sent> – кількість відправлених повідомлень.
<sms_ok> – кількість доставлених повідомлень.Приклади операцій з розсилкамиПриклади:
Створення SMS-розсилки:
https://smsc.ua/sys/jobs.php?add=1&login=alex&psw=123&phones=79999999999&name=Privet&mes=Hello!
Створення розсилки з голосовим повідомленням:
https://smsc.ua/sys/jobs.php?add=1&login=alex&psw=1234567890&phones=79999999999&call=1&voice=w2&name=Privet&mes=Hello!
Створення розсилки e-mail повідомленням на адресу "alex@mysite.com" з темою "Hi" та текстом "Hello!" від відправника "alex2@mysite2.com"
і назвою розсилки "Privet":
https://smsc.ua/sys/jobs.php?add=1&login=alex&psw=123&phones=alex%40mysite.com&mail=1&name=Privet&mes=Hello!&subj=Hi&sender=alex2%40mysite2.com
Створення Viber-розсилки з макросами та автоповторенням по SMS (текст SMS відрізняється від тексту Viber-повідомлення) на кілька номерів (тексти повідомлень необхідно закодувати за допомогою функції urlencode):
https://smsc.ua/sys/jobs.php?add=1&login=alex&psw=123&phones=79999999999,78888888888&name=rassilka1&mes={Ім'я}, це Viber-повідомлення&mes2=це SMS для {Ім'я}&sender=MyViber & fl[5]=1&viber=1
Видалення створеної розсилки з id рівним 701:
https://smsc.ua/sys/jobs.php?del=1&login=alex&psw=123&id=701
Відключення відкладеної розсилки з id рівним 701:
https://smsc.ua/sys/jobs.php?cancel=1&login=alex&psw=123&id=701 Перевірка статусу
Для перевірки статусу доставки SMS або e-mail необхідно викликати методом GET або POST адресу:
https://smsc.ua/sys/status.php?login=<login>&psw=<password>&phone=<phone>&id=<sms_id>
Серверу передаються наступні параметри:
Параметр | Значення
|
---|
login | Логін Клієнта.
|
---|
psw | Пароль Клієнта (можна додати або редагувати на даннійсторінці).
|
---|
phone | Номер телефону або список номерів через кому при запиті
статусів декількох SMS. При множинному запиті номеру в списку повинні
бути перераховані в порядку, відповідному ідентифікаторам повідомлень. Задля
збереження формату множинного запиту при запиті статусу одного повідомлення
вкажіть кому після номера телефону. Цей опис підходить і для e-mail-повідомлень.
|
---|
id | Ідентифікатор повідомлення або список ідентифікаторів через кому при
запиті статусів декількох повідомлень. Для збереження формату множинного запиту
при запиті статусу одного повідомлення вкажіть кому після ідентифікатора
повідомлення.
|
---|
fmt | Формат відповіді сервера:
0 – (за замовчуванням) у вигляді рядка (Status = 1, check_time = 10.10.2010 10:10:10).
1 – у вигляді номера статусу і штампа часу через кому (1,1286524541).
2 – у xml форматі.
3 – у json форматі.
|
---|
all | 0 – (за замовчуванням) отримати статус повідомлення в звичайному форматі.
1 – отримати повну інформацію про відправлене повідомлення.
2 – додати в інформацію про повідомлення дані про країну, оператора та регіон абонента.
|
---|
charset | Кодування результату запиту, якщо використовується відмінна від кодування
за замовчуванням windows-1251. Варіанти: utf-8 і koi8-r.
|
---|
del | 1 – видаліть раніше надіслане повідомлення. Використовується спільно з параметрами
phone і id. Більш детально цей параметр описаний тут.
|
---|
Статуси повідомлень. Відповідь сервера та коди помилокУ разі помилки Сервер повертає наступний рядок:
- При fmt = 0:
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-адреси, що не входить в список дозволених Клієнтом (якщо такий список був налаштований Клієнтом раніше).
|
---|
4 | IP-адреса тимчасово заблокована.
|
---|
5 | Помилка видалення повідомлення.
|
---|
9 | Спроба відправки більше п'яти запитів на отримання статусу одного і того ж повідомлення або більше одного масового запиту протягом хвилини.
Дана помилка виникає також при спробі відправки п'яти і більше запитів одночасно з різних підключень під одним логіном (too many concurrent requests).
|
---|
У разі успішного запиту Сервер повертає відповідь у вигляді рядка:
Відповіді для SMS-повідомлень:
- при fmt = 0 та all = 0: Status = <status>, check_time = <last_date>, err = <err>
- при fmt = 1 та all = 0: <status>,<last_timestamp>,<err>
- при fmt = 2 та all = 0:
<sms>
<status>status</status>
<last_date>last_date</last_date>
<last_timestamp>last_timestamp</last_timestamp>
<flag>flag</flag>
<err>err</err>
</sms> |
- при fmt = 3 та all = 0:
{
"status": <status>,
"last_date": "<last_date>",
"last_timestamp": <last_timestamp>,
"flag": <flag>,
"err": <err>
} |
- при fmt = 0 та all = 1:
Status = <status>, check_time = <last_date>, err = <err>, send_date = <send_date>, phone = <phone>, cost = <cost>, sender_id = <sender>, status_name = <status_name>, message = <message>, comment = <comment>, type = <type>
|
- при fmt = 1 та all = 1:
<status>,<last_timestamp>,<err>,<send_timestamp>,<phone>,<cost>,<sender>,<status_name>,<message>, <comment>, <type>
- при fmt = 2 та all = 1:
<sms>
<status>status</status>
<last_date>last_date</last_date>
<last_timestamp>last_timestamp</last_timestamp>
<flag>flag</flag>
<err>err</err>
<send_date>send_date</send_date>
<send_timestamp>send_timestamp</send_timestamp>
<phone>phone</phone>
<cost>cost</cost>
<sender_id>sender</sender_id>
<status_name>status_name</status_name>
<message>message</message>
<comment>comment</comment>
<type>type</type>
<sms_cnt>sms_cnt</sms_cnt>
</sms>
|
- при fmt = 3 та all = 1:
{
"status": <status>,
"last_date": "<last_date>",
"last_timestamp": <last_timestamp>,
"flag": <flag>,
"err": <err>,
"send_date": "<send_date>",
"send_timestamp": <send_timestamp>,
"phone": "<phone>",
"cost": "<cost>",
"sender_id": "<sender>",
"status_name": "<status_name>",
"message": "<message>",
"comment": "<comment>",
"type": <type>,
"sms_cnt": <sms_cnt>
} |
- при fmt = 0 та all = 2:
Status = <status>, check_time = <last_date>, err = <err>, send_date = <send_date>, phone = <phone>, mccmnc = <mccmnc>, country = <country>, operator = <operator>, operator_orig= <operator_orig>, region = <region>, cost = <cost>, sender_id = <sender>, status_name = <status_name>, message = <message>, comment = <comment>, type = <type>
|
- при fmt = 1 та all = 2:
<status>,<last_timestamp>,<err>,<send_timestamp>,<phone>,<country>,<operator>,<region>,<cost>,<sender>,<status_name>,<message>, <comment>, <type>
|
- при fmt = 2 та all = 2:
<sms>
<status>status</status>
<last_date>last_date</last_date>
<last_timestamp>last_timestamp</last_timestamp>
<flag>flag</flag>
<err>err</err>
<send_date>send_date</send_date>
<send_timestamp>send_timestamp</send_timestamp>
<phone>phone</phone>
<cost>cost</cost>
<sender_id>sender</sender_id>
<status_name>status_name</status_name>
<message>message</message>
<comment>comment</comment>
<mccmnc>mccmnc</mccmnc>
<country>country</country>
<operator>operator</operator>
<operator_orig>operator_orig</operator_orig>
<region>region</region>
<type>type</type>
<sms_cnt>sms_cnt</sms_cnt>
</sms>
|
- при fmt = 3 та all = 2:
{
"status": <status>,
"last_date": "<last_date>",
"last_timestamp": <last_timestamp>,
"flag": <flag>,
"err": <err>,
"send_date": "<send_date>",
"send_timestamp": <send_timestamp>,
"phone": "<phone>",
"cost": "<cost>",
"sender_id": "<sender>",
"status_name": "<status_name>",
"message": "<message>",
"comment": "<comment>",
"mccmnc": "<mccmnc>",
"country": "<country>",
"operator": "<operator>",
"operator_orig": "<operator_orig>",
"region": "<region>",
"type": <type>,
"sms_cnt": <sms_cnt>
} |
Де:
<status> – код статусу (список)
<last_date> – дата останньої зміни статусу. Формат DD.MM.YYYY HH:mm: ss.
<last_timestamp> – штамп часу останньої зміни статусу.
<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-рекламне).
<err> – код помилки, якщо повідомлення не було доставлене.
<send_date> – дата відправки повідомлення (формат DD.MM.YYYY hh:mm:ss).
<send_timestamp> – штамп часу відправки повідомлення.
<phone> – номер телефону абонента або e-mail адреса.
<country> – назва країни реєстрації номера абонента.
<operator> – поточний стільниковий оператор абонента.
<operator_orig> – оператор абонента за мобільним кодом до портування номера.
<region> – регіон реєстрації номера абонента.
<cost> – вартість повідомлення.
<sender> – ім'я відправника.
<status_name> – назва статусу.
<message> – текст повідомлення.
<comment> – коментар повідомлення.
<mccmnc> – числовий код країни абонента плюс числовий код оператора абонента.
<type> - тип повідомлення (0-SMS, 1-Flash – SMS, 2 – бінарне SMS, 3-Wap – push, 4-HLR – запит, 5-ping – SMS, 6-MMS, 7 –
Дзвінок, 8-E-mail, 10-Viber, 12-соцмережі).
<sms_cnt> – кількість частин в SMS-повідомленні (або секунд в голосовому повідомленні).
Відповіді для HLR-запитів:
- при fmt = 0 та all = 0:
Status = <status>, check_time = <check_time>, err = <err>, imsi = <imsi>, msc = <msc>, mcc = <mcc>, mnc = <mnc>, cn = <cn>, net = <net>, rcn = <rcn>, rnet = <rnet> |
- при fmt = 1 та all = 0: <status>,<last_timestamp>,<err>,<imsi>,<msc>,<mcc>,<mnc>,<cn>,<net>,<rcn>,<rnet>
- при fmt = 2 та all = 0:
<sms>
<status>status</status>
<last_date>last_date</last_date>
<last_timestamp>last_timestamp</last_timestamp>
<flag>flag</flag>
<err>err</err>
<imsi>imsi</imsi>
<msc>msc</msc>
<mcc>mcc</mcc>
<mnc>mnc</mnc>
<cn>cn</cn>
<net>net</net>
<rcn>rcn</rcn>
<rnet>rnet</rnet>
</sms> |
- при fmt = 3 та all = 0:
{
"status": <status>,
"last_date": "<last_date>",
"last_timestamp": <last_timestamp>,
"flag": <flag>,
"err": <err>,
"imsi": "<imsi>",
"msc": "<msc>",
"mcc": "<mcc>",
"mnc": "<mnc>",
"cn": "<cn>",
"net": "<net>",
"rcn": "<rcn>",
"rnet": "<rnet>"
} |
- при fmt = 0 та all = 1:
Status = <status>, check_time = <check_time>, err = <err>, imsi = <imsi>, msc = <msc>, mcc = <mcc>, mnc = <mnc>, cn = <cn>, net = <net>, rcn = <rcn>, rnet = <rnet>, send_date = <send_date>, phone = <phone>, cost = <cost>, sender_id = <sender_id>, status_name = <status_name>, message = <message>, type = <type> |
- при fmt = 1 та all = 1:
<status>,<last_timestamp>,<err>,<imsi>,<msc>,<mcc>,<mnc>,<cn>,<net>,<rcn>,<rnet>,
<send_timestamp>,<phone>,<cost>,<sender_id>,<status_name>,<message>,<type> |
- при fmt = 2 та all = 1:
<sms>
<status>status</status>
<last_date>last_date</last_date>
<last_timestamp>last_timestamp</last_timestamp>
<flag>flag</flag>
<err>err</err>
<imsi>imsi</imsi>
<msc>msc</msc>
<mcc>mcc</mcc>
<mnc>mnc</mnc>
<cn>cn</cn>
<net>net</net>
<rcn>rcn</rcn>
<rnet>rnet</rnet>
<send_date>send_date</send_date>
<send_timestamp>send_timestamp</send_timestamp>
<phone>phone</phone>
<cost>cost</cost>
<sender_id>sender_id</sender_id>
<status_name>status_name</status_name>
<message>message</message>
<type>type</type>
</sms> |
- при fmt = 3 та all = 1:
{
"status": <status>,
"last_date": "<last_date>",
"last_timestamp": <last_timestamp>,
"flag": <flag>,
"err": <err>,
"imsi": "<imsi>",
"msc": "<msc>",
"mcc": "<mcc>",
"mnc": "<mnc>",
"cn": "<cn>",
"net": "<net>",
"rcn": "<rcn>",
"rnet": "<rnet>",
"send_date": "<send_date>",
"send_timestamp": <send_timestamp>,
"phone": "<phone>",
"cost": "<cost>",
"sender_id": "<sender>",
"status_name": "<status_name>",
"message": "<message>",
"type": <type>
} |
- при fmt = 0 та all = 2:
Status = <status>, check_time = <check_time>, err = <err>, imsi = <imsi>,
msc = <msc>, mcc = <mcc>, mnc = <mnc>, cn = <cn>, net = <net>, rcn = <rcn>, rnet = <rnet>,
send_date = <send_date>, phone = <phone>, country = <country>, operator = <operator>, region = <region>, cost = <cost>,
sender_id = <sender_id>, status_name = <status_name>, message = <message>, type = <type> |
- при fmt = 1 та all = 2:
<status>,<last_timestamp>,<err>,<imsi>,<msc>,<mcc>,<mnc>,<cn>,<net>,<rcn>,<rnet>,
<send_timestamp>,<phone>,<country>,<operator>,<region>,<cost>,<sender_id>,<status_name>,<message>,<type> |
- при fmt = 2 та all = 2:
<sms>
<status>status</status>
<last_date>last_date</last_date>
<last_timestamp>last_timestamp</last_timestamp>
<flag>flag</flag>
<err>err</err>
<imsi>imsi</imsi>
<msc>msc</msc>
<mcc>mcc</mcc>
<mnc>mnc</mnc>
<cn>cn</cn>
<net>net</net>
<rcn>rcn</rcn>
<rnet>rnet</rnet>
<send_date>send_date</send_date>
<send_timestamp>send_timestamp</send_timestamp>
<phone>phone</phone>
<cost>cost</cost>
<sender_id>sender_id</sender_id>
<status_name>status_name</status_name>
<message>message</message>
<country>country</country>
<operator>operator</operator>
<region>region</region>
<type>type</type>
</sms> |
- при fmt = 3 та all = 2:
{
"status": <status>,
"last_date": "<last_date>",
"last_timestamp": <last_timestamp>,
"flag": <flag>,
"err": <err>,
"imsi": "<imsi>",
"msc": "<msc>",
"mcc": "<mcc>",
"mnc": "<mnc>",
"cn": "<cn>",
"net": "<net>",
"rcn": "<rcn>",
"rnet": "<rnet>",
"send_date": "<send_date>",
"send_timestamp": <send_timestamp>,
"phone": "<phone>",
"cost": "<cost>",
"sender_id": "<sender>",
"status_name": "<status_name>",
"message": "<message>",
"country": "<country>",
"operator": "<operator>",
"region": "<region>",
"type": <type>
} |
Де:
<status> – код статусу (список)
<last_date> – дата останньої зміни статусу. Формат DD.MM.YYYY HH:mm: ss.
<last_timestamp> – штамп часу останньої зміни статусу.
<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-ознака шаблонного повідомлення.
<err> – код HLR-помилки або Статусу абонента (список).
<imsi> – унікальний код IMSI SIM-карти абонента.
<msc> – номер сервіс-центру оператора, в мережі якого знаходиться абонент.
<mcc> – числовий код країни абонента.
<mnc> – числовий код оператора абонента.
<cn> – назва країни реєстрації абонента.
<net> – назва оператора реєстрації абонента.
<rcn> – назва роумінгової країни абонента при знаходженні в чужій мережі.
<rnet> – назва роумінгового оператора абонента при знаходженні в чужій мережі.
<send_date> – дата відправки повідомлення (формат DD.MM.YYYY hh:mm:ss).
<send_timestamp> – штамп часу відправки повідомлення.
<phone> – номер телефону абонента.
<country> – назва країни реєстрації номера абонента.
<operator> – назва оператора абонента.
<region> – регіон реєстрації номера абонента.
<cost> – вартість повідомлення.
<sender> – ім'я відправника.
<status_name> – назва статусу.
<message> – текст повідомлення.
<type> - тип повідомлення (для HLR дорівнює 4).
Якщо повідомлення не знайдене або знаходиться в архівній базі (Значення статусу дорівнює -3), то для fmt = 0,2,3 повертається код статусу у
відповідному форматі. Для fmt = 1 повертається відповідь в форматі статусу звичайного повідомлення.
При множині запиті статусів:
- для fmt = 0 і fmt = 1 в результаті повертається список рядків, кожна з яких містить інформацію про статус відповідного повідомлення.
- для fmt = 2 формат статусів, що повертаються, аналогічний формату для одиночних повідомлень, при цьому весь список статусів заключається в тег "<list>".
- для FMT = 3 формат також аналогічний формату для одиночних повідомлень, статуси перераховуються через кому, і весь список обрамляється
квадратна дужка.
У разі множинного запиту статусів при значенні параметра all = 1 або all = 2 для кожного статусу додатково повертається ідентифікатор
повідомлення. При all = 0 додатково повертається ідентифікатор повідомлення і номер телефону.Коди статусівМожливі варіанти кодів статусів повідомлень або HLR-запитів (значення <status>):
Код | Назва | Опис
|
---|
-3 | Повідомлення не знайдене | Виникає, якщо для вказаного номера телефону та ID повідомлення не знайдено.
|
---|
-2 | Зупинено | Виникає у повідомлень з розсилки, які не встигли піти оператору до моменту тимчасової зупинки даної розсилки на сторінці Розсилки та завдання.
|
---|
-1 | Очікує відправки | Якщо при відправці повідомлення було задано час отримання абонентом, то до цього часу повідомлення буде
перебувати в даному статусі, в інших випадках повідомлення в цьому статусі знаходиться нетривалий час перед відправкою на SMS-центр.
|
---|
0 | Передано оператору | Повідомлення було передано на SMS-центр оператора для доставки.
|
---|
1 | Доставлене | Повідомлення було успішно доставлене абоненту.
|
---|
2 | Прочитано | Повідомлення було прочитано (відкрито) абонентом. Даний статус можливий для e-mail-повідомлень, що мають формат html-документа.
|
---|
3 | Прострочено | Виникає, якщо час "життя" повідомлення минув, а воно так і не було доставлене одержувачу, наприклад, якщо абонент
не був доступний протягом певного часу або в його телефоні був переповнений буфер повідомлень.
|
---|
4 | Натиснуте посилання | Повідомлення було доставлено, і абонентом було натиснуте коротке посилання, передане в повідомленні.
Даний статус можливий при включених в налаштуваннях опціях "Автоматично скорочувати посилання в повідомленнях" і "відстежувати номери абонентів".
|
---|
20 | Неможливо доставити | Спроба доставити повідомлення закінчилася невдало, це може бути викликане різними причинами, наприклад,
абонент заблокований, не існує, знаходиться в роумінгу без підтримки обміну SMS, або на його телефоні не підтримується прийом SMS-повідомлень.
|
---|
22 | Невірний номер | Неправильний формат номера телефону.
|
---|
23 | Заборонено | Виникає при спрацьовуванні обмежень на відправку дублів, на часті повідомлення на один номер (флуд), на номери з
чорного списку, на заборонені спам фільтром тексти або імена відправників (Sender ID).
|
---|
24 | Недостатньо коштів | На рахунку клієнта недостатня сума для відправки повідомлення.
|
---|
25 | Недоступний номер | Телефонний номер не приймає SMS-повідомлення, або на цього оператора немає робочого маршруту.
|
---|
Запит статусів повідомлень необхідно здійснювати протягом доби з моменту відправки.
Після закінчення даного часу повідомлення поміщаються в архівну базу. В 03:00 за московським часом переносяться
повідомлення з кінцевим статусом, відправлені до 18:00 минулого дня. Для можливості отримання реальних статусів
таких повідомлень необхідно звернутися до служби підтримки.
Також сервер не приймає більше п'яти однакових запитів на отримання статусу одного і того ж повідомлення або більше одного масового запиту
протягом хвилини для зниження навантаження і захисту від помилок і зациклення в програмі на стороні Клієнта.
Коди помилок у статусіМожливі коди помилок у статусі повідомлень або HLR-запитів (значення <err>):
Код | Назва | Опис
|
---|
0 | Немає помилки | Абонент існує та доступний.
|
---|
1 | Абонент не існує | Зазначений номер телефону не існує.
|
---|
6 | Абонент не в мережі | Телефон абонента відключений або знаходиться поза зоною дії мережі.
|
---|
11 | Не підключена послуга | Означає, що абонент не може прийняти SMS-повідомлення. Наприклад, послуга не підключена,
або абонент знаходиться в роумінгу, де не активований прийом повідомлень, або у оператора абонента не налагоджений обмін SMS із
поточним роумінговим оператором. Також це може бути міський номер без прийому повідомлень.
|
---|
12 | Помилка в телефоні абонента | Неможливо доставити повідомлення абоненту через помилки в телефонному апараті або SIM-картці.
|
---|
13 | Абонент заблокований | Виникає, наприклад, якщо на рахунку абонента нульовий або негативний баланс, і
він знаходиться в роумінгу, або заблокований оператором за тривалу несплату або добровільно самим абонентом. Також
ця помилка може повертатися при пошкодженні SIM-карти або неправильному введенні PIN і PUK-кодів SIM-карти.
|
---|
21 | Немає підтримки сервісу | Апарат абонента не підтримує роботу з даною послугою (сервісом).
|
---|
200 | Віртуальна відправка | Дане повідомлення з'являється під статусом повідомлення в разі відправки
повідомлення в режимі тестування (при встановленій в налаштуваннях галочці "Режим тестування (віртуальна відправка без
оплати)").
|
---|
219 | Заміна sim-карти | Помилка відправки повідомлення у зв'язку з заміною абонентом sim-карти. Після фізичної заміни sim-карти абоненту заблокований прийом повідомлень від буквених імен відправників на 24 години. Блокування може бути знято шляхом поповнення балансу на 100 рублів.
|
---|
220 | Переповнена чергу у оператора | Зазначена помилка може виникати в разі, коли абонент недоступний
для прийому SMS, але повідомлення продовжують приходити оператору і відбувається переповнення внутрішньої черги повідомлень
для даного абонента. У рідкісних випадках можлива поява помилки в результаті збою в мережі самого оператора або переповненні
загальної черги повідомлень. У всіх подібних ситуаціях система з певними інтервалами кілька разів намагається відправити
зазначені повідомлення повторно.
|
---|
237 | Абонент не відповідає | Виникає, якщо в процесі спроби дозвону абонент не взяв трубку.
|
---|
238 | Немає шаблону | Виникає, якщо відправка повідомлення можлива тільки за певним шаблоном, а відправляється
повідомлення йому не задовольняє.
|
---|
239 | Заборонена ip-адреса | Виникає при спробі відправки повідомлення з ip-адреси, що не входить в список ip-адрес,
дозволених Клієнтом для відправки. Також може виникати при спробі відправки повідомлення з ip-адреси, яка раніше не використовувалась
для відправки повідомлень і входів в особистий кабінет.
|
---|
240 | Абонент зайнятий | Виникає при передачі голосового повідомлення абоненту, якщо абонент зайнятий, або
скасував виклик.
|
---|
241 | Помилка конвертації | При перетворенні тексту або звукового файлу в кінцевий формат для передачі
абоненту голосового повідомлення сталася помилка конвертації звуку. Також дана помилка може виникати при передачі
SMS-повідомлення окремими частинами, коли оператору передані не всі частини.
|
---|
242 | Зафіксовано автовідповідач | Означає, що під час відправки голосового повідомлення на стороні абонента був
зафіксований автовідповідач.
|
---|
243 | Не укладено договір | Виникає при спробі відправки розсилок рекламного або масового характеру без
укладеного договору.
|
---|
244 | Розсилка заборонена | Означає, що для даного Клієнта заборонена відправка масових і рекламних розсилок,
або в тексті повідомлення зустрілось заборонене посилання.
|
---|
245 | Статус не отримано | Протягом доби статус доставки не був отриманий від оператора, в цьому
випадку не можна точно сказати, було повідомлення доставлено чи ні.
|
---|
246 | Обмеження часу | Якщо в особистому кабінеті у пункті "Налаштування" у вкладці "Ліміти та обмеження"
встановлено "Час відправки" і галочка "заборонити відправку в інший час", то при спробі відправки SMS-повідомлень в період
часу, відмінний від зазначеного в полі "Час відправки", відправка повідомлень буде заборонятись із зазначенням даної помилки.
|
---|
247 | Перевищено ліміт повідомлень | Перевищено загальний добовий ліміт повідомлень, зазначений Клієнтом в особистому кабінеті
у пункті "Налаштування".
|
---|
248 | Немає маршруту | Означає, що на даний номер відправка повідомлень недоступна в нашому сервісі.
Наприклад, ввели неіснуючий мобільний код, або для зазначеного номера і тексту немає робочого SMS-шлюзу.
|
---|
249 | Неправильний формат номеру | Виникає, коли мобільний код зазначеного номера і відповідна цьому коду
довжина номера невірні.
|
---|
250 | Номер заборонений налаштуваннями | Номер потрапив під обмеження, встановлені Клієнтом для мобільних номерів в
особистому кабінеті в пункті "Налаштування".
|
---|
251 | Перевищено ліміт на один номер | Перевищено добовий ліміт повідомлень на один номер. Ліміт встановлюється
Клієнтом в особистому кабінеті в пункті "Налаштування". Також така помилка можлива при відправці більше 50 повідомлень одному абоненту,
які були відправлені з перервою між повідомленнями менше 30 секунд.
|
---|
252 | Номер заборонений | Виникає, наприклад, при спробі вказівки Клієнтом одного із наших федеральних номерів
як одержувача SMS-повідомлення.
|
---|
253 | Заборонено спам-фільтром | Якщо текст повідомлення містить нецензурні вирази і образи, заклики відправити
sms і деякі інші заборонені тексти, то відправка повідомлення заблокується. Також заборонено вказувати в якості
відправника короткі платні номери, номер одержувача повідомлень, назви операторів, чужих інтернет-ресурсів, компаній і
державних організацій.
|
---|
254 | Незареєстрований sender id | Дана помилка виникає при спробі відправки повідомлення від незареєстрованого
імені відправника.
|
---|
255 | Відхилено оператором | Оператор відхилив повідомлення без вказівки точного коду помилки. Таке буває, наприклад,
коли номер не належить жодному мобільному оператору, тобто з неіснуючим кодом, або з якоїсь іншої причини оператор
не може доставити повідомлення.
|
---|
Можливі коди помилок в статусі e-mail повідомлень (значення <err>):
Код | Назва | Опис
|
---|
0 | Немає помилки | Одержувач існує і доступний.
|
---|
1 | Адресат не існує | Вказана e-mail адреса не існує.
|
---|
2 | Поштову скриньку переповнено | Поштовий сервер одержувача відхилив повідомлення з вказаним кодом помилки.
|
---|
3 | Сервер одержувача не знайдено | Домен, вказаний як поштовий сервер, не знайдено.
|
---|
4 | Поштову скриньку заблоковано | Від поштового сервера одержувача повернулася помилка про неможливість доставки
повідомлення через блокування ящика.
|
---|
239 | Заборонена ip-адреса | Виникає при спробі відправки повідомлення з ip-адреси, що не входить в список ip-адрес,
дозволених Клієнтом для відправки. Також може виникати при спробі відправки повідомлення з ip-адреси, яка раніше не використовувалась
для відправки повідомлень і входів в особистий кабінет.
|
---|
245 | Статус не отримано | Протягом доби статус доставки не був отриманий від поштового сервера одержувача, в цьому
разі не можна точно сказати, було повідомлення доставлено чи ні.
|
---|
248 | Немає маршруту | Означає, що на даний e-mail адресу відправка повідомлень недоступна в нашому сервісі.
Наприклад, для вказаної адреси і тексту немає робочого e-mail шлюзу.
|
---|
249 | Неправильний формат адреси | Виникає, коли ввели некоректну за форматом e-mail адресу одержувача.
|
---|
252 | E-mail адреса заборонена | Виникає, наприклад, при знаходженні вказаної e-mail адреси в чорному списку.
|
---|
253 | Заборонено спам-фільтром | Якщо текст повідомлення містить нецензурні вирази і образи, заклики відправити
sms або e-mail і деякі інші заборонені Тексти, то відправка повідомлення заблокується. Також заборонено вказувати в якості
відправника e-mail адреса одержувача повідомлення, адреси чужих інтернет-ресурсів, компаній і державних організацій.
|
---|
254 | Незареєстрований відправник | Дана помилка виникає при спробі відправки повідомлення від незареєстрованого
e-mail адреси відправника.
|
---|
255 | Відхилено сервером одержувача | Поштовий сервер одержувача відхилив повідомлення без вказівки точного коду помилки. Таке буває, наприклад,
при виникненні внутрішньої помилки сервера, коли він не може обробити повідомлення.
|
---|
Видалення повідомленняЩоб видалити повідомлення необхідно викликати методом GET або POST скрипт запиту статусу, вказавши команду del:
https://smsc.ua/sys/status.php?del=1&login=<login>&psw=<password>&phone=<phone>&id=<sms_id>
Опис параметрів, що передаються Серверу, і помилок, що повертаються їм, аналогічний наведеному для функції запиту статусу.
У разі успішного запиту Сервер повертає відповідь у вигляді рядка:
- при fmt = 0,1: OK
- при fmt = 2:
<result>OK</result>
- при fmt = 3:
Видалення повідомлень необхідно зробити до перенесення в архівну базу.
Перевірка стану балансуЗапит балансуДля запиту балансу використовуйте адресу:
https://smsc.ua/sys/balance.php?login=<login>&psw=<password>
Серверу передаються наступні параметри:
Параметр | Значення
|
---|
login | Логін Клієнта.
|
---|
psw | Пароль Клієнта (можна додати або редагувати на даннійсторінці).
|
---|
cur | Прапор, який вказує на необхідність додавання у відповідь сервера назви валюти клієнта.
|
---|
fmt | Формат відповіді сервера:
0 або 1 – (за замовчуванням) у вигляді рядка (250.80).
2 – у xml форматі.
3 – у json форматі.
|
---|
Баланс. Відповідь сервера та коди помилок
У разі помилки Сервер повертає наступний рядок:
- При fmt = 0:
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-адреси, що не входить в список дозволених Клієнтом (якщо такий список був налаштований Клієнтом раніше).
|
---|
4 | IP-адреса тимчасово заблокована.
|
---|
9 | Спроба відправки більше десяти запитів на отримання балансу протягом хвилини.
Дана помилка виникає також при спробі відправки п'ятнадцяти і більше запитів одночасно з різних підключень під одним логіном (too many concurrent requests).
|
---|
У разі успішного запиту Сервер повертає відповідь у вигляді рядка:
При cur = 0:
- при fmt = 0 або 1: <balance>
- при fmt = 2: <balance>balance</balance>
- при fmt = 3:
{
"balance": "<balance>"
} |
При cur = 1 і ненульовому кредиті:
- при fmt = 0: <balance> <currency>
- при fmt = 1: <balance>,<currency>
- При fmt = 2:
<result>
<balance>balance</balance>
<credit>credit</credit>
<currency>currency</currency>
</result> |
- при fmt = 3:
{
"balance": "<balance>",
"credit": "<credit>",
"currency": "<currency>"
} |
Де:
<balance> – поточний стан балансу.
<credit> – поточний стан встановленого кредиту.
<currency> – валюта Клієнта.
Сервер не приймає більше десяти запитів на отримання балансу протягом хвилини для зниження
навантаження і захисту від помилок і зациклень в програмі на стороні клієнта.
Дії з контактами і групамиДля управління контактами або групами необхідно викликати методом GET або POST відповідну адресу із зазначенням
необхідної команди і параметрів.
Для створення контакту:
https://smsc.ua/sys/phones.php?add=1&login=<login>&psw=<password>&phone=<phone>&name=<name>
Для створення нової групи:
https://smsc.ua/sys/phones.php?add_group=1&login=<login>&psw=<password>&name=<name>
Для зміни номера телефону в контакті:
https://smsc.ua/sys/phones.php?chg=1&login=<login>&psw=<password>&phone=<phone>&new_phone=<new_phone>
Для зміни назви групи:
https://smsc.ua/sys/phones.php?chg_group=1&login=<login>&psw=<password>&grp=<group_id>&name=<name>
Для перенесення контакту в нову групу:
https://smsc.ua/sys/phones.php?move_group=1&login=<login>&psw=<password>&grp=<group_id>&phone=<phone>
Для додавання нової групи до контакту:
https://smsc.ua/sys/phones.php?move_group=2&login=<login>&psw=<password>&grp=<group_id>&phone=<phone>
Для видалення контакту з групи:
https://smsc.ua/sys/phones.php?move_group=3&login=<login>&psw=<password>&grp=<group_id>&phone=<phone>
Для видалення контакту:
https://smsc.ua/sys/phones.php?del=1&login=<login>&psw=<password>&phone=<phone>
Для видалення групи:
https://smsc.ua/sys/phones.php?del_group=1&login=<login>&psw=<password>&grp=<group_id>
Для виведення списку контактів:
https://smsc.ua/sys/phones.php?get=1&login=<login>&psw=<password>
Для виведення списку груп:
https://smsc.ua/sys/phones.php?get_group=1&login=<login>&psw=<password>
Для додавання запису в" чорний " список:
https://smsc.ua/sys/phones.php?add_black=1&login=<login>&psw=<password>&phone=<phone>
Для видалення запису з" чорного " списку:
https://smsc.ua/sys/phones.php?del_black=1&login=<login>&psw=<password>&phone=<phone>
Для отримання елементів "чорного" списку:
https://smsc.ua/sys/phones.php?get_black=1&login=<login>&psw=<password>
Контакти та групи. Опис параметрівОпис параметрів, що передаються Серверу:
Параметр | Значення
|
---|
login | Логін Клієнта.
|
---|
psw | Пароль Клієнта (можна додати або редагувати на даннійсторінці).
|
---|
name | Назва контакту або групи.
|
---|
grp | Ідентифікатор групи, якій належить контакт, який створюється. Можна прив'язати контакт
відразу до декількох груп, вказавши їх ідентифікатори через кому.
|
---|
num | Номер групи для розсилок повідомлень.
|
---|
phone | Список номерів телефонів через будь-який роздільник (команда add), або номер телефону
(команда move_group, add_black). Використовується для операцій з номерами телефонів у скрипті phones.php.
|
---|
mail | Список e-mail адрес через будь-який роздільник (команда add), або e-mail адреса
(команда move_group, add_black). Використовується для операцій з e-mail адресами в скрипті mails.php.
Формат запитів аналогічний формату для phones.php.
|
---|
new_phone | Новий список номерів телефонів через будь роздільник (команда chg).
|
---|
new_mail | Новий список e-mail адрес через будь-який роздільник (команда chg).
|
---|
lnm | Прізвище.
|
---|
fnm | Ім'я.
|
---|
mnm | По батькові.
|
---|
fio | ПІБ контакту. Цей параметр використовується в команді get для отримання списку контактів по будь-якому з
ініціалів (прізвища, імені та (або) по-батькові).
|
---|
search | Вибірка контактів для команди get за назвою контакту та (або) номером телефону.
|
---|
after_id | Ідентифікатор контакту (int_id), починаючи з якого необхідно повернути список контактів (команда get, формат fmt=3), за винятком самого
after_id.
|
---|
bd | Дата народження у форматі дд.мм.рррр.
|
---|
myid | ID контакту, призначений Клієнтом.
|
---|
cmt | Коментарі.
|
---|
tags | Теги (мітки).
|
---|
pho | Інші номери телефонів. За даними номерами розсилка SMS-повідомлень не виконується.
|
---|
type | Тип блокування (команда add_black):
0 – всі повідомлення.
1 – масові розсилки.
2 – поодинокі повідомлення.
Або тип групи (команда add_group і get_group):
0 – група для номерів телефонів.
1 – група для E-mail адрес.
|
---|
prev_id | Глобальний ідентифікатор елемента" чорного " списку (параметр id у відповіді Сервера), що призначається Сервером автоматично. Використовується в команді get_black для запиту елементів "чорного списку", доданих раніше до даного елемента.
|
---|
cnt | Кількість записів, що повертаються у відповіді Сервера. Максимальне значення дорівнює 1000.
|
---|
fmt | Формат відповіді сервера:
0 – (за замовчуванням) у вигляді рядка (ID = 12345).
1 – у вигляді рядка (12345).
2 – у xml форматі.
3 – у json форматі.
|
---|
Контакти та групи. Відповідь сервера та коди помилок
У разі помилки Сервер повертає наступний рядок:
- 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 | Записи не знайдені.
|
---|
4 | IP-адреса тимчасово заблокована.
|
---|
5 | Помилка виконання операції.
|
---|
9 | Спроба відправки більше трьох однакових запитів на операції з групами, контактами або записами "чорного" списку протягом хвилини.
Дана помилка виникає також при спробі відправки п'ятнадцяти і більше запитів одночасно з різних підключень під одним логіном (too many concurrent requests).
|
---|
У разі успішного запиту Сервер повертає відповідь у вигляді рядка.
При створенні контакту, групи контактів, записи "чорного" списку:
- при fmt = 0: ID = <id>
- при fmt = 1: <id>
- при fmt = 2 (створення контакту, запису "чорного" списку):
<phone>
<id>id</id>
</phone> |
- при fmt = 2 (створення групи):
<group>
<id>id</id>
</group> |
- при fmt = 3:
Де <id> - ідентифікатор контакту, групи або запису "чорного" списку, призначений Сервером автоматично.
При зміні або видаленні контакту (групи), видаленні запису "чорного" списку:
- при fmt = 0,1: OK
- при fmt = 2: <result>OK</result>
- при fmt = 3:
При запиті списку контактів:
- при fmt = 0:
phone = <phone>, name = <name>, group = <group>, first_name = <first_name>, last_name = <last_name>, middle_name = <middle_name>,
birthday = <birthday>, id = <id>, comments = <comments>, tags = <tags>, phone_other = <phone_other>
... |
- при fmt = 1:
<phone>,<name>,<group>,<first_name>,<last_name>,<middle_name>,<birthday>,<id>,<comments>,<tags>,<phone_other>
... |
- при fmt = 2:
<list>
<contact>
<phone>phone</phone>
<name>name</name>
<group>group</group>
<first_name>first_name</first_name>
<last_name>last_name</last_name>
<middle_name>middle_name</middle_name>
<birthday>birthday</birthday>
<id>id</id>
<comments>comments</comments>
<tags>tags</tags>
<phone_other>phone_other</phone_other>
</contact>
...
</list> |
- при fmt = 3:
[{
"phone": "<phone>",
"name": "<name>",
"group": <group>,
"first_name": "<first_name>",
"last_name": "<last_name>",
"middle_name": "<middle_name>",
"birthday": "<birthday>",
"id": "<id>",
"comments": "<comments>",
"tags": "<tags>",
"phone_other": "<phone_other>"
},
...] |
Де:
<phone> – список номерів телефонів через будь-який роздільник. Для e-mail адрес замінюється на <mail>.
<name> – назва контакту.
<group> – ідентифікатор групи, до якої належить контакт.
<first_name> – ім'я.
<last_name> – прізвище.
<middle_name> – по батькові.
<birthday> – дата народження у форматі дд.мм.рррр.
<id> – id контакту, призначений Клієнтом.
<comments> – коментарі.
<tags> – теги (мітки).
<phone_other> - інші номери телефонів. За даними номерами розсилка повідомлень не виконується. Для e-mail
адрес замінюється на <mail_other>.
При запиті списку груп:
- при fmt = 0:
id = <id>, name = <name>, number = <number>, cnt = <cnt>
... |
- при fmt = 1:
<id>,<name>,<number>,<cnt>
... |
- при fmt = 2:
<list>
<group>
<id>id</id>
<name>name</name>
<number>number</number>
<cnt>number</cnt>
</group>
...
</list> |
- при fmt = 3:
[{
"id": <id>,
"name": "<name>",
"number": <number>,
"cnt": "<cnt>"
},
...] |
Де:
<id> – ідентифікатор групи, призначений Сервером при створенні.
<name> – назва групи.
<number> – номер групи для розсилок.
<cnt> – кількість контактів у групі.
При запиті елементів "чорного" списку:
- при fmt = 0:
id = <id>, phone = <phone>, type = <type>, comment = <comment>
... |
- при fmt = 1:
<id>,<phone>,<type>,<comment>
... |
- при fmt = 2:
<list>
<record>
<id>id</id>
<phone>phone</phone>
<type>type</type>
<comment>comment</comment>
</record>
...
</list> |
- при fmt = 3:
[{
"id": <id>,
"phone": "<phone>",
"type": <type>,
"comment": "<comment>"
},
...] |
Де:
<id> – ідентифікатор елемента, призначений Сервером при створенні.
<phone> – номер телефону (або <email> при запиті" чорного " списку e-mail).
<type> – тип блокування: 0-всі повідомлення, 1-масові розсилки, 2-поодинокі повідомлення.
<comment> – коментарі.Приклади операцій з контактамиПриклади:
Створення контакту з іменем "Contact", що належить групі з ID = 321:
https://smsc.ua/sys/phones.php?add=1&login=alex&psw=123&phone=79999999999&name=Contact&grp=321
Створення групи з іменем "Group":
https://smsc.ua/sys/phones.php?add_group=1&login=alex&psw=123&name=Group
Зміна імені контакту з номером телефону "79999999999 "на нове ім'я "Contact1":
https://smsc.ua/sys/phones.php?chg=1&login=alex&psw=123&phone=79999999999&name=Contact1
Зміна назви групи з ID = 321 на нову назву " Group1":
https://smsc.ua/sys/phones.php?chg_group=1&login=alex&psw=123&grp=321&name=Group1
Видалення контакту з номером телефону "79999999999":
https://smsc.ua/sys/phones.php?del=1&login=alex&psw=123&phone=79999999999
Видалення групи з ID = 321:
https://smsc.ua/sys/phones.php?del_group=1&login=alex&psw=123&grp=321
Отримання списку контактів, що належать групі з ID = 321:
https://smsc.ua/sys/phones.php?get=1&login=alex&psw=123&grp=321
Отримання даних контакту з номером телефону "79999999999":
https://smsc.ua/sys/phones.php?get=1&login=alex&psw=123&phone=79999999999
Отримання списку всіх груп:
https://smsc.ua/sys/phones.php?get_group=1&login=alex&psw=123
Додавання телефону "79999999999" в "чорний" список із блокуванням тільки масових розсилок:
https://smsc.ua/sys/phones.php?add_black=1&login=alex&psw=123&phone=79999999999&type=1
Видалення телефону "79999999999" із "чорного" списку:
https://smsc.ua/sys/phones.php?del_black=1&login=alex&psw=123&phone=79999999999
Сервер не приймає більше трьох однакових запитів протягом хвилини на операції з групами,
контактами або записами "чорного" списку для зниження навантаження і захисту від помилок і зациклень в програмі на стороні клієнта.
Перелік доступних операційДля створення або зміни субклієнта необхідно викликати методом GET або POST відповідну адресу із зазначенням необхідної команди і параметрів.
Створення субклієнта:
https://smsc.ua/sys/users.php?add=1&login=<login>&psw=<password>&user=<user>&password=<password2>
Зміна налаштувань субклієнта:
https://smsc.ua/sys/users.php?chg=1&login=<login>&psw=<password>&user=<user>&fio=<fio>
Зміна балансу субклієнта:
https://smsc.ua/sys/users.php?pay=1&login=<login>&psw=<password>&user=<user>&sum=<sum>
Отримання статистики по субклієнтах із незалежним балансом:
https://smsc.ua/sys/users.php?get_stat=1&login=<login>&psw=<password>&start=<date1>&end=<date2>&reseller=1
Отримання статистики по одному субклієнту:
https://smsc.ua/sys/users.php?get_stat=1&login=<login>&psw=<password>&start=<date1>&end=<date2>&user=<sub_login>
або:
https://smsc.ua/sys/users.php?get_stat=1&login=<login>&psw=<password>&start=<date1>&end=<date2>&user_id=<id>
Отримання детальної статистики по субклієнтам з незалежним балансом:
https://smsc.ua/sys/users.php?get_stat_all=1&login=<login>&psw=<password>&start=<date1>&end=<date2>&reseller=1 Субклієнти. Опис параметрів
Опис параметрів, що передаються Серверу:
Параметр | Значення
|
---|
login | Логін Клієнта.
|
---|
psw | Пароль Клієнта (можна додати або редагувати на даннійсторінці).
|
---|
user | Логін субклієнта.
|
---|
pswc | Поточний пароль субклієнта.
|
---|
password | Новий пароль субклієнта. Довжина повинна бути не менше 8 символів, і виконуватися 3 з умов: букви, цифри, різний регістр, символи.
|
---|
sum | Сума, що перераховується клієнту з головного аккаунта у валюті головного аккаунта.
|
---|
balance2 | Прапор, який встановлює можливість використання електронного балансу для зарахувань, списань і отримання статистики за повідомленнями.
|
---|
site_id | ID сайту, якому належатиме створюваний субклієнт.
|
---|
new_login | Новий логін субклієнта при зміні.
|
---|
type | Тип облікового запису. 0 (за замовчуванням) – незалежні тариф і баланс.
1 – тариф головного аккаунта, незалежний баланс. 2 – тариф і баланс головного аккаунта.
3 – баланс головного аккаунта, незалежний тариф. 4 – додатковий логін головного аккаунта.
|
---|
email | Основна адреса електронної пошти.
|
---|
fl[9] | Прапор, який встановлює можливість пересилки вхідних SMS на e-mail.
|
---|
email2 | Альтернативну адресу електронної пошти для пересилання вхідних SMS.
|
---|
phone | Основний номер телефону.
|
---|
fl[8] | Прапор, який встановлює можливість пересилки вхідних SMS на телефон.
|
---|
phone2 | Альтернативний номер телефону для пересилання вхідних SMS.
|
---|
start | Початкова дата в періоді, за який запитується статистика. Формат: 'дд.мм. рррр'.
|
---|
end | Кінцева дата в періоді. Якщо не вказана, то повертаються дані з початкової дати. Формат: 'дд.мм. рррр'.
|
---|
user_id | Ідентифікатор субклієнта, який призначається сервером автоматично при створенні.
|
---|
reseller | Типи субклієнтів. 0 або відсутній-субклієнти, що використовують баланс головного аккаунта.
1 – субклієнти із незалежним балансом.
|
---|
hide_deleted | Приховати статистику по віддалених субклієнтах. 0 або відсутній-вивести статистику по всіх субклієнтах. 1 – приховати статистику по віддалених субклієнтах.
|
---|
mycur | Прапор, що дозволяє виводити статистику у валюті головного аккаунта.
|
---|
fio | Ініціали (прізвище, ім'я, по батькові) або назва компанії.
|
---|
props | Поле" інші реквізити " субклієнта.
|
---|
cntr | Номер договору.
|
---|
tariff | Поточний тарифний план. Субклієнту можна встановити тарифний план не вище тарифного плану Клієнта. Параметр може приймати такі значення: 0 (за замовчуванням) – 1 тариф (від 1 р.).
1 – 2 тариф (від 1000 р.).
...
8 – 9 тариф (від 100000 р.).
|
---|
mintrf | Мінімальний тариф. Визначає мінімальне значення тарифу субклієнта незалежно від суми платежу.
|
---|
curr | Валюта розрахунків субклієнта. Використовується в командах add и chg. Може приймати наступні основні значення:
1 – російський рубль;
2 – долар США;
3 – євро;
4 – українська гривня;
5 – казахстанський тенге.
|
---|
tz | Часовий пояс. За замовчуванням встановлюється часовий пояс Клієнта. Можливі значення:
0 – GMT-12. ... 12 – GMT+00 ... 24 – GMT+12.
|
---|
sender | Ім'я відправника (Sender ID) за замовчуванням.
|
---|
sender2 | Резервне ім'я відправника.
|
---|
fl[29] | Прапор, який визначає можливість використання списку відправників Клієнта (головного аккаунту).
|
---|
fl2[9] | Прапор, який дозволяє використання більш дорогих маршрутів для гарантованої доставки повідомлень.
|
---|
fl2[24] | Прапор, що дозволяє відправляти спочатку через дешеві маршрути, при недоставці повторювати через дорогі (окрім масових розсилок).
|
---|
fl2[12] | Прапор забороняє відправку повідомлень із автоматичною заміною імені відправника.
|
---|
fl2[13] | Прапор відключає додавання імені відправника в текст повідомлень без подорожчання в разі автозаміни.
|
---|
nb | Баланс для повідомлень. При досягненні зазначеної суми будуть відправлятися повідомлення на e-mail субклієнта.
|
---|
ktm | Цей параметр встановлює кількість днів для зберігання відправлених повідомлень, після закінчення яких SMS-повідомлення будуть автоматично видалятися з історії.
|
---|
fmts | Список телефонних кодів, за якими дозволена відправка повідомлень.
|
---|
notes | Коментарі головного облікового запису. Недоступні субклієнту.
|
---|
fl2[23] | Заборона масових і рекламних розсилок.
|
---|
fl[26] | Дозвіл використання списку контактів головного аккаунта.
|
---|
fl2[8] | Прапор, що встановлює розширений режим особистого кабінету.
|
---|
fl[16] | Включити розпізнавання автовідповідачів при дзвінках.
|
---|
fl2[31] | Дозволити використання шаблонів головного облікового запису.
|
---|
Додаткові параметри для налаштування доступу до сервісу
|
---|
fl3[20] | Прапор, що дозволяє відключити підтвердження доступу з нових IP-адрес при вході.
|
---|
ph | Список телефонів або номерів груп через кому для виконання розсилок по SMS-командах.
|
---|
fl[27] | Заборонити зміни налаштувань субклієнтом.
|
---|
fl[28] | Заборонити оплати субаккаунтом.
|
---|
fl[6] | Заборонити розсилки.
|
---|
fl2[1] | Приховати повідомлення для субклієнта.
|
---|
fl2[10] | Заблокувати субаккаунт.
|
---|
Додаткові параметри для лімітів і обмежень
|
---|
dlim | Загальний ліміт SMS за день. Визначає максимальну кількість відправлених за добу повідомлень.
|
---|
plim | Ліміт на один номер. Встановлює максимальну кількість повідомлень, відправляються за добу, на один номер телефону.
|
---|
tlim | Ліміт на номер і текст. Встановлює максимальну кількість повідомлень, що відправляються за добу, з одним текстом на один номер телефону.
|
---|
ilim | Ліміт з однієї IP-адреси. Задає максимальну кількість повідомлень, що відправляються за добу, з однієї IP-адреси.
|
---|
tmlim | Діапазон часу в годиннику h1-h2, в який дозволено відправляти повідомлення. Якщо поточний час менше h1, то SMS-повідомлення буде відправлено абоненту при настанні часу h1, якщо поточний час потрапляє в проміжок від h1 до h2, то повідомлення буде відправлено негайно, в іншому випадку відправка буде виконана на наступний день при досягненні часу h1. Ця функція, наприклад, корисна для того, щоб не допустити отримання SMS-повідомлень абонентами в нічний час.
|
---|
fl2[15] | Заборонити відправку в інший час, окрім зазначеного в параметрі tmlim, замість перенесення на наступний день.
|
---|
fl2[16] | При використанні параметра tmlim враховувати часовий пояс абонентів.
|
---|
vld | Максимальний строк доставки повідомлень тимчасово недоступним абонентам (хв.).
|
---|
Додаткові параметри для автовідповідачів
|
---|
answ | Автовідповідь на вхідні SMS.
|
---|
answ_call | Автовідповідь на вхідні дзвінки.
|
---|
fl2[4] | Відключити пересилку дзвінків (на e-mail, телефон і обробник).
|
---|
Додаткові параметри для налаштувань API
|
---|
url | http-адреса (URL) скрипта для обробки статусів доставки SMS-повідомлень і (або) вхідних SMS-повідомлень на стороні субклієнта. Зазначений скрипт буде викликатись Сервером після кожного отримання статусу доставки раніше відправленого субклієнтом SMS-повідомлення та (або) після отримання вхідного SMS-повідомлення від абонента.
|
---|
fl[10] | Вмикання пересилання статусів повідомлень на http-адресу, вказану в параметрі url.
|
---|
fl[11] | Вмикання пересилання вхідних SMS-повідомлень на http-адресу, встановлену в параметрі url.
|
---|
fl[2] | Включити SMPP-доступ (попередньо необхідно зареєструвати IP-адреси через ONLINE-підтримку).
|
---|
fl[1] | Передавати вхідні SMS по SMPP-підключенню.
|
---|
fl[23] | Відслідковувати статуси окремих SMS-частин.
|
---|
fl2[27] | Режим тестування (віртуальна відправка без оплати).
|
---|
fl[5] | Включити контроль за доставкою повідомлень.
|
---|
fl[30] | Включення лога API. Дозволяє переглядати 20 останніх http-запитів. Зберігається 10 хвилин після останнього запиту.
|
---|
Додаткові параметри для E-mail2sms
|
---|
mfl[0] | Прапор, що дозволяє відключити функцію e-mail2sms.
|
---|
mph | Розділений комою список номерів телефонів, на які будуть відправлятись повідомлення.
|
---|
mfl[5] | Включає можливість вказівки списку телефонів у тілі листа.
|
---|
mfl[6] | Включає можливість вказівки списку телефонів у адресі листа.
|
---|
mfl[1] | Пересилання листа без теми.
|
---|
mfl[2] | Пересилання листа без тексту.
|
---|
mfl[3] | Пересилання листа без зворотної адреси (від кого).
|
---|
mfl[4] | Переклад тексту листа в трансліт.
|
---|
mh1 | Початкове значення діапазону часу для відправки вхідних листів. Разом із параметром mh2 визначає діапазон, протягом якого можливе пересилання вхідних листів у вигляді SMS-повідомлень.
|
---|
mh2 | Кінцеве значення діапазону часу для відправки вхідних листів.
|
---|
mlen | Максимальна довжина повідомлення, до якої обрізається вхідний лист при відправці у вигляді SMS-повідомлення (число більше 12 задає максимальну довжину повідомлення, менше 12 - кількість SMS).
|
---|
Відповідь сервера і коди помилок
У разі помилки Сервер повертає наступний рядок:
- 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 | Записи не знайдені.
|
---|
4 | IP-адреса тимчасово заблокована.
|
---|
5 | Помилка виконання операції.
|
---|
6 | Субклієнт з указаним іменем не існує.
|
---|
7 | Вказано сублогін, який має загальний баланс із головним аккаунтом, або в запиті на операцію з електронним балансом не вказано параметр balance2=1.
|
---|
8 | Помилка при збереженні запису.
|
---|
9 | Спроба відправки більше трьох запитів на додавання субклієнтів
або зміна одного і того ж субклієнта протягом хвилини.
Дана помилка виникає також при спробі відправки п'ятнадцяти і більше запитів одночасно з різних підключень під одним логіном (too many concurrent requests).
|
---|
10 | Недостатньо коштів для зарахування.
|
---|
У разі успішного запиту Сервер повертає відповідь у вигляді рядка.
При створенні субклієнта:
- при fmt = 0: ID = <id>
- при fmt = 1: <id>
- при fmt = 2:
<user
<id>id</id>
</user> |
- при fmt = 3:
Де <id> – ідентифікатор субклієнта, призначений Сервером автоматично.
При зміні сублогіна:
- при fmt = 0,1: OK
- при fmt = 2:
<result>OK</result>
- при fmt = 3:
При запиті статистики:
- при fmt = 0 та get_stat = 1:
login = <login>, sms = <cnt>, credit = <credit>, debit = <debit>, currency = <currency>
... |
- при fmt = 0 та get_stat_all = 1:
login = <login>, description = <description>, operator = <operator>, mccmnc = <mccmnc>, sms = <cnt>, credit = <credit>, debit = <debit>, currency = <currency>
... |
- при fmt = 1 та get_stat = 1:
<login>,<cnt>,<credit>,<debit>,<currency>
... |
- при fmt = 1 та get_stat_all = 1:
<login>,<description>,<operator>,<mccmnc>,<cnt>,<credit>,<debit>,<currency>
... |
- при fmt = 2 та get_stat = 1:
<list>
<stat>
<login>login</login>
<sms>cnt</sms>
<credit>credit</credit>
<debit>debit</debit>
<currency>currency</currency>
</stat>
...
</list> |
- при fmt = 2 та get_stat_all = 1:
<list>
<user login="login">
<item>
<description>description</description>
<operator>operator</operator>
<mccmnc>mccmnc</mccmnc>
<sms>cnt</sms>
<credit>credit</credit>
<debit>debit</debit>
<currency>currency</currency>
</item>
...
</user>
...
</list> |
- при fmt = 3 та get_stat = 1:
[{
"login": "<login>",
"sms": "<cnt>",
"credit": "<credit>",
"debit": "<debit>",
"currency": "<currency>"
},
...] |
- при fmt = 3 та get_stat_all = 1:
[{
"login": "<login>",
"items": [{
"description": "<description>",
"operator": "<operator>",
"mccmnc": "<mccmnc>",
"sms": "<cnt>",
"credit": "<credit>",
"debit": "<debit>",
"currency": "<currency>"
},
...]
},
...] |
Де:
<login> - логін субклієнта.
<description> - назва операції.
<operator> - назва оператора.
<mccmnc> - числовий код країни абонента плюс числовий код оператора абонента
<cnt> - кількість повідомлень.
<credit> - витрати.
<debit> - надходження.
<currency> - трехсимвольный код валюти субклієнта.Приклади дій із субклієнтамиПриклади:
Створення субклієнта з логіном "mylogin", паролем "mypassword", номером телефону 79999999999 і дозволом на використання
імена відправників (Sender ID) головного облікового запису:
https://smsc.ua/sys/users.php?add=1&login=alex&psw=123&user=mylogin&password=mypassword&phone=79999999999&fl[29]=1
Зміна логіна субклієнта з "mylogin" на "mylogin2", типу клієнта на "Тариф і баланс головного облікового запису" і установки
дозволених кодів для відправки SMS тільки по Росії:
https://smsc.ua/sys/users.php?chg=1&login=alex&psw=123&user=mylogin&password=mypassword&new_login=mylogin2&type=2&fmts=7,-77
Отримання статистики по субклієнтам, що мають загальний баланс з головним аккаунтом і SMS, відправлені з електронного балансу:
https://smsc.ua/sys/users.php?get_stat=1&login=alex&psw=123&balance2=1
Отримання статистики по субклієнту з логіном "sub_alex":
https://smsc.ua/sys/users.php?get_stat=1&login=alex&psw=123&user=sub_alex
Отримання статистики по незалежних субклієнтах у валюті головного облікового запису з "01.01.2014" за "01.02.2014":
https://smsc.ua/sys/users.php?get_stat=1&login=alex&psw=123&mycur=1&start=01.01.2014&end=01.02.2014
Сервер не приймає більше трьох запитів протягом хвилини на додавання субклієнтів або зміна одного і того ж субклієнта
для зниження навантаження та захисту від помилок і зациклення в програмі на стороні Клієнта.
Створення і вивантаження рахунків і актівДля створення нового рахунку для субклієнта необхідно викликати методом GET або POST адреси:
https://smsc.ua/sys/documents.php?add_account=1&login=<login>&psw=<password>&user=<user>&sum=<sum>
або:
https://smsc.ua/sys/documents.php?add_account=1&login=<login>&psw=<password>&user_id=<user_id>&sum=<sum>
Для завантаження існуючого рахунку субклієнта необхідно викликати методом GET або POST адреси:
https://smsc.ua/sys/documents.php?get_account=1&login=<login>&psw=<password>&user=<user>&id=<id>
або:
https://smsc.ua/sys/documents.php?get_account=1&login=<login>&psw=<password>&user_id=<user_id>&id=<id>
Для вивантаження існуючого акту субкліента необхідно викликати методом GET або POST адрес:
https://smsc.ua/sys/documents.php?get_act=1&login=<login>&psw=<password>&user=<user>&id=<id>
https://smsc.ua/sys/documents.php?get_act=1&login=<login>&psw=<password>&user_id=<user_id>&id=<id>
або:
https://smsc.ua/sys/documents.php?get_act=1&login=<login>&psw=<password>&user=<user>&num=<num>
https://smsc.ua/sys/documents.php?get_act=1&login=<login>&psw=<password>&user_id=<user_id>&num=<num>
Серверу передаються наступні параметри:
Параметр | Значення
|
---|
login | Логін Клієнта.
|
---|
psw | Пароль Клієнта (можна додати або редагувати на даннійсторінці).
|
---|
user | Логін субклієнта, для якого необхідно створити або вивантажити рахунок. Замість цього параметру можна використовувати параметр user_id.
|
---|
user_id | Ідентифікатор субклієнта, для якого необхідно створити або вивантажити рахунок. Замість цього параметра можна використовувати параметрuser.
|
---|
sum | Сума, на яку необхідно створити рахунок у валюті клієнта.
|
---|
service | Назва послуги, вказаної при створенні рахунку.
|
---|
id | Ідентифікатор запитуваного рахунку або акту.
|
---|
num | Номер запитуваного акту.
|
---|
У разі помилки Сервер повертає наступний рядок:
{
"error": "опис",
"error_code": N
} |
N – номер помилки, може приймати наступні значення:
Значення | Опис
|
---|
1 | Помилка в параметрах.
|
---|
2 | Невірний логін або пароль. Також виникає при спробі відправки повідомлення з IP-адреси, що не входить в список дозволених Клієнтом (якщо такий список був налаштований Клієнтом раніше).
|
---|
4 | IP-адреса тимчасово заблокована.
|
---|
5 | Помилка створення рахунку.
|
---|
6 | Сублогін не знайдено.
|
---|
7 | Зазначений документ не знайдено.
|
---|
9 | Спроба відправки більше одного запиту на створення або отримання рахунку або акту протягом хвилини.
Дана помилка виникає також при спробі відправки п'ятнадцяти і більше запитів одночасно з різних підключень під одним логіном (too many concurrent requests).
|
---|
У разі успішного запиту на створення рахунку Сервер повертає multipart-структуру, що включає в себе 2 частини з відповідними заголовками. Перша частина містить відповідь Сервера в json-форматі, що містить ідентифікатор і суму створеного рахунку, друга частина включає в себе файл із рахунком в pdf-форматі.
У разі успішного запиту на отримання рахунку Сервер повертає файл з рахунком в pdf-форматі.
У разі успішного запиту на отримання акту Сервер повертає файл з актом в pdf-форматі.
Сервер не приймає більше одного запиту на створення або зміна рахунку або акту протягом хвилини для зниження навантаження і захисту від помилок і зациклення в програмі на стороні Клієнта.
Перелік доступних операцій з іменами відправниківДля керування іменами відправників необхідно викликати методом GET або POST відповідну адресу із зазначенням
необхідної команди і параметрів.
Для отримання списку зареєстрованих в особистому кабінеті і допущених модератором імен відправників:
https://smsc.ua/sys/senders.php?get=1&login=<login>&psw=<password>
Щоб додати нове ім'я відправника:
https://smsc.ua/sys/senders.php?add=1&login=<login>&psw=<password>&sender=<sender>&cmt=<cmt>
Щоб змінити ім'я відправника:
https://smsc.ua/sys/senders.php?chg=1&login=<login>&psw=<password>&sender=<sender>&cmt=<cmt>
або
https://smsc.ua/sys/senders.php?chg=1&login=<login>&psw=<password>&id=<id>&cmt=<cmt>
Надсилання коду підтвердження для цифрового імені відправника:
https://smsc.ua/sys/senders.php?send_code=1&login=<login>&psw=<password>&sender=<sender>
Підтвердження цифрового імені відправника:
https://smsc.ua/sys/senders.php?check_code=1&login=<login>&psw=<password>&sender=<sender>&code=<code>
Щоб видалити ім'я відправника:
https://smsc.ua/sys/senders.php?del=1&login=<login>&psw=<password>&sender=<sender>
або
https://smsc.ua/sys/senders.php?del=1&login=<login>&psw=<password>&id=<id>
При додаванні або зміні імені відправника в тілі запиту можна передавати файл документа для операторів (свідоцтво на товарний знак, сертифікат на домен) у форматі jpg, TIF, pdf, png, zip, rar. Максимальний розмір переданого файлу не повинен перевищувати 3 Мб. Коментар до документа може бути вказаний в додатковому параметрі doc_info.
Опис параметрів
Опис параметрів, що передаються Серверу:
Параметр | Значення
|
---|
login | Логін Клієнта.
|
---|
psw | Пароль Клієнта (можна додати або редагувати на даннійсторінці).
|
---|
all | 0 (за замовчуванням) – отримати список активованих імен відправників.
1 – отримати повний список імен відправників.
|
---|
sender | Створюване або те, що видаляється, ім'я відправника.
|
---|
mts_step | 1 – зареєструвати платне ім'я у оператора MTS.
|
---|
sber_step | 1 – зареєструвати безкоштовне ім'я у оператора СберМобайл.
|
---|
tele2 | 1 – зареєструвати ім'я у оператора Tele2 за тарифом із безкоштовними іменами.
|
---|
motiv | 1 – зареєструвати ім'я у оператора МОТИВ за тарифом з безкоштовними іменами.
|
---|
mega_step | 1 – зареєструвати платне ім'я у оператора Мегафон.
|
---|
bee_step | 1 – зареєструвати платне ім'я у оператора Білайн.
|
---|
motiv_step | 1 – зареєструвати платне ім'я у оператора MOTIV.
|
---|
winmob_step | 1 – зареєструвати платне ім'я у оператора Win-Mobile.
|
---|
volnamob_step | 1 – зареєструвати платне ім'я у оператора хвиля мобайл.
|
---|
tele2_step | 1 – зареєструвати платне ім'я у оператора Tele2.
|
---|
ua_reg | 1 – зареєструвати ім'я для України на знижений тариф за національним трафіком.
Для даного тарифу необхідно додатково передати наступні параметри:
fio – Юридична назва організації (ТОВ / СПД).
inn – ЄДРПОУ / ІПН.
site – Адреса сайту або посилання на соц. мережа.
email – E-mail для зв'язку.
address – Фактична адреса.
desc – Опис послуг, що надаються відправником.
subj – Тема (мета інформування).
|
---|
ua_int | 1 – зареєструвати ім'я для України за більш високим тарифом для міжнародного трафіку. Для реєстрації також необхідно додатково передати поля, описані вище для параметра ua_reg.
|
---|
by_reg | 1 – зареєструвати ім'я для Білорусі на знижений тариф по національному трафіку.
Для даного тарифу необхідно додатково передати наступні параметри:
by_fio – Назва компанії.
by_inn – УНП / ІПН.
by_address – Адреса компанії.
by_ocup - Сфера діяльності (варіанти можна уточнити на даний сторінка). Нумерація від 1 до 19.
by_type - Тип розсилки (варіанти можна уточнити на даний сторінка). Нумерація від 1 до 3.
by_mes – Приклад повідомлення.
by_site – Адреса сайту.
|
---|
by_int | 1 – зареєструвати ім'я для Білорусі за більш високим тарифом для міжнародного трафіку. Для реєстрації також необхідно додатково передати поля, описані вище для параметра by_reg.
|
---|
id | Ідентифікатор імені відправника, який призначається Сервером
автоматично при створенні нового імені.
|
---|
cmt | Коментар, що вказується при створенні імені відправника.
|
---|
mail | 1 – додати e-mail адресу відправника.
|
---|
name | Коментар, пов'язаний із параметромmail (зазвичай ім'я власника e-mail адреси).
|
---|
code | Код для підтвердження цифрового імені відправника.
|
---|
site | Адреса сайту, від якого будуть приходити коди для підтвердження цифрових
імен відправників. Даний параметр повинен бути раніше доданий і активований в якості
Sender ID. Якщо не вказане, то повідомлення будуть приходити від імені відправника
за замовчуванням.
|
---|
site_name | Адреса сайту, що вказується в тексті повідомлення з кодом підтвердження.
|
---|
user | Логін субклієнта, до якої застосовується вказана команда.
|
---|
operators | 1 – додати у відповідь код статусу імені відправника у оператора.
|
---|
from_date | Вибрати імена відправників починаючи із зазначеної дати, для яких був змінений статус імені у будь-якого з операторів.
При вказівці даного параметра відбувається сортування імен у порядку убування дати зміни статусів імен. Формат DD.MM.YYYY.
|
---|
prev_id | Унікальний ідентифікатор імені відправника, який призначається сервером автоматично при створенні імені. Використовується для запиту списку імен, створених до імені із зазначеним ідентифікатором.
|
---|
cnt | Кількість імен відправників, що повертаються при запиті списку імен. Максимальне значення становить 15000.
|
---|
doc_info | Якщо при створенні або зміні імені відправника в тілі запиту буде переданий файл документа для операторів, то в даному параметрі можна вказати опис до переданого файлу.
|
---|
charset | Кодування параметрів, що передаються.
|
---|
files | 1 – повернути у відповіді сервера для команди get масив files, що містить інформацію про прикріплені файли документів для операторів. Параметр актуальний тільки для форматів fmt=2 або fmt=3.
Масив включає наступні поля:
file – Назва файлу.
fid – Ідентифікатор файлу в системі.
fstatus – Статус файлу (0 - на перевірці, 1 - відхилено, 2-допущено).
fcomment – Коментар адміністратора.
|
---|
Відповідь сервера і коди помилок
У разі помилки Сервер повертає наступний рядок:
- 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 | Ім'я відправника не знайдене.
|
---|
4 | IP-адреса тимчасово заблокована.
|
---|
5 | Помилка збереження або видалення імені відправника.
|
---|
7 | Неправильний формат номеру.
|
---|
8 | Код підтвердження на вказаний номер не може бути доставлений.
|
---|
9 | Спроба відправки більше трьох однакових запитів на отримання списку доступних імен відправників
або п'яти запитів на створення нового імені відправника протягом хвилини.
Дана помилка виникає також при спробі відправки п'ятнадцяти і більше запитів одночасно з різних підключень під одним логіном (too many concurrent requests).
|
---|
10 | Код вже був відправлений на вказаний номер. Повторна спроба можлива через 8 годин.
|
---|
11 | Невірний код підтвердження.
|
---|
У разі успішного запиту Сервер повертає відповідь у вигляді рядка.
При запиті списку імен відправників:
- при fmt = 0 та all = 0:
name = <sender>, id = <id>
... |
- при fmt = 1 та all = 0:
- при fmt = 2 та all = 0:
<list>
<sender id="<id>">sender</sender>
...
</list>
|
- при fmt = 3 та all = 0:
[{
"sender": "<sender>",
"id": <id>
},
...] |
- при fmt = 0 та all = 1:
name = <sender>, status = <status>, id = <id>
... |
- при fmt = 1 та all = 1:
<sender>,<status>,<id>
... |
- при fmt = 2 та all = 1:
<list>
<sender status="<status>" id="<id>">sender</sender>
...
</list>
|
- при fmt = 3 та all = 1:
[{
"sender": "<sender>",
"status": <status>,
"id": <id>
},
...] |
- при fmt = 0 и operators = 1:
name = <sender>, mega_step = <mega_step_status>, bee_step = <bee_step_status>, motiv_step = <motiv_step_status>, sber_step = <sber_step_status>, winmob_step = <winmob_step>, volnamob_step = <volnamob_step>, mts_step = <mts_step_status>, tele2_step = <tele2_step_status>, tele2 = <tele2_status>, ua_reg = <ua_reg_status>, ua_int = <ua_int_status>, mega_int = <mega_int_status>, motiv_int = <motiv_int_status>, mts_int = <mts_int_status>, motiv = <motiv_status>, by_reg = <by_reg_status>, by_int = <by_int_status>, tele2_int = <tele2_int_status>, sber_int = <sber_int_status>, id = <id>
... |
- при fmt = 2 и operators = 1:
<list>
<sender mega_step="<mega_step_status>" bee_step="<bee_step_status>" motiv_step="<motiv_step_status>" sber_step="<sber_step_status>" winmob_step="<winmob_step_status>" volnamob_step="<volnamob_step_status>" mts_step="<mts_step_status>" tele2_step="<tele2_step_status>" tele2="<tele2_status>" ua_reg="<ua_reg_status>" ua_int="<ua_int_status>" mega_int="<mega_int_status>" motiv_int="<motiv_int_status>" mts_int="<mts_int_status>" motiv="<motiv_status>" by_reg="<by_reg_status>" by_int="<by_int_status>" tele2_int="<tele2_int_status>" sber_int="<sber_int_status>" id="<id>">sender</sender>
...
</list>
|
- при fmt = 3 и operators = 1:
[{
"sender": "<sender>",
"mega_step": "<mega_step_status>",
"mega_int": "<mega_int_status>",
"bee_step": "<bee_step_status>",
"motiv": "<motiv_status>",
"motiv_step": "<motiv_step_status>",
"motiv_int": "<motiv_int_status>",
"sber_step": "<sber_step_status>",
"sber_int": "<sber_int_status>",
"winmob_step": "<winmob_step_status>",
"volnamob_step": "<volnamob_step_status>",
"mts_step": "<mts_step_status>",
"mts_int": "<mts_int_status>",
"tele2_step": "<tele2_step_status>",
"tele2": "<tele2_status>",
"tele2_int": "<tele2_int_status>",
"ua_reg": "<ua_reg_status>",
"ua_int": "<ua_int_status>",
"by_reg": "<by_reg_status>",
"by_int": "<by_int_status>",
"id": "<id>"
},
...] |
Де:
<sender> – зареєстроване та допущене до використання ім'я відправника.
<mega_step_status>, <mega_int_status>, <bee_step_status>, <motiv_status>, <motiv_step_status>, <motiv_int_status>, <sber_step_status>, <sber_int_status>, <winmob_step_status>, <volnamob_step_status>, <mts_step_status>, <mts_int_status>, <tele2_step_status>, <tele2_status>, <tele2_int_status>, <ua_reg_status>, <ua_int_status>, <by_reg_status>, <by_int_status> - код статусу імені відправника у відповідного оператора (0-очікує реєстрації, 1-відправлено на реєстрацію, 2-допущено оператором, 3-не прийнято оператором, 4-тимчасово відключено, 5-недостатньо коштів на рахунку, 8-необхідні підтверджуючі документи, 9-активація з початку місяця), 255-допущено, але позначено на зняття з реєстрації).
<status> – статус імені відправника (0 - очікує модерації, 1 - допущене до використання, 2 - вимкнене).
<id> – унікальний ідентифікатор імені відправника (призначається Сервером автоматично при створенні імені).
Якщо для будь-якого оператора ім'я відправника має замінюючий аналог, то при operators = 1 и fmt = 0,2,3 у відповідь сервера додатково буде включена дана заміна.
При додаванні нового імені відправника:
- при fmt = 0: ID = <id>
- при fmt = 1: <id>
- при fmt = 2:
<sender>
<id>id</id>
</sender>
|
- при fmt = 3:
Де:
<id> – ідентифікатор імені відправника, призначений Сервером автоматично.
При зміні імені відправника, відправці коду, підтвердженні та видаленні імені відправника:
- при fmt = 0, 1: OK
- при fmt = 2:
<result>OK</result>
- при fmt = 3:
Приклади дій з іменами відправниківПриклади:
Отримання списку імен відправників:
https://smsc.ua/sys/senders.php?get=1&login=alex&psw=123
Додавання нового імені відправника:
https://smsc.ua/sys/senders.php?add=1&login=alex&psw=123&sender=my_shop&cmt=test
Надсилання коду підтвердження для цифрового імені відправника:
https://smsc.ua/sys/senders.php?send_code=1&login=alex&psw=123&sender=79999999999
Відправка коду підтвердження цифрового імені відправника для субклієнта "subalex" від імені "mysite.ru":
https://smsc.ua/sys/senders.php?send_code=1&login=alex&psw=123&sender=79999999999&user=subalex&site=mysite.ru
Підтвердження цифрового імені відправника:
https://smsc.ua/sys/senders.php?check_code=1&login=alex&psw=123&sender=79999999999&code=338824
Видалення імені відправника:
https://smsc.ua/sys/senders.php?del=1&login=alex&psw=123&sender=my_shop
Сервер не приймає більше трьох однакових запитів протягом хвилини на отримання списку доступних імен
відправників і п'яти запитів на створення нового імені відправника для зниження навантаження і захисту від помилок і зациклень
у програмі на стороні клієнта.
Отримання історії відправлених повідомленьДля отримання списку відправлених SMS-повідомлень необхідно викликати методом GET або POST адресу:
https://smsc.ua/sys/get.php?get_messages=1&login=<login>&psw=<password>
Опис параметрів, що передаються Серверу:
Параметр | Значення
|
---|
login | Логін Клієнта.
|
---|
psw | Пароль Клієнта (можна додати або редагувати на даннійсторінці).
|
---|
start | Початкова дата в періоді, за який запитується історія. Формат: 'дд.мм. рррр'. Максимальний період, за який можливий запит історії
відправлених повідомлень, становить півроку.
|
---|
end | Кінцева дата в періоді. Якщо не вказана, то повертаються дані з початкової дати. Формат: 'дд.мм. рррр'.
|
---|
phone | Номер або розділений комами список номерів телефонів, для яких необхідно отримати
історію відправлених SMS-повідомлень.
|
---|
email | E-mail адреса або розділений комами список адрес, для яких необхідно отримати
історію відправлених e-mail повідомлень.
|
---|
format | Ознака запиту e-mail повідомлень.
0 (за замовчуванням) – запит SMS-повідомлень. 8 – запит e-mail повідомлень.
|
---|
cnt | Кількість повідомлень, що повертаються у відповіді. Максимальне значення становить 1000.
|
---|
prev_id | Глобальний ідентифікатор повідомлення (параметр int_id у відповіді Сервера), який призначається сервером автоматично. Використовується для запиту списку повідомлень, відправлених до повідомлення із вказаним ідентифікатором.
|
---|
fmt | Формат відповіді Сервера.
0 – (за замовчуванням) у вигляді рядка (докладніше можна ознайомитися в описі нижче).
1 – повернути відповідь у вигляді параметрів через кому.
2 – відповідь у xml форматі.
3 – відповідь у json форматі.
|
---|
У разі помилки Сервер повертає наступний рядок:
- 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 | Повідомлення не знайдене.
|
---|
4 | IP-адреса тимчасово заблокована.
|
---|
9 | Спроба відправки більше трьох однакових запитів на отримання історії вихідних повідомлень протягом хвилини або більше тридцяти запитів протягом години.
Дана помилка виникає також при спробі відправки п'ятнадцяти і більше запитів одночасно з різних підключень під одним логіном (too many concurrent requests).
|
---|
У разі успішного запиту Сервер повертає відповідь у вигляді рядка:
- при fmt = 0:
Status = <status>, check_time = <last_date>, err = <err>, send_date = <send_date>, phone = <phone>,
mccmnc = <mccmnc>, country = <country>, operator = <operator>, region = <region>, cost = <cost>, sender_id = <sender>,
status_name = <status_name>, message = <message>, type = <type>, ID = <id>, int_id = <int_id>, sms_cnt = <sms_cnt>,
format = <format>, crc = <crc>
... |
- при fmt = 1:
<status>,<last_timestamp>,<err>,<send_timestamp>,<phone>,<mccmnc>,<country>,<operator>,<region>,<cost>,<sender>,<status_name>,
<message>,<type>,<id>,<int_id>,<sms_cnt>,<format>,<crc>
... |
- при fmt = 2:
<list>
<sms>
<status>status</status>
<last_date>last_date</last_date>
<last_timestamp>last_timestamp</last_timestamp>
<err>err</err>
<send_date>send_date</send_date>
<send_timestamp>send_timestamp</send_timestamp>
<phone>phone</phone>
<cost>cost</cost>
<sender_id>sender</sender_id>
<status_name>status_name</status_name>
<message>message</message>
<mccmnc>mccmnc</mccmnc>
<country>country</country>
<operator>operator</operator>
<region>region</region>
<type>type</type>
<id>id</id>
<int_id>int_id</int_id>
<sms_cnt>sms_cnt</sms_cnt>
<format>format</format>
<crc>crc</crc>
</sms>
...
</list>
|
- при fmt = 3:
[{
"status": <status>,
"last_date": "<last_date>",
"last_timestamp": <last_timestamp>,
"err": <err>,
"send_date": "<send_date>",
"send_timestamp": <send_timestamp>,
"phone": "<phone>",
"cost": "<cost>",
"sender_id": "<sender>",
"status_name": "<status_name>",
"message": "<message>",
"mccmnc": "<mccmnc>",
"country": "<country>",
"operator": "<operator>",
"region": "<region>",
"type": <type>,
"id": <id>,
"int_id": "<int_id>",
"sms_cnt": <sms_cnt>,
"format": <format>,
"crc": <crc>
...] |
Де:
<status> – код статусу (список)
<last_date> – дата останньої зміни статусу. Формат DD.MM.YYYY HH:mm: ss.
<last_timestamp> – штамп часу останньої зміни статусу.
<err> – код помилки, якщо повідомлення не було доставлене.
<send_date> – дата відправки повідомлення (формат DD.MM.YYYY hh:mm:ss).
<send_timestamp> – штамп часу відправки повідомлення.
<phone> – номер телефону абонента.
<country> – назва країни реєстрації номера абонента.
<operator> – назва оператора абонента.
<region> – регіон реєстрації номера абонента.
<type> - тип повідомлення.
<cost> – вартість повідомлення.
<sender> – ім'я відправника.
<status_name> – назва статусу.
<message> – текст повідомлення.
<mccmnc> – мобільний код країни і мобільний код оператора.
<id> – ідентифікатор повідомлення.
<int_id> – глобальний ідентифікатор повідомлення.
<sms_cnt> – кількість частин в повідомленні.
<format> – формат повідомлення.
<crc> – контрольна сума повідомлення.
Приклади:
Отримання останніх десяти вихідних SMS-повідомлень:
https://smsc.ua/sys/get.php?get_messages=1&login=alex&psw=123&cnt=10
Отримання останнього вихідного SMS-повідомлення, відправленого на номер "79999999999":
https://smsc.ua/sys/get.php?get_messages=1&login=alex&psw=123&phone=79999999999
Сервер не приймає більше трьох однакових запитів протягом хвилини або тридцяти запитів протягом години на отримання історії вихідних
повідомлень для зниження навантаження і захисту від помилок і зациклення в програмі на стороні Клієнта.
Отримання вхідних повідомлень
Для отримання списку вхідних повідомлень необхідно викликати методом GET або POST адреси:
https://smsc.ua/sys/get.php?get_answers=1&login=<login>&psw=<password>
Опис параметрів, що передаються Серверу:
Параметр | Значення
|
---|
login | Логін Клієнта.
|
---|
psw | Пароль Клієнта (можна додати або редагувати на даннійсторінці).
|
---|
cnt | Кількість повідомлень, що повертаються у відповіді. Максимальне значення становить 10000.
|
---|
hour | Період в годинах, за який необхідно запросити вхідні повідомлення. Максимальна кількість годин - 168 (7 днів).
|
---|
after_id | Ідентифікатор повідомлення, починаючи з якого необхідно повернути вхідні повідомлення, за винятком самого
after_id.
|
---|
to_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-адреси, що не входить в список дозволених Клієнтом (якщо такий список був налаштований Клієнтом раніше).
|
---|
4 | IP-адреса тимчасово заблокована.
|
---|
9 | Спроба відправки більше трьох однакових запитів на отримання списку вхідних повідомлень протягом хвилини.
Дана помилка виникає також при спробі відправки п'ятнадцяти і більше запитів одночасно з різних підключень під одним логіном (too many concurrent requests).
|
---|
У разі успішного запиту Сервер повертає відповідь у вигляді рядка:
- при fmt = 0:
id = <id>, received = <received>, phone = <phone>, message = <message>, to_phone = <to_phone>, sent = <sent>
... |
- при fmt = 1:
<id>,<received>,<phone>,<to_phone>,<sent>,<message>
... |
- при fmt = 2:
<sms_answers>
<sms>
<id>id</id>
<received>received</received>
<phone>phone</phone>
<message>message</message>
<to_phone>to_phone</to_phone>
<sent>sent</sent>
</sms>
...
</sms_answers>
|
- при fmt = 3:
[{
"id": <id>,
"received": "<received>",
"phone": "<phone>",
"message": "<message>",
"to_phone": "<to_phone>",
"sent": "<sent>"
},
...] |
Де:
<id> – ідентифікатор вхідного повідомлення, що призначається Сервером автоматично.
<received> – дата отримання повідомлення Сервером. Формат DD.MM.YYYY HH:mm: ss.
<phone> – номер телефону абонента.
<message> – вхідне повідомлення.
<to_phone> – номер телефону одержувача.
<sent> – дата відправки повідомлення. Формат DD.MM.YYYY hh:mm:ss.
Приклади:
Отримання списку з 10 перших вхідних повідомлень за поточну добу:
https://smsc.ua/sys/get.php?get_answers=1&login=alex&psw=123&cnt=10
Отримання списку з 15 перших вхідних повідомлень за останні 48 годин:
https://smsc.ua/sys/get.php?get_answers=1&login=alex&psw=123&hour=48&cnt=15
Отримання списку з 20 перших вхідних повідомлень з ідентифікаторами, великими id="1234567":
https://smsc.ua/sys/get.php?get_answers=1&login=alex&psw=123&after_id=1234567&cnt=20
Сервер не приймає більше трьох однакових запитів протягом хвилини на отримання списку вхідних
повідомлень для зниження навантаження і захисту від помилок і зациклень в програмі на стороні клієнта.
Отримання статистикиДля отримання статистики відправлених повідомлень необхідно викликати методом GET або POST адресу:
https://smsc.ua/sys/get.php?get_stat=1&login=<login>&psw=<password>&start=<date1>&end=<date2>
Опис параметрів, що передаються Серверу:
Параметр | Значення
|
---|
login | Логін Клієнта.
|
---|
psw | Пароль Клієнта (можна додати або редагувати на даннійсторінці).
|
---|
start | Початкова дата в періоді, за який запитується статистика. Формат: 'дд.мм. рррр'.
|
---|
end | Кінцева дата в періоді. Якщо не вказана, то повертаються дані з початкової дати. Формат: 'дд.мм. рррр'.
|
---|
mycur | Прапор, що дозволяє виводити статистику в поточній валюті клієнта.
|
---|
balance2 | Прапор, що дозволяє отримати статистику по відправленим повідомленням, оплаченим з електронного балансу.
|
---|
У разі помилки Сервер повертає наступний рядок:
- 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-адреси, що не входить в список дозволених Клієнтом (якщо такий список був налаштований Клієнтом раніше).
|
---|
4 | IP-адреса тимчасово заблокована.
|
---|
9 | Спроба відправки більше трьох однакових запитів на отримання списку вхідних повідомлень протягом хвилини.
Дана помилка виникає також при спробі відправки п'ятнадцяти і більше запитів одночасно з різних підключень під одним логіном (too many concurrent requests).
|
---|
У разі успішного запиту Сервер повертає відповідь у вигляді рядка:
- при fmt = 0:
login = <login>, sms = <cnt>, credit = <credit>, debit = <debit>, currency = <currency>
... |
- при fmt = 1:
<login>,<cnt>,<credit>,<debit>,<currency>
... |
- при fmt = 2:
<list>
<stat>
<login>login</login>
<sms>cnt</sms>
<credit>credit</credit>
<debit>debit</debit>
<currency>currency</currency>
</stat>
...
</list> |
- при fmt = 3:
[{
"login": "<login>",
"sms": "<cnt>",
"credit": "<credit>",
"debit": "<debit>",
"currency": "<currency>"
},
...] |
Де:
<login> - логін Клієнта.
<cnt> - кількість повідомлень.
<credit> - витрати.
<debit> - надходження.
<currency> - трисимвольний код валюти.
Приклади:
Отримання статистики в поточній валюті Клієнта з "01.01.2014" по "01.02.2014" за безготівковим балансом:
https://smsc.ua/sys/get.php?get_stat=1&login=alex&psw=123&mycur=1&start=01.01.2014&end=01.02.2014
Сервер не приймає більше трьох запитів протягом хвилини на отримання статистики для зниження
навантаження і захисту від помилок і зациклень в програмі на стороні клієнта.
Запит тарифівДля отримання списку тарифів зазначеного клієнта необхідно викликати методом GET або POST адреси:
https://smsc.ua/sys/get.php?get_price=1&login=<login>&psw=<password>
Опис параметрів, що передаються Серверу:
Параметр | Значення
|
---|
login | Логін Клієнта.
|
---|
psw | Пароль Клієнта (можна додати або редагувати на даннійсторінці).
|
---|
У разі помилки Сервер повертає наступний рядок:
- 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-адреси, що не входить в список дозволених Клієнтом (якщо такий список був налаштований Клієнтом раніше).
|
---|
4 | IP-адреса тимчасово заблокована.
|
---|
9 | Спроба відправки більше трьох однакових запитів на отримання списку тарифів протягом хвилини.
Дана помилка виникає також при спробі відправки п'ятнадцяти і більше запитів одночасно з різних підключень під одним логіном (too many concurrent requests).
|
---|
У разі успішного запиту Сервер повертає відповідь у вигляді набору рядків:
- при fmt = 0:
zone = <zone>, name = <name>, api = <api>, mass = <mass>, mms = <mms>, hlr = <hlr>, call = <call>
...
|
при наявності встановлених індивідуальних тарифів за певними операторами до відповіді додається набір рядків:
mccmnc = <mccmnc>, cost = <cost>
...
mail = <mail>
|
- при fmt = 1:
<zone>,<name>,<api>,<mass>,<mms>,<hlr>,<call>
...
<mccmnc>,<cost>
...
<mail>
|
- при fmt = 2:
<price>
<zones>
<zone name="<name>" api="<api>" mass="<mass>" mms="<mms>" hlr="<hlr>" call="<call>">zone</zone>
...
</zones>
<codes>
<mccmnc cost="<cost>">mccmnc</mccmnc>
...
</codes>
<mail>mail</mail>
</price> |
- при fmt = 3:
{
"zones": [{
"zone": "<zone>",
"name": "<name>",
"api": "<api>",
"mass": "<mass>",
"mms": "<mms>",
"hlr": "<hlr>",
"call": "<call>"
},
...
{
...
}],
"codes": [{
"mccmnc": "<mccmnc>",
"cost": "<cost>"
},
...
{
...
}],
"mail": "<mail>"
}
|
Де:
<zone> - тарифна зона.
<name> - назва тарифної зони (оператор, країна тощо.).
<api> - вартість SMS при відправці через API.
<mass> - вартість SMS при відправці через Особистий кабінет.
<mms> - вартість MMS-повідомлення.
<hlr> - вартість HLR-запиту.
<call> - вартість голосового повідомлення (дзвінок).
<mccmnc> - код країни і мобільного оператора, для якого встановлено індивідуальний тариф.
<cost> - вартість повідомлення за даним індивідуальним тарифом.
<mail> - вартість e-mail повідомлення.
Приклади:
Отримання списку тарифів:
https://smsc.ua/sys/get.php?get_price=1&login=alex&psw=123
Сервер не приймає більше трьох однакових запитів протягом хвилини на отримання списку тарифів для
зниження навантаження і захисту від помилок і зациклень в програмі на стороні клієнта.
Отримання інформації про оператораДля отримання інформації про оператора абонента необхідно викликати методом GET або POST адресу:
https://smsc.ua/sys/info.php?get_operator=1&login=<login>&psw=<password>&phone=<phone>
Опис параметрів, що передаються Серверу:
Параметр | Значення
|
---|
login | Логін Клієнта.
|
---|
psw | Пароль Клієнта (можна додати або редагувати на даннійсторінці).
|
---|
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 | Оператор не знайдений.
|
---|
4 | IP-адреса тимчасово заблокована.
|
---|
9 | Спроба відправки більше трьох однакових запитів або будь-яких 100 запитів на отримання
інформації про оператора абонента протягом хвилини.
Дана помилка виникає також при спробі відправки п'ятнадцяти і більше запитів одночасно з різних підключень під одним логіном (too many concurrent requests).
|
---|
При успішному запиті Сервер повертає відповідь у вигляді рядка або списку рядків при множиному запиті (у цьому випадку у відповідь
Сервера додається параметр "phone"):
- при fmt = 0: country = <country>, operator = <operator>, region = <region>, mcc = <mcc>, mnc = <mnc>, tz = <tz>
- при fmt = 1: <country>,<operator>,<region>,<mcc>,<mnc>,<tz>
- при fmt = 2:
<info>
<country>country</country>
<operator>operator</operator>
<region>region</region>
<mcc>mcc</mcc>
<mnc>mnc</mnc>
<tz>tz</tz>
</info>
|
При множинному запиті конструкції <info> заключаються в тег <list>.
- при fmt = 3:
{
"country": "<country>",
"operator": "<operator>",
"region": "<region>",
"mcc": "<mcc>",
"mnc": "<mnc>",
"tz": "<tz>"
} |
Де:
<phone> – номер телефону абонента.
<country> – назва країни реєстрації номера абонента.
<operator> – мобільний оператор абонента.
<region> – регіон реєстрації номера абонента.
<mcc> – числовий код країни абонента.
<mnc> – числовий код оператора абонента.
<tz> – часовий пояс регіону реєстрації номера абонента.
Приклад:
Отримання інформації про оператора абонента з номером "79999999999":
https://smsc.ua/sys/info.php?get_operator=1&login=alex&psw=123&phone=79999999999
Сервер не приймає більше трьох однакових запитів протягом хвилини на отримання інформації
про оператора абонента для зниження навантаження і захисту від помилок і зациклень в програмі на стороні клієнта.
Сервер також блокує відправку більше 100 запитів протягом хвилини на отримання даних про оператора для зниження
навантаження на базу даних.
Отримання даних о короткому посиланніДля отримання інформації про короткі посилання необхідно викликати методом GET або POST адреса:
https://smsc.ua/sys/tinyurls.php?get=1&login=<login>&psw=<password>&link=<link>
або
https://smsc.ua/sys/tinyurls.php?get=1&login=<login>&psw=<password>&id=<id>
Опис параметрів, що передаються Серверу:
Параметр | Значення
|
---|
login | Логін Клієнта.
|
---|
psw | Пароль Клієнта (можна додати або редагувати на даннійсторінці).
|
---|
link | Вихідне повне посилання.
|
---|
id | Ідентифікатор короткого посилання. Призначається автоматично при створенні.
|
---|
Всі параметри, які містять спеціальні символи (плюс, пробіл, символи кирилиці і т. д.), повинні бути закодовані за допомогою функції urlencode для передачі в HTTP-запиті.
У разі помилки Сервер повертає наступний рядок:
- 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 | Посилання не знайдено.
|
---|
4 | IP-адреса тимчасово заблокована.
|
---|
9 | Спроба відправки більше трьох однакових запитів на отримання
інформації про коротке посилання протягом хвилини.
Дана помилка виникає також при спробі відправки п'ятнадцяти і більше запитів одночасно з різних підключень під одним логіном (too many concurrent requests).
|
---|
У разі успішного запиту Сервер повертає відповідь у вигляді рядка:
- при fmt = 0: id = <id>, cnt = <cnt>, cnt_mon = <cnt_mon>, cnt_day = <cnt_day>, cnt_yes = <cnt_yes>, cnt_pmon = <cnt_pmon>, link = <link>
- при fmt = 1: <id>,<cnt>,<cnt_mon>,<cnt_day>,<cnt_yes>,<cnt_pmon>,<link>
- при fmt = 2:
<result>
<id>id</id>
<cnt>cnt</cnt>
<cnt_mon>cnt_mon</cnt_mon>
<cnt_day>cnt_day</cnt_day>
<cnt_yes>cnt_yes</cnt_yes>
<cnt_pmon>cnt_pmon</cnt_pmon>
<link>link</link>
</result>
|
- при fmt = 3:
{
"id": "<id>",
"cnt": "<cnt>",
"cnt_mon": "<cnt_mon>",
"cnt_day": "<cnt_day>",
"cnt_yes": "<cnt_yes>",
"cnt_pmon": "<cnt_pmon>",
"link": "<link>"
} |
Де:
<id> – ідентифікатор короткого посилання.
<cnt> – кількість всіх переходів за коротким посиланням.
<cnt_mon> – кількість переходів за коротким посиланням за місяць.
<cnt_day> – кількість переходів за коротким посиланням за сьогодні.
<cnt_yes> – кількість переходів за коротким посиланням за вчора.
<cnt_pmon> – кількість переходів за коротким посиланням в попередньому місяці.
<link> – коротке посилання.
Приклад:
Отримання інформації про коротке посилання з id="145142":
https://smsc.ua/sys/tinyurls.php?get=1&login=alex&psw=123&id=145142
Отримання інформації про коротке посилання за повним вихідним посиланням "mywebsite.ru":
https://smsc.ua/sys/tinyurls.php?get=1&login=alex&psw=123&link=mywebsite.ru
Сервер не приймає більше трьох однакових запитів протягом хвилини на отримання інформації
про коротке посилання для зниження навантаження і захисту від помилок і зациклення в програмі на стороні Клієнта.
Підключення виділених номерів для прийому повідомленьВи можете через спеціальні команди 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 | Пароль Клієнта (можна додати або редагувати на даннійсторінці).
|
---|
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 | Недостатньо коштів на рахунку для оренди номеру.
|
---|
4 | IP-адреса тимчасово заблокована.
|
---|
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> – сума, списана з рахунку Клієнта за оренду номера.
Для зміни ознаки продовження номера:
- при fmt = 0,1: OK
- при fmt = 2:
<result>OK</result>
- при fmt = 3:
Приклади:
Отримання списку вільних номерів для оренди:
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¶m2?param3¶m4 " параметри 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".
|
---|
md5 | MD5-хеш строки "id:phone:status:<секретная строка>". Передається, якщо був указаний в якості додаткового параметра
в http(s)-адресі обробника.
|
---|
sha1 | sha1-хеш строки "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 | Вхідний номер телефону, на який було відправлено повідомлення абонентом.
|
---|
smsc | SMS-центр оператора, від якого було отримано вхідне повідомлення.
|
---|
sent | Час відправки повідомлення абонентом у вигляді штампа в секундах.
|
---|
time | Час отримання повідомлення Сервером у вигляді штампу в секундах.
|
---|
md5 | MD5-хеш строки "phone:mes:to:<секретная строка>". Передається, якщо був указаний в якості додаткового параметра
в http(s)-адресі обробника.
|
---|
sha1 | sha1-хеш строки "phone:mes:to:<секретная строка>". Передається, якщо був указаний в якості додаткового параметра
в http(s)-адресі обробника.
|
---|
crc32 | Контрольная сумма crc32 строки "phone:mes:to:<секретная строка>". Передається, якщо був указаний в якості додаткового параметра
в http(s)-адресі обробника.
|
---|
Передані параметри при використанні послуги "Підтвердження номеру за допомогою дзвінка":
Параметр | Значення
|
---|
waitcall | 1 – ознака службового повідомлення для послуги "Підтвердження номеру за допомогою дзвінка".
|
---|
phone | Номер телефону абонента, з якого надійшов дзвінок.
|
---|
ts | Час дзвінка.
|
---|
md5 | MD5-хеш строки "phone:ts:<секретная строка>". Передається, якщо був указаний в якості додаткового параметра
в http(s)-адресі обробника.
|
---|
sha1 | sha1-хеш строки "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 | Пароль Клієнта (можна додати або редагувати на даннійсторінці).
|
---|
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 | Недостатньо коштів на рахунку клієнта.
|
---|
4 | IP-адреса тимчасово заблокована.
|
---|
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]"
і відправить на обробник Клієнта всю необхідну інформацію про даний дзвінок.
Сервер не приймає понад п'ятдесят однакових запитів на отримання номеру телефону для підтвердження протягом хвилини для зниження навантаження і захисту від помилок і зациклення в програмі на стороні Клієнта.
|