Реєстрація

Підключення до API

Якщо вам необхідно налаштувати автоматичні SMS-сповіщення з вашого Інтернет-магазину, 1С, CRM або іншого програмного забезпечення або ви використовуєте Mobizon як CRM - наше API допоможе вам вирішити ці завдання.

Для комунікації з сервером API використовується протокол HTTP з можливістю безпечних з'єднань SSL. Для передачі запитів використовуються методи GET і POST. Сервер може повертати відповідь в одному з форматів: XML або JSON на ваш вибір. Детальніше про те, як підключитися до API та виконувати запити, описано нижче.

Підключення до API

Для того щоб виконувати запити до API, необхідно ввімкнути і налаштувати цю функцію в Панелі управління Mobizon:

  1. Відкрийте Налаштування API у Панелі управління:
    Додаток Налаштування API в Панелі управління
  2. Увімкніть опцію Ввімкнути доступ до API:
    Ввімкнути доступ до API Mobizon
  3. Вкажіть 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 — формат відповіді, що повертається сервером.
    На даний момент підтримується два формати відповіді сервера API:
    • 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
  • Інші параметри.
    Будь-які інші параметри, в тому числі і параметри методів, можуть бути передані в якості GET або POST параметрів. Слід враховувати максимальну довжину GET запиту і можливе кешування відповідей на GET запити проміжними вузлами мережі, тому ми рекомендуємо все запити до API здійснювати за допомогою методу POST.
Зверніть увагу! Всі значення переданих в 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, який необхідно отримати в Панелі управління.