SMS шлюз. Підключення до API

Загальні відомості

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

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

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

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

1. Відкрийте Налаштування API в Панелі управління:
   
2. Увімкніть опцію Ввімкнути доступ до API:
   
3. Вкажіть IP адреси, з яких будуть відбуватися запити до API.

Після ввімкнення доступу ви побачите свій Ключ API. Використовуйте цей ключ в вашому додатку для виконання запитів до API.

Для забезпечення безпеки вашого облікового запису рекомендуємо обов'язково вказати список IP-адрес, з яких повинен бути дозволений доступ до API з вашим ключем. В поле Список IP адрес для доступу до API перерахуйте IP-адреси ваших серверів. Адрес може бути кілька, в цьому випадку розділяйте їх комами, наприклад: 192.12.34.56,23.45.67.89,123.123.123.123.

Ви можете змінити ключ API, натиснувши на кнопку «Оновити» поруч з ключем. В цьому випадку всі додатки, що використовують колишній ключ, більше не зможуть отримати доступ до API. Для відновлення доступу замініть старий ключ на новий в налаштуваннях вашого додатку.

Робота з API

Точка входу в API

Всі запити до API здійснюються за адресою: https://api.mobizon.ua/service/

Обов'язкові параметри

Мінімальний запит до API містить назву модуля, методу і ключ API:

https://api.mobizon.ua/service/user/getownbalance?apiKey=KKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKK

• user - модуль API,
• getownbalance — метод API,

а після символу питання йдуть додаткові параметри, в даному випадку apiKey.
Важливо відзначити, що перед символом питання не повинно бути символу косої риски (слеш), такий запит буде вважатися неправильним:

https://api.mobizon.ua/service/user/getownbalance/?apiKey=KKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKK

Опціональні параметри

• 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

Відповідь сервера є рядком у вигляді обраного формату даних (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

• Відправка одного SMS повідомлення
• Відправка масової SMS розсилки
• Отримання стану балансу
• Отримання списку доступних для використання підписів (альфаімен)
• Збереження звіту про SMS повідомлення за заданими критеріями пошуку
• Збереження зведеного звіту про SMS кампанії за заданими критеріями пошуку

Приклад використання 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, який необхідно отримати в Панелі управління.