Якщо вам необхідно налаштувати автоматичні SMS-сповіщення з вашого Інтернет-магазину, 1С, CRM або іншого програмного забезпечення або ви використовуєте Mobizon як CRM - наше API допоможе вам вирішити ці завдання.
Для комунікації з сервером API використовується протокол HTTP з можливістю безпечних з'єднань SSL. Для передачі запитів використовуються методи GET і POST. Сервер може повертати відповідь в одному з форматів: XML або JSON на ваш вибір. Детальніше про те, як підключитися до API та виконувати запити, описано нижче.
Підключення до API
Для того щоб виконувати запити до API, необхідно ввімкнути і налаштувати цю функцію в Панелі управління Mobizon:
Відкрийте Налаштування API у Панелі
управління:
Увімкніть опцію Ввімкнути доступ до API :
Вкажіть IP адреси, з яких будуть відбуватися запити до API.
Після ввімкнення доступу ви побачите свій Ключ API. Використовуйте цей ключ в вашому додатку для виконання
запитів до API.
Ключ є секретним, не варто його записувати або передавати будь-кому без необхідності, так як особа, яка отримала ваш ключ, зможе проводити будь-які операції з вашим аккаунтом за допомогою API.
Для забезпечення безпеки вашого облікового запису радимо обов'язково вказати список IP-адрес, з яких
повинен бути дозволений доступ до API з вашим ключем. В поле Список IP адрес для доступу до API
перерахуйте IP-адреси ваших серверів.
Адрес може бути кілька, в цьому випадку розділяйте їх комами, наприклад: 192.12.34.56,23.45.67.89,123.123.123.123 .
Якщо поле залишити порожнім, працювати з API можна буде з будь-якої IP-адреси, але це небезпечно.
Ви можете змінити ключ API, натиснувши на кнопку «Оновити» поруч з ключем. В цьому випадку всі додатки, що використовують колишній ключ, більше не зможуть отримати доступ до API. Для відновлення доступу замініть старий ключ на новий в налаштуваннях вашого додатку.
Робота з API
Точка входу до API
Всі запити до API здійснюються за адресою: https://api.mobizon.ua/service/
Ви можете відправляти запити за допомогою HTTP або HTTPS за вашим вибором. Для безпеки комунікації вашого додатку з API Mobizon ми рекомендуємо всі запити робити за допомогою HTTPS , але якщо ваше ПЗ не підтримує можливість створення безпечних HTTP-запитів, є можливість робити запити за звичайним HTTP протоколом без шифрування, в такому випадку адреса API для вас буде такою: http://api.mobizon.ua/service/ .HTTPS в документації і прикладах можна вважати рівнозначними HTTP .
Обов'язкові параметри
Мінімальний запит до API містить назву модуля, методу і ключ API:
https://api.mobizon.ua/service/user/getownbalance?apiKey=KKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKK
де:
user - модуль API,
getownbalance — метод API,
а після символу питання йдуть додаткові параметри, в даному випадку apiKey .
Опціональні параметри
output — формат відповіді, що повертається сервером.
json — відповідь повертається в форматі json рядка (за замовчуванням)xml — відповідь повертається у вигляді xml документа
https://api.mobizon.ua/service/user/getownbalance?output=json &api=v1&apiKey=KKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKK api — версія API.API — v1, це значення використовується За замовчуванням.
https://api.mobizon.ua/service/user/getownbalance?output=json&api=v1 &apiKey=KKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKK
Інші параметри.
Всі значення переданих в API параметрів повинні бути в форматі url-encoded . Як це зробити в конкретній мові програмування або системі, ви можете дізнатися в документації до відповідної мови/системи.
Формат відповідей сервера API
Відповідь сервера є рядком у вигляді обраного формату даних (XML або JSON), який містить об'єкт, що складається з трьох елементів: code, data і message. Приклад відповіді в форматі JSON:
{
"code":0,
"data":{
"balance":"4043.0656",
"currency":"UAH"
},
"message":""
}
У форматі XML відповідь виглядає наступним чином:
<?xml version="1.0" encoding="UTF-8"?>
<root>
<code>0</code>
<data>
<balance>123.4567</balance>
<currency>UAH</currency>
</data>
<message></message>
</root>
где:
code — код відповіді API, дв. коди відповідей API у документації ,
data — дані, що повертаються в форматі, передбаченому методом API, що виконується, а у
випадку коду помилки можлива наявність даних, які розшифровують причини помилки (наприклад, список
помилкових полів і
опису помилок в них у разі помилки валідації),
message — текст статусу, зазвичай в загальних рисах описує суть помилки при її наявності.
Коди відповідей API
Результат, який повертається, завжди містить поле code , що містить числове значення, яке вказує на результат виконання запиту:
0 — відповідь успішна.100 — відповідь не є помилкою і означає, що операція була відправлена в фонове виконання. У цьому випадку поле data містить ID фонової операції, прогрес і статус якої можна відстежити за допомогою запиту до API taskqueue/getstatus .
Будь-який інший код відповіді — помилка під час виконання операції. Переглянути коди помилок ви можете на цій сторінці документації .
Клієнтська бібліотека на PHP
Ви можете використовувати офіційний клієнт MobizonApi на PHP. Приклади використання .
Крім цього, є можливість підключити цей модуль, використовуючи Composer .
Приклади роботи з Клієнтським модулем API на PHP
Якщо у Вас є власні робочі приклади використання, будемо раді розмістити їх у нас на сайті. просто надішліть нам посилання або приклад коду за адресою support@mobizon.ua
Приклад використання GET запитів
Для відправки повідомлень з вашого додатку, якщо він не підтримує можливість реалізації POST запитів,
використовуйте GET запит наступного виду:
https://api.mobizon.ua/service/message/sendsmsmessage?recipient=NNNNNNNNNNN&from=PPPPPPP&text=Message+text+here%21&apiKey=KKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKK
де:
NNN...NNN - номер телефону одержувача в міжнародному форматі (без символу
+ ),
наприклад,
380631392155.
PPP...PPP - підпис відправника (альфаім'я). Підпис можна не вказувати, в цьому випадку буде використаний загальний системний підпис або ваш підпис за замовчуванням (якщо він є).
Message+text+here%21 - текст вашого SMS-повідомлення в форматі url-encoded string: Message text here! .KKK...KKK - ваш ключ API, який необхідно отримати в Панелі управління.