SMS API

Сервис Mobizon дает возможность автоматически отправлять SMS-сообщения с вашего сайта, 1С, CRM-системы или любого другого ПО. Он предоставляет пользователям набор функций API для работы с SMS.

Документация API находится здесь.

Для того чтобы выполнять запросы к API, необходимо авторизоваться на сайте и включить эту функцию в панели управления.

Как включить доступ к API

  1. Запустите приложение Настройки API в Панели управления. Настройки API
  2. Включите опцию Включить доступ к 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.com/service/

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

Обязательные параметры запроса к API

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

https://api.mobizon.com/service/user/getownbalance?apiKey=1234567890abcdefghit1234567890abcdefghit
где:

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

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

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

output — формат возвращаемых данных

На данный момент поддерживается два формата ответа сервера API:

  • ответ возвращается в формате json строки (по умолчанию)
  • ответ возвращается в виде xml документа
Пример запроса:

https://api.mobizon.com/service/user/getownbalance?output=json&api=v1

api — версия API

Актуальная версия API — v1, пример запроса:

https://api.mobizon.com/service/user/getownbalance?output=json&api=v1

другие параметры

Любые другие параметры, в том числе и параметры методов, могут быть переданы в качестве GET параметров или POST параметров. Следует учитывать максимальную длину GET строки, поэтому мы рекомендуем все запросы к API осуществлять посредством POST запросов.

Обратите внимание! Все значения передаваемых в API параметров должны быть в формате url-encoded. Как это сделать в конкретном языке программирования или системе, вы можете узнать в документации к соответствующему языку/системе.

Формат ответов сервера API

Обычно ответ сервера состоит из трех параметров: code, data и message:
{"code":0,"data":{"currency": 'KZT', "balance": 123.4567},"message":""}
где:

  • code— код ответа API, см. ниже коды ответов API
  • data— возвращаемые данные в формате, предусмотренном выполняемым методом API, а в случае кода ошибки возможно содержание данных, расшифровывающих причины ошибки (например, список ошибочных полей и тексты ошибок в них в случае ошибки валидации)
  • message— текст статуса, обычно в общих чертах описывающий ошибки при их наличии.

Коды ответов API

0 - ответ успешный.

100 - ответ не является ошибкой и означает, что операция была отправлена в фоновое выполнение. В этом случае поле data содержит ID фоновой операции, процесс и окончание которой можно отследить при помощиTaskqueue::GetStatus.

Любой другой код ответа - ошибка во время выполнения операции. Просмотреть коды ошибок вы можете на этой странице.

Клиентская библиотека на PHP

Вы можете использовать официальный клиент Mobizon API для PHP. Примеры использования.

Кроме этого, есть возможность подключить этот модуль, используя Composer.

Примеры работы с API на PHP

  • Получение баланса текущего пользователя
  • Отправка одиночного сообщения

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

Для отправки сообщений с вашего сайта или любого другого ПО используйте GET запрос следующего вида:

https://api.mobizon.com/service/message/sendsmsmessage?apiKey=KKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKK&recipient=NNNNNNNNNNN&from=PPPPPPP&text=Текст сообщения

Где: Внимание! Перед отправкой SMS текст необходимо кодировать функцией urlencode (http://php.net/manual/ru/function.urlencode.php) , поскольку сам текст SMS используется как часть URL при отправке запроса.

Если этого не сделать, то такие символы как "+", "?", "&" и некоторые другие в тексте SMS система может обработать как служебные, что вызовет ошибки при отправке SMS. Функция urlencode позволяет избежать этого.

SMS API