| 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
Опис параметрів, що передаються Серверу :
Параметр | Значення
|
---|
login | Логін Клієнта.
|
---|
psw | Пароль Клієнта (можна додати або редагувати на даннійсторінці).
|
---|
phones | Номер або розділений комами або крапками з комами список номерів мобільних телефонів в міжнародному форматі,
на які відправляється повідомлення. Номери можуть передаватися без знака "+".
Якщо номер переданий без знака "+", то він може бути виправлений автоматичним форматуванням
і приведено до належного міжнародного формату. Таким чином, деякі
помилки при введенні номерів телефонів можуть бути виправлені автоматично.
Для відключення автоматичного виправлення передайте номер зі знаком "+".
Також можна відправляти повідомлення на групу номерів, вказавши спеціальний код "G<номер группы>".
Повідомлення буде відправлено на всі номери, що належать даній групі. E-mail повідомлення передається список e-mail адрес
одержувачів.
|
---|
mes | Текст повідомлення, що надсилається. Максимальний розмір – 1000 символів. Повідомлення
необхідності буде розбито на кілька SMS, відправлених абоненту та оплачені окремо. Розмір одного
SMS – 160 символів у латиниці або 70 символів у кирилиці. При розбивці повідомлення на кілька SMS на кожну частину
додається заголовок для об'єднання частин в одне повідомлення на телефоні одержувача, і максимальна довжина стає
67 для кирилиці і 153 для латинських літер. У текст повідомлення можна додавати коментарі
призначені для перегляду відправником історії у особистому кабінеті.
|
---|
Додаткові параметри
|
---|
id | Ідентифікатор повідомлення. Призначається Клієнтом. Служить для подальшої ідентифікації повідомлення. Якщо не вказувати, то буде призначений автоматично. Не обов'язково унікальний. Ідентифікатор представляє собою 32-бітове число в діапазоні від до 1 2147483647, або рядок довжиною до 40 символів, що складається з латинських букв, цифр і символів ".-_".
|
---|
sender | Ім'я відправника, який відображається в телефоні одержувача.
Можна англійські літери, цифри, пробіл і деякі символи. Довжина – 11 символів або 15 цифр.
Всі імена реєструються в особистому кабінеті на сторінки.
|
---|
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-повідомлення. Буде відправлено sms на кожен номер телефону в списку.
|
---|
mail | Ознака e-mail повідомлення. Файли, що прикріплюються до повідомлення, передаються методом POST в тілі http-запиту.
0 (за замовчуванням) – звичайне повідомлення. 1 – e-mail повідомлення.
|
---|
soc | Ознака soc-повідомлення, що відправляється користувачам соціальних мереж "Однокласники", "ВКонтакте" або користувачам "Mail.Ru Агент".
0 (за замовчуванням) – звичайне повідомлення. 1 – soc-повідомлення.
|
---|
viber | Ознака viber-повідомлення, що надсилається користувачам месенджера Viber.
|
---|
fileurl | Повний http-адреса файлу для завантаження та передачі в повідомленні.
|
---|
call | Ознака голосового повідомлення. При формуванні голосового повідомлення можна передавати як текст, так і прикріплювати файли.
Файли, що додаються до повідомлення повинні передаватися методом POST в тілі http-запиту.
0 (за замовчуванням) – звичайне повідомлення. 1 – голосове повідомлення.
|
---|
voice | Голос, який використовується для озвучування тексту (тільки для голосових повідомлень).
m (за замовчуванням) – чоловічий голос. m2 – чоловічий альтернативний голос. w – жіночий голос. w2 – жіночий альтернативний голос.
|
---|
param | Розділений комами список параметрів для голосового повідомлення у форматі "param=w,i,n".
Тут:
- w – час очікування підняття трубки абонентом після початку дзвінка в секундах. Якщо протягом зазначеного часу абонент не підніме трубку,
то дзвінок піде на повтор з помилкою "абонент зайнятий". Робочий діапазон значень параметра від 10 до 35, але можна вказувати інтервал від 0 до 99
(у разі, якщо значення менше 10, то воно буде приведене до 10, аналогічно для верхньої межі).
- i – інтервал повтору, тобто проміжок часу, після закінчення якого відбудеться повторний дзвінок (у секундах). Робочий діапазон параметра
від 10 до 3600 (у разі, якщо значення менше 10, то воно буде приведене до 10).
- n – загальна кількість спроб дозвону. Робочий діапазон значень від 1 до 9 (0 буде приведений до 1).
При вказівці значення будь-якого параметра, відмінного від можливих, будуть використані значення всіх параметрів за замовчуванням (n = 8, w = 25, i від 3 до 14 секунд по наростаючій).
|
---|
subj | Тема MMS або e-mail повідомлення. При відправлення e-mail вказівку теми, тексту і адреси відправника обов'язково. Для MMS обов'язковим
є вказівка теми або тексту. Якщо не вказати тему повідомлення, в її якості буде використано ім'я відправника, передане в запиті або
використовуване за замовчуванням.
|
---|
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.
Параметр 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-повідомлення) або 5-секундних блоків (при голосовому повідомленні (дзвінок)).
<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, і розмір кожного вкладення не повинен перевищувати 3 Мб.
При перевищенні зазначених лімітів буде повертатися помилка з кодом 1 (неправильні параметри).
При відправленні кожної листи максимальний загальний розмір прикріплюються вкладень становить 15 Мб, вкладення,
не вміщаються у цей розмір, будуть передаватися посиланням на наш сайт.
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).
Максимальна кількість вкладень, переданих у запиті, дорівнює чотирьом, і розмір кожного вкладення не повинен перевищувати 3 Мб. При перевищенні
зазначених лімітів оброблювані вкладення будуть виключатися.
Для передачі свого номера телефону в якості імені відправника необхідно вказати його у параметрі sender. Зазначений номер перш
повинен бути доданий та активований в особистому кабінеті на цієї сторінці.
При формуванні запиту можна передавати спеціальний параметр param, в якому задаються деякі характеристики дзвінка
(більш детально можна ознайомитися в описі). Також додатково в запиті можна передати параметр voice,
який визначає голос, використовуваний для озвучування тексту. Даний параметр може приймати такі значення:
- voice = m – чоловічий голос.
- voice = m2 – чоловічий альтернативний голос.
- voice = w – жіночий голос.
- voice = w2 – жіночий альтернативний голос.
Відправка коду в телефонному номеріПри необхідності відправлення цифрового коду для підтвердження певних операцій за допомогою телефонного номера (наприклад, при реєстрації нового користувача, оформленні замовлення, отримання доступу до різних сервісів і т. п.) замість відправки SMS-повідомлення можна скористатися більш дешевим способом передачі коду в номері телефону вхідного дзвінка.
Щоб передати код в телефонному номері необхідно надіслати абоненту спеціальне голосове повідомлення (дзвінок) зі словом code. При отриманні дзвінка абонент може його скинути або підняти трубку. При піднятті трубки система сама скине дзвінок. Останні 6 цифр номеру, з якого прийшов дзвінок, будуть секретним кодом, його необхідно використовувати абоненту для підтвердження операції.
Також можливо використання більш короткого коду номера, вказавши кількість цифр в інструкції для користувачів на своєму сайті.
Для відправки зазначеного коду через API необхідно виконати запит на відправку голосового повідомлення, отримати згенерований код з відповіді системи і зберегти його на своєму боці. Саме цей код прийде абонента в телефонному номері при дзвінку і потрібно для підтвердження операції.
Формат запиту та відповідь Сервера:
https://smsc.ua/sys/send.php?login=<login>&psw=<password>&phones=<phones>&mes=code&call=1
У разі успішної обробки запиту повертається рядок наступного виду (у стандартну відповідь Сервера додається параметр code):
- при fmt = 0: OK - <n> SMS, ID - <id>, CODE - <code>
- при fmt = 1: <id>,<n>,<code>
- при fmt = 2 (xml):
<result>
<id>id</id>
<cnt>n</cnt>
<code>code</code>
</result> |
- при fmt = 3 (json):
{
"id": <id>,
"cnt": <n>,
"code": "<code>"
} |
При використанні даної функції не можна передавати параметр voice, так як при його явної передачі в запиті відбудеться звичайне озвучування тексту повідомлення.
Використання голосового меню (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 | Перенаправлення дзвінка абонента на вказаний номер телефону, де обов'язковим параметром є phone - номер телефону або список номерів телефонів через кому. Можна вказати до 9 номерів. Номери, на які буде відбуватися перенаправлення дзвінка абонента необхідно зареєструвати на даній сторінці.
Необов'язковими параметрами є:
– wait=n - час очікування підняття трубки абонентом, якому був перенаправлений дзвінок, де n - час очікування в секундах. Діапазон можливих значень параметра від 0 до 120. За замовчуванням час очікування підняття трубки абонентом 120 секунд.
– ok:end - після успішного з'єднання з зазначеним номером та закінчення діалогу завершити голосове меню.
– err:n - якщо додзвонитися до вказаного номера не вдалося, то перейти на крок чи мітку n, описану в тілі меню. Мітка може приймати значення будь-якого набору латинських букв і цифр.
|
---|
sms:phone,sender,msg | Відправка SMS-повідомлення на вказаний номер телефону, де phone - номер телефону, sender - ім'я відправника, msg - текст повідомлення.
|
---|
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 5: url 5: call:79999999999,79999999998 wait=10 ok:end err:6 6: call:79999999997 wait=60 ok:end err:callerr 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)://...>, або відправляти в запиті додатковий параметр fileurl, що містить повну http (s)-адресу картинки. При використанні fileurl передача в запиті параметра mes необов'язкова.
Якщо при створенні розсилки передбачається відправка одного тексту на декілька номерів, то необхідно вставляти в текст повідомлення повне http (s) -посилання раніше завантаженого файлу картинки, дізнатися яке можна в особистому кабінеті на сторінці відправки, натиснувши послідовно "прикріпити файл" - "Завантажені файли ". Прикріплюємий файл розміром не повинен перевищувати 512 КБ і задовольняти одному з наступних форматів: JPG, GIF, PNG.Додавання кнопкиДля вставки в повідомлення кнопки, при натисканні на яку буде відбуватися відкриття браузера і перехід на вказану адресу, необхідно додати в текст повідомлення спеціальний макрос {button,url,text}, де:
<button> – назва макросу.
<url> – повний http-адреса посилання, по якій відбудеться перехід при натисканні кнопки.
<text> – текст кнопки. Довжина тексту не може перевищувати 20 символів.
Для вставки в повідомлення кнопки, при натисканні на яку буде відбуватися виклик абонента за вказаним номером телефону, необхідно додати в текст повідомлення спеціальний макрос {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://smsc.ua,Site}" і картинкою, раніше завантаженої в особистому кабінеті і має адресу "http://smsc.ua/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%2Fsmsc.ua%2CSite%7D+http%3A%2F%2Fsmsc.ua%2Fupload%2Ffiles%2Fsms%2F1856f97d%2F6_1.jpg
Відправка viber-повідомлення по одному з визначених шаблонів для тестування з текстом "test", кнопкою "{button,http://smsc.ua,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%2Fsmsc.ua%2CSite%7D+%3Cfile+https%3A%2F%2Fmysite.com%2Fsms%2Fpicture.jpg%3E
Відправка viber-повідомлення по одному з визначених шаблонів для тестування з текстом "test", кнопкою "{button,http://smsc.ua,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%2Fsmsc.ua%2CSite%7D&fileurl=https%3A%2F%2Fmysite.com%2Fsms%2Fpicture.jpg Використання префіксів при відправці повідомленьДля відправки різних типів повідомлень можна скористатися можливістю вказівки спеціальних префіксів на початку або замість тексту повідомлення.
Підтримувані префікси:
Назва | Опис
|
---|
__CALL__: повідомлення | Відправка голосового повідомлення (дзвінка). При відправленні голосового повідомлення у кінці тексту можна вказати
спеціальну комбінацію "\n~~~\n" (переклад рядка, 3 символу тильди і знову переведення рядка), після якої передати параметр param,
визначає деякі характеристики дзвінка (більш докладно можна подивитися описі).
При формуванні повідомлення можна вказувати як текст, так і додавати медіа-файли форматів wav і mp3, а також вставляти
раніше завантажені файли. Більш докладно щодо процесу створення голосового повідомлення можна прочитати на цієї сторінці.
| __VIBER__: повідомлення | Відправка повідомлень користувачам месенджера Viber.
| __SOC__: повідомлення | Відправка повідомлення користувачам соціальних мереж "Однокласники", "ВКонтакте" або користувачам "Mail.Ru Агент".
| __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_trn=1&mega_srv=1&mega_trn=1&bee_srv=1&bee_trn=1&tele2_srv=1&tele2_trn=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_trn | Створити шаблон для оператора МТС (транзакційні повідомлення).
|
---|
mega_srv | Створити шаблон для оператора Мегафон (сервісні повідомлення).
|
---|
mega_trn | Створити шаблон для оператора Мегафон (транзакційні повідомлення).
|
---|
bee_srv | Створити шаблон для оператора Білайн (сервісні повідомлення).
|
---|
bee_trn | Створити шаблон для оператора Білайн (транзакційні повідомлення).
|
---|
tele2_srv | Створити шаблон для оператора Теле2 (сервісні повідомлення).
|
---|
tele2_trn | Створити шаблон для оператора Теле2 (транзакційні повідомлення).
|
---|
У разі помилки Сервер повертає наступний рядок:
- при 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 адрес
одержувачів.
|
---|
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-повідомлення. Буде відправлено sms на кожен номер телефону в списку.
|
---|
mail | Ознака e-mail повідомлення. Файли, що прикріплюються до повідомлення, передаються методом POST в тілі http-запиту.
0 (за замовчуванням) – звичайне повідомлення. 1 – e-mail повідомлення.
|
---|
soc | Ознака soc-повідомлення, що відправляється користувачам соціальних мереж "Однокласники", "ВКонтакте" або користувачам "Mail.Ru Агент".
0 (за замовчуванням) – звичайне повідомлення. 1 – soc-повідомлення.
|
---|
viber | Ознака viber-повідомлення, що надсилається користувачам месенджера Viber.
|
---|
fileurl | Повний http-адреса файлу для завантаження та передачі в повідомленні.
|
---|
mes2 | Даний параметр задає варіант повідомлення для надсилання SMS в режимі автоматичного повтору при недоставленні на альтернативні маршрути, наприклад, відправка в месенджери. Для включення автоматичного повтору необхідно в запиті додатково передати прапор fl[5], рівний 1.
|
---|
call | Ознака голосового повідомлення. При формуванні голосового повідомлення можна передавати як текст, так і прикріплювати файли.
Файли, що додаються до повідомлення повинні передаватися методом POST в тілі http-запиту.
0 (за замовчуванням) – звичайне повідомлення. 1 – голосове повідомлення.
|
---|
voice | Голос, який використовується для озвучування тексту (тільки для голосових повідомлень).
m (за замовчуванням) – чоловічий голос. m2 – чоловічий альтернативний голос. w – жіночий голос. w2 – жіночий альтернативний голос.
|
---|
param | Розділений комами список параметрів для голосового повідомлення у форматі "param=w,i,n".
Тут:
- w – час очікування підняття трубки абонентом після початку дзвінка в секундах. Якщо протягом зазначеного часу абонент не підніме трубку,
то дзвінок піде на повтор з помилкою "абонент зайнятий". Робочий діапазон значень параметра від 10 до 35, але можна вказувати інтервал від 0 до 99
(у разі, якщо значення менше 10, то воно буде приведене до 10, аналогічно для верхньої межі).
- i – інтервал повтору, тобто проміжок часу, після закінчення якого відбудеться повторний дзвінок (у секундах). Робочий діапазон параметра
від 10 до 3600 (у разі, якщо значення менше 10, то воно буде приведене до 10).
- n – загальна кількість спроб дозвону. Робочий діапазон значень від 1 до 9 (0 буде приведений до 1).
При вказівці значення будь-якого параметра, відмінного від можливих, будуть використані значення всіх параметрів за замовчуванням (n = 8, w = 25, i від 3 до 14 секунд по наростаючій).
|
---|
subj | Тема MMS або e-mail повідомлення. При відправлення e-mail вказівку теми, тексту і адреси відправника обов'язково. Для MMS обов'язковим
є вказівка теми або тексту. Якщо не вказати тему повідомлення, в її якості буде використано ім'я відправника, передане в запиті або
використовуване за замовчуванням.
|
---|
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.
Параметр 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>
<err>err</err>
</sms> |
- при fmt = 3 і all = 0:
{
"status": <status>,
"last_date": "<last_date>",
"last_timestamp": <last_timestamp>,
"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>
<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>
|
- при fmt = 3 і all = 1:
{
"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>",
"comment": "<comment>",
"type": <type>
} |
- при 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>
<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>
|
- при fmt = 3 і all = 2:
{
"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>",
"comment": "<comment>",
"mccmnc": "<mccmnc>",
"country": "<country>",
"operator": "<operator>",
"operator_orig": "<operator_orig>",
"region": "<region>",
"type": <type>
} |
Де:
<status> – код статусу (список)
<last_date> – дата останньої зміни статусу. Формат DD.MM.YYYY hh:mm:ss.
<last_timestamp> – штамп часу останньої зміни статусу.
<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 –
Дзвінок, 10 – Viber).
Відповіді для 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>
<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>,
"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>
<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>,
"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>
<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>,
"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> – штамп часу останньої зміни статусу.
<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-повідомлення. Наприклад, послуга підключена,
або абонент знаходиться в роумінгу, де не активований прийом повідомлень, або у оператора абонента не налагоджено обмін SMS з
поточним роумінговими оператором. Також це може бути міський номер без прийому повідомлень.
|
---|
12 | Помилка в телефоні абонента | Не вдається доставити повідомлення абоненту з-за помилки в телефонному апараті або на SIM-картці.
|
---|
13 | Абонент заблокований | Виникає, наприклад, якщо на рахунку абонента нульовий або негативний баланс, і
він знаходиться в роумінгу, або заблоковано оператором за тривалу несплату або добровільно самим абонентом. Також
дана помилка може повертатися при пошкодженні SIM-карти або неправильному введенні PIN і PUK-кодів SIM-карти.
|
---|
21 | Немає підтримки сервісу | Апарат абонента не підтримує роботу з даною послугою (сервісом).
|
---|
200 | Віртуальна відправлення | Дане повідомлення з'являється під статусом у разі відправлення повідомлення
повідомлення в режимі тестування (при встановленій у налаштуваннях галочці "Режим тестування (віртуальна відправка без
оплати)").
|
---|
219 | Заміна sim-карти | Помилка відправки повідомлення у зв'язку з заміною абонентом sim-карти. Після фізичної заміни sim-карти абоненту заблокований прийом повідомлень від буквених імен відправників на 24 години. Блокування може бути знято шляхом поповнення балансу на 100 рублів.
|
---|
220 | Переповнена чергу у оператора | Зазначена помилка може виникати у випадку, коли абонент недоступний
для прийому SMS, але повідомлення продовжують приходити оператору і відбувається переповнення внутрішньої черги повідомлень
для даного абонента. У рідкісних випадках можлива поява помилки в результаті збою в мережі оператора або переповненні
загальної черги повідомлень. У всіх подібних ситуаціях система з певними інтервалами кілька разів намагається відправити
зазначені повідомлення повторно.
|
---|
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 | Відхилено оператором | Оператор відхилив повідомлення без зазначення точного коду помилки. Таке буває, наприклад,
коли номер не належить жодному мобільному оператору, тобто з неіснуючим кодом, або з якоїсь іншої причини оператор
не може доставити повідомлення.
|
---|
Видалення повідомленняДля видалення повідомлення необхідно викликати методом 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>
Опис параметрівОпис параметрів, що передаються Серверу:
Параметр | Значення
|
---|
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 адрес.
|
---|
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>
... |
- при fmt = 1:
<id>,<name>,<number>
... |
- при fmt = 2:
<list>
<group>
<id>id</id>
<name>name</name>
<number>number</number>
</group>
...
</list> |
- при fmt = 3:
[{
"id": <id>,
"name": "<name>",
"number": <number>
},
...] |
Де:
<id> – ідентифікатор групи, призначений Сервером при створенні.
<name> – назва групи.
<number> – номер групи для розсилок.Приклади операцій з контактамиПриклади:
Створення контакту з ім'ям "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>
Отримання статистики по субклиентам c незалежним балансом:
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 | Новий пароль субклиента.
|
---|
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] | Прапор, який встановлює розширений режим особистого кабінету.
|
---|
Додаткові параметри для налаштування доступу до сервісу
|
---|
ip | Список IP-адрес, з яких дозволений доступ до функцій сервісу.
|
---|
fl[16] | Установка цього прапора відкриває доступ до особистого кабінету тільки для IP-адрес, перелічених у параметрі ip.
|
---|
fl[17] | Установка прапора доступу через HTTP/SMTP API для IP-адрес, зазначених у параметрі ip.
|
---|
fl[18] | Прапор, що відкриває можливість доступу до функції e-mail2sms для IP-адрес, перелічених у параметрі ip.
|
---|
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
Отримання статистики по субклиентам, що мають загальний баланс з головним обліковим записом:
https://smsc.ua/sys/users.php?get_stat=1&login=alex&psw=123
Отримання статистики по субклиенту з логіном "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. Коментар до документа може бути вказаний в додатковому параметрі doc_info.
Опис параметрівОпис параметрів, що передаються Серверу:
Параметр | Значення
|
---|
login | Логін Клієнта.
|
---|
psw | Пароль Клієнта (можна додати або редагувати на даннійсторінці).
|
---|
all | 0 (за замовчуванням) – отримати список активованих імен відправників.
1 – отримати повний список імен відправників.
|
---|
sender | Створюване чи потрібне ім'я відправника.
|
---|
mega | 1 – зареєструвати ім'я оператора Мегафон за тарифом з безкоштовними іменами.
|
---|
mts | 1 – зареєструвати ім'я оператора MTS.
|
---|
mts_step | 1 – зареєструвати платне ім'я оператора MTS.
|
---|
tele2 | 1 – зареєструвати ім'я оператора Tele2 за тарифом з безкоштовними іменами.
|
---|
mega_step | 1 – зареєструвати платне ім'я оператора Мегафон.
|
---|
bee_step | 1 – зареєструвати платне ім'я оператора Білайн.
|
---|
motiv_step | 1 – зареєструвати платне ім'я оператора MOTIV.
|
---|
tele2_step | 1 – зареєструвати платне ім'я оператора Tele2.
|
---|
ua_reg | 1 – зареєструвати ім'я для України на знижений тариф за національною трафіку.
Для даного тарифу необхідно додатково передати наступні параметри:
fio – юридична назва організації (ТОВ/СПД).
inn – ЄДРПОУ/ІПН.
site – Адреса сайту (необов'язковий параметр).
email – E-mail для зв'язку.
address – Фактична адреса.
desc – Опис послуг, що надаються відправником.
subj – Тема (мета інформування).
|
---|
ua_int | 1 – зареєструвати ім'я України за більш високим тарифом для міжнародного трафіку.
|
---|
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 | Кодування переданих параметрів.
|
---|
Відповідь сервера і коди помилокУ разі помилки Сервер повертає наступний рядок:
- 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 = <mega_status>, mts = <mts_status>, mega_step = <mega_step_status>, bee_step = <bee_step_status>, motiv_step = <motiv_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>, id = <id>
... |
- при fmt = 1 і operators = 1:
<sender>,<mega_status>,<mts_status>,<mega_step_status>,<bee_step_status>,<motiv_step_status>,<mts_step_status>,<tele2_step_status>,
<tele2_status>,<ua_reg_status>,<ua_int_status>,<id>
... |
- при fmt = 2 і operators = 1:
<list>
<sender mega="<mega_status>" mts="<mts_status>" mega_step="<mega_step_status>" bee_step="<bee_step_status>" motiv_step="<motiv_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>" id="<id>">sender</sender>
...
</list>
|
- при fmt = 3 і operators = 1:
[{
"sender": "<sender>",
"mega": "<mega_status>",
"mts": "<mts_status>",
"mega_step": "<mega_step_status>",
"bee_step": "<bee_step_status>",
"motiv_step": "<motiv_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>",
"id": "<id>"
},
...] |
Де:
<sender> – зареєстроване і допущене до використання ім'я відправника.
<mega_status>, <mts_status>(до 01.12.2017), <mega_step_status>, <bee_step_status>, <motiv_step_status>, <mts_step_status>(c 01.12.2017), <tele2_step_status>,
<tele2_status>, <ua_reg_status>, <ua_int_status> – код статусу імені відправника у відповідного оператора
(0 - очікує реєстрації, 1 - відправлено на реєстрацію, 2 - допущено оператором, 3 - не прийнято оператором, 4 - тимчасово відключено,
5 - недостатньо коштів на рахунку, 6 - дубль іншого імені (конфлікт), 8 - необхідні підтверджуючі документи).
<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 | Пароль Клієнта (можна додати або редагувати на даннійсторінці).
|
---|
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.
Приклади:
Отримання списку вхідних повідомлень за поточну добу:
https://smsc.ua/sys/get.php?get_answers=1&login=alex&psw=123
Отримання списку вхідних повідомлень за останні 48 годин:
https://smsc.ua/sys/get.php?get_answers=1&login=alex&psw=123&hour=48
Отримання списку вхідних повідомлень з ідентифікаторами, більшими id="1234567":
https://smsc.ua/sys/get.php?get_answers=1&login=alex&psw=123&after_id=1234567
Сервер не приймає більше трьох однакових запитів протягом хвилини на отримання списку входять
повідомлень для зниження навантаження і захисту від помилок і зациклення в програмі на стороні Клієнта.
Отримання статистикиДля отримання статистики відправлених повідомлень необхідно викликати методом 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_mega_accounts=1&login=<login>&psw=<password>
Для отримання статистики по певному особовому рахунку необхідно викликати методом GET або POST адреса:
https://smsc.ua/sys/get.php?get_mega_accounts=1&login=<login>&psw=<password>&account=<account>
Опис параметрів, що передаються Серверу:
Параметр | Значення
|
---|
login | Логін Клієнта.
|
---|
psw | Пароль Клієнта (можна додати або редагувати на даннійсторінці).
|
---|
account | Номер особового рахунку у оператора Мегафон.
|
---|
У разі помилки Сервер повертає наступний рядок:
- 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:
account = <account>, phone = <phone>, sms_mon = <sms_mon>, sms_day = <sms_day>, sms_yes = <sms_yes>, sms_pmon = <sms_pmon>, balance = <balance>, credit = <credit>, senders = <senders>
... |
- при fmt = 1:
<account>,<phone>,<sms_mon>,<sms_day>,<sms_yes>,<sms_pmon>,<balance>,<credit>,<senders>
... |
- при fmt = 2:
<accounts>
<account>
<number>number</number>
<phone>phone</phone>
<sms_mon>sms_mon</sms_mon>
<sms_day>sms_day</sms_day>
<sms_yes>sms_yes</sms_yes>
<sms_pmon>sms_pmon</sms_pmon>
<balance>balance</balance>
<credit>credit</credit>
<senders>senders</senders>
</account>
...
</accounts> |
- при fmt = 3:
[{
"account": "<account>",
"phone": "<phone>",
"sms_mon": <sms_mon>,
"sms_day": <sms_day>,
"sms_yes": <sms_yes>,
"sms_pmon": <sms_pmon>,
"balance": "<balance>",
"credit": <credit>,
"senders": "<senders>"
},
...] |
Де:
<account> - номер особового рахунку.
<phone> - телефон, прив'язаний до особового рахунку.
<sms_mon> - кількість смс, відправлених за поточний місяць.
<sms_day> - кількість смс, відправлених за поточний день.
<sms_yes> - кількість смс, відправлених за попередній день.
<sms_pmon> - кількість смс, відправлених за попередній місяць.
<balance> - баланс.
<credit> - кредит.
<senders> - зареєстровані імена відправників.
Приклади:
Отримання статистики за всіма особовими рахунками:
https://smsc.ua/sys/get.php?get_mega_accounts=1&login=alex&psw=123
Отримання статистики по особовому рахунку "111":
https://smsc.ua/sys/get.php?get_mega_accounts=1&login=alex&psw=123&account=111
Сервер не приймає більше трьох однакових запитів протягом хвилини на отримання статистики
для зниження навантаження і захисту від помилок і зациклення в програмі на стороні Клієнта.
Запит тарифівДля отримання списку тарифів зазначеного Клієнта необхідно викликати методом 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 | Ідентифікатор короткого посилання. Призначається автоматично при створенні.
|
---|
У разі помилки Сервер повертає наступний рядок:
- 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.
Для захисту переданих даних від підміни в адресу обробника додатково можна вказати будь-який з параметрів md5, sha1, crc32,
визначають алгоритм обчислення контрольного параметра з хешем рядка:
"id:phone:status:<секретная строка>" − для статусу доставки
"phone:mes:to:<секретная строка>" − для вхідного повідомлення
"phone:ts:<секретная строка>" − для підтвердження номеру за допомогою дзвінка
у вигляді:
?md5=<секретная строка>
?sha1=<секретная строка>
?crc32=<секретная строка>
В якості символів секретної рядка можна використовувати латинські літери, цифри, мінус та підкреслення.
Обробникові буде переданий відповідний параметр, в якому секретна рядок буде замінена на значення хешу переданих даних.
Всі параметри передаються методом POST.
Передані параметри для статусу SMS-повідомлення:
Параметр | Значення
|
---|
id | Ідентифікатор повідомлення.
|
---|
phone | Номер телефону.
|
---|
status | Статус повідомлення.
|
---|
time | Час зміни статусу (або доставки SMS-повідомлення абоненту).
Формат: DD.MM.YY hh:mm:ss (по часовому поясу, вказаною в налаштуваннях).
|
---|
ts | Час зміни статусу у вигляді штампа в секундах.
|
---|
err | Код помилки, якщо повідомлення не може бути доставленийсписок). Передається, якщо не дорівнює нулю.
|
---|
syserr | Додаткова помилка від оператора, є не завжди.
|
---|
cnt | Кількість частин (при відправці SMS-повідомлення) або 5-секундних блоків (при голосовому повідомленні (дзвінок)).
|
---|
type | Тип повідомлення (0 – SMS, 1 – Flash-SMS, 2 – Бінарне SMS, 3 – Wap-push, 4 – HLR-запит, 5 – Ping-SMS, 6 – MMS, 7 –
Дзвінок, 10 – Viber).
|
---|
cost | Вартість повідомлення.
|
---|
flag | Прапор у вигляді 2-х байтового числа, що містить різну інформацію про повідомленні. Можливі комбінації значень бітів різних характеристик.
Біти 0-3 (тип повідомлення):
0 (за замовчуванням) – SMS.
1 – Flash-SMS.
2 – Бінарне SMS.
3 – Wap-push.
4 – HLR-запит.
5 – Ping-SMS.
6 – MMS.
7 – Дзвінок.
10 – Viber.
Біт 5 – оплата повідомлення з другого балансу.
Біт 8 – ознака шаблонного повідомлення.
|
---|
sender | Ім'я відправника, який відображається в телефоні одержувача.
|
---|
dtmf | Послідовність символів, набираемая абонентом на цифровій клавіатурі під час прослуховування голосового повідомлення (дзвінка).
|
---|
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)-Адресі обробника.
|
---|
Крім описаних вище стандартних параметрів Сервер також буде передавати методом POST всі параметри,
зазначені в http(s)-адресі обробника після знаку "?".
Для различия статуса сообщения, входящего SMS-сообщения или служебного сообщения (при использовании услуги "Подтверждение номера с помощью звонка") в одном обработчике можно выполнить проверку на наличие параметра mes (для входящего сообщения) и waitcall (для услуги подтверждения номера):
if (isset($_POST["mes"])) { // message } elseif (isset($_POST["waitcall"])) { // confirmation } else { // status }
Пересилання статусів на обробник Клієнта здійснюється тільки при відправленні повідомлень
по протоколах HTTP/HTTPS, SMTP або SMPP. При відправці повідомлень з особистого кабінету передача статусів на обробник Клієнта
не відбувається.
У разі якщо від обробника Клієнта повернеться відповідь з кодом помилки, відмінним від 200 або 404, то Сервер з певною періодичністю буде повторювати запит на обробник. Підключення антиспам перевірки (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 | Зазначений номер телефону абонента знаходиться в чорному списку Клієнта.
|
---|
9 | Спроба відправки понад п'ятдесят однакових запитів на отримання номеру телефону для підтвердження протягом хвилини.
Дана помилка виникає також при спробі відправки п'ятнадцяти і більше запитів одночасно з різних підключень під одним логіном (too many concurrent requests).
|
---|
У разі успішного запиту Сервер повертає відповідь у вигляді рядка.
- при fmt = 0 та fmt = 1:
<phone>
- при fmt = 2:
<phone>phone</phone>
|
- при fmt = 3:
{
"phone": "<phone>"
} |
Де:
<phone> – номер телефону, на який протягом 15 хвилин повинен здійснити дзвінок абонент для підтвердження свого номера телефону.
Після дзвінка абонента Сервер зафіксує факт дзвінка у вигляді вхідного повідомлення з текстом "[waitcall]"
і відправить на обробник Клієнта всю необхідну інформацію про даний дзвінок.
Сервер не приймає понад п'ятдесят однакових запитів на отримання номеру телефону для підтвердження протягом хвилини для зниження навантаження і захисту від помилок і зациклення в програмі на стороні Клієнта.
|