Если вам необходимо настроить автоматические 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.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 — формат ответа, возвращаемого сервером.
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
Другие параметры.
Все значения передаваемых в 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, который необходимо получить в Панели управления.