API для sms рассылки

Что делать, когда необходимо с какой либо целью организовать отправку sms сообщений прямо с web страницы. Например, есть крайне редко используемая в России и широко известная за рубежом технология привлечения и удержания клиентов основанная на организации обратной связи клиент – менеджер с помощью смс сообщений отправляемых с сайта компании.

Такой подход дает ряд преимуществ, особенно, для малого и среднего бизнеса где менеджеры зачастую не привязаны к рабочему месту, могут трудиться дома и в командировке. Принцип работы прост: клиент пишет sms сообщение в текстовом поле и нажимает кнопку “отправить”. СМС сообщение поступает на телефон ответственного за работу с клиентами независимо от того, где он находится.

Таким образом, ни один контакт не будет потерян. Единственное, что следует предусмотреть, это обязательное поле для контактных данных клиента, например, телефона или e-mail. Положительным побочным эффектом такого подхода является то, что за весьма короткий срок возможно создать обширную базу телефонных номеров заинтересованных в ваших услугах. Ее можно успешно использовать для организации собственной смс рассылки для продвижения своих товаров и услуг, информирования клиентов о акциях и предложениях, давать sms – купоны на скидку и многое другое.

И это не единственное применение бесплатной для клиента отправки сообщений с сайта. Точно таким же образом можно легко организовать прием сообщений для сотрудников техподдержки, служб доставки и сервиса, организовать опросы и голосования. Кроме того возможна отправка бесплатных смс с сайта для увеличения его посещаемости. Такой сервис всегда привлекает посетителей.

Взаимодействие с API осуществляется по протоколам HTTP, параметры передаются методом POST.
Все запросы необходимо подписывать при помощи персонального ключа (API-KEY), который можно получить обратившись в службу технической поддержки.

Чтобы обратиться к API-функции, нужно вызвать ее по определенному адресу, формируемому из:

  1. основного адреса шлюза: http://api.sms-38.ru/api/
  2. названия компонента
  3. названия функции

Например:

  • http://api.sms-38.ru/api/user/balance, user — компонент, balance — функция
  • http://api.sms-38.ru/api/message/send, message — компонент, send — функция

Общие для всех функций параметры

  • user — логин указанный при регистрации
  • sign — подпись запроса, сформированная функцией md5(sha1(параметр1 + параметр2 + .. + API KEY))

 

Функция генерации подписи на PHP:


/**
 * @param string $username - логин пользователя или API-аккаунта
 * @param array $params - параметры вызываемой функции (например: recipients, message, sender, ...)
 * @param string $apiKey - API-ключ пользователя или API-аккаунта
 */
function sign($username, $params, $apiKey)
{
    ksort($params); // сортируем значения параметров функции по ключу
    return md5(sha1($username . join('', $params) . $apiKey));
}

// пример использования, отправка СМС:
$sign = sign('vasya', array(
    'recipients' => '8(950)111-22-55', // номер в любом формате
    'message' => 'Привет, как дела?',
    'sender' => 'Vasya',
    'test' => 1, // тестовый режим, в рабочем режиме параметр можно пропустить
), 'Qdfe3Sf');

// запрос баланса
$sign = sign('vasya', array(), 'Qdfe3Sf'); // параметров нет, т.к. для запроса баланса достаточно указать логин

 

Примеры запросов

Запрос баланса:

http://api.sms-38.ru/api/user/balance
HTTP POST
user=supercat&sign=8421e3b2a28b73fee0373307117bd81d

 

Отправка СМС:

http://api.sms-38.ru/api/message/send
HTTP POST
user=supercat&recipients=79001112233&message=preved&sender=medved&sign=e39e438b0d666d64ad1b0534a733887f

 

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

Ответ приходит в формате JSON и всегда содержит параметр status, определяющий выполнена функция успешно или произошла ошибка. Может принимать значения: success — при успешном выполнении, error — при ошибке.

 

Обработка ошибок

Общие для всех функций ошибки:

Код Текст Описание
1 invalid user Логин указан некорректно или такого пользователя не существует.
2 invalid signature Некорректная подпись запроса, проверьте свой API KEY и функцию генерирования подписи.

 

Функции для работы с СМС

Компонент: message

Отправка SMS

Функция: send

Адрес: http://api.sms-38.ru/api/message/send/

Параметры запроса:

Параметр Описание Обязательный Формат/Пример
user Ваш логин Да Строка
recipients Получатели Да Строка, список номеров в любом формате разделенных запятой
message Сообщение Да Строка в кодировке UTF-8
sender Имя отправителя Нет Строка (от 5 до 11 символов, латиница, цифры)
test Тестовый режим Нет Число, 0 или 1
sign Подпись запроса Да Строка, 32 символа в нижнем регистре

Параметры успешного ответа:

Параметр Описание Формат/Значение
status Статус Строка, success
recipients Получатели Массив
messages_id Идентификаторы сообщений принятых к отправке Массив
count Количество отправленных сообщений Число
parts Количество частей в сообщении Число
price Цена отправки Число
balance Остаток средств Число
test Флаг тестового режима Число, 1 или 0

 

Проверка статусов сообщений

Функция: status

Адрес: http://api.sms-38.ru/api/message/status/

Параметры запроса:

Параметр Описание Обязательный Формат/Пример
user Ваш логин Да Строка
sign Подпись запроса Да Строка, 32 символа в нижнем регистре
messages_id Список идентификаторов сообщений через запятую Да Строка

Параметры успешного ответа:

Параметр Описание Формат/Значение
status Статус запроса Строка, success
messages Массив статусов сообщений (идентификатор => статус) Ассоциативный массив

Расшифровка статусов сообщения:

Статус Описание
enqueued Ожидает отправки
enroute В пути
accepted Отправлено
delivered Доставлено
expired Истек срок
deleted Удалено
undeliverable Недоставляемо
rejected Отклонено
unknown Неизвестно

 

Ошибки

Параметры ответа при ошибках:

Параметр Описание Формат/Значение
status Статус Строка, error
error Код ошибки Число
message Текст ошибки Строка

Возможные ошибки:

Код Текст Описание
1 invalid user Логин указан некорректно или такого пользователя не существует.
2 invalid signature Некорректная подпись запроса, проверьте свой API KEY и функцию генерирования подписи.
3 empty message Сообщение не передано или пустое.
4 incorrect recipients list Не указаны получатели или указаны, но формат всех телефонов неверен.
5 not enough money Недостаточно средств на счете, пополните баланс.

 

Запрос цены сообщения

Функция: price

Адрес: http://api.sms-38.ru/api/message/price/

Параметры запроса:

Параметр Описание Обязательный Формат/Пример
user Ваш логин Да Строка
sign Подпись запроса Да Строка, 32 символа в нижнем регистре
recipients Номера телефонов Да Строка, список номеров в любом формате разделенных запятой
message Сообщение Да Строка в кодировке UTF-8

Параметры успешного ответа:

Параметр Описание Формат/Значение
status Статус Строка, success
recipients Корректные номера получателей Массив
parts Количество частей в сообщении Число
price Цена отправки Число
balance Остаток средств Число
Главная   |   Заказать Qiwi-Info   |   Тарифы   |   Клиентам   |   Возможности   |   Оферта   |   Контакты   |