Регистрация

Подключение к 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.kz/service/

Обратите внимание! Вы можете отправлять запросы посредством HTTP или HTTPS по вашему выбору. Для безопасности коммуникации вашего приложения с API Mobizon мы рекомендуем все запросы делать посредством HTTPS, но если ваше ПО не поддерживает возможность создания безопасных HTTP-запросов, то есть возможность делать запросы по обычному HTTP протоколу без шифрования, в таком случае адрес API для вас будет таким: http://api.mobizon.kz/service/.
Все последующие упоминания HTTPS в документации и примерах можно считать равнозначными HTTP.

Обязательные параметры

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

https://api.mobizon.kz/service/user/getownbalance?apiKey=KKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKK
где:
  • user - модуль API,
  • getownbalance — метод API,

а после символа вопроса идут дополнительные параметры, в данном случае apiKey.

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

  • output — формат ответа, возвращаемого сервером.
    На данный момент поддерживается два формата ответа сервера API:
    • json — ответ возвращается в формате json строки (по умолчанию)
    • xml — ответ возвращается в виде xml документа

    Пример запроса:
    https://api.mobizon.kz/service/user/getownbalance?output=json&api=v1&apiKey=KKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKK

  • api — версия API.
    Актуальная версия API — v1, это значение используется по умолчанию.
    Пример запроса:
    https://api.mobizon.kz/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.kz/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, который необходимо получить в Панели управления.