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

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

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

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

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

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

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

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

• 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

Ответ сервера является строкой в виде выбранного формата данных (XML или JSON), которая содержит объект, состоящий из трех элементов: code, data и message. Пример ответа в формате JSON:

{
    "code":0,
    "data":{
        "balance":"4043.0656",
        "currency":"KZT"
    },
    "message":""
}

В формате XML ответ выглядит следующим образом:

<?xml version="1.0" encoding="UTF-8"?>
<root>
    <code>0</code>
    <data>
        <balance>123.4567</balance>
        <currency>KZT</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.kz

• Отправка одного SMS сообщения
• Отправка массовой SMS рассылки
• Получение состояния баланса
• Получение списка доступных для использования подписей (альфаимен)
• Сохранение отчета о СМС сообщениях по заданным критериям поиска
• Сохранение сводного отчета о СМС кампаниях по заданным критериям поиска

Пример использования GET запросов

Для отправки сообщений из вашего приложения, если оно не поддерживает возможность реализации POST запросов, используйте GET запрос следующего вида:

https://api.mobizon.kz/service/message/sendsmsmessage?recipient=NNNNNNNNNNN&from=PPPPPPP&text=Message+text+here%21&apiKey=KKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKK

• NNN...NNN - номер телефона получателя в международном формате (без символа +), например, 77051708264.
• PPP...PPP - подпись отправителя (альфаимя). Подпись можно не указывать, в этом случае будет использована общая системная подпись или ваша подпись по умолчанию (если она есть).
• Message+text+here%21 - текст вашего SMS-сообщения в формате url-encoded string: Message text here!.
• KKK...KKK - ваш ключ API, который необходимо получить в Панели управления.