Содержание
- Описание
- Отправка сообщения
- Получение стоимости
- Проверка статуса
- Проверка состояния баланса
Описание
Файл описания методов веб-сервиса: http://billing.smstraf.ru/sys/soap.php?wsdl
В сервисе доступны методы для отправки сообщений и получения стоимости, проверки статусов и состояния баланса.
Все параметры должны передаваться в кодировке UTF-8.
Отправка сообщения
Для отправки SMS-сообщений используются методы send_sms и send_sms2.
В методе send_sms2 имеется возможность добавления дополнительных параметров.
$client = new SoapClient('http://billing.smstraf.ru/sys/soap.php?wsdl');
$ret = $client->send_sms(array('login'=>'alex', 'psw'=>'123', 'phones'=>'79999999999', 'mes'=>'Hello world!', 'id'=>'', 'sender'=>'ivan', 'time'=>0));
Описание параметров, передаваемых Серверу:
| Параметр | Значение
|
|---|
| login | Логин Клиента.
|
|---|
| psw | Пароль Клиента или MD5-хеш пароля в нижнем регистре.
|
|---|
| phones | Номер или разделенный запятой или точкой с запятой список номеров мобильных телефонов в международном формате,
на которые отправляется сообщение. Номера могут передаваться без знака "+".
Если номер передан без знака "+", то он может быть исправлен автоматическим форматированием
и приведен к правильному международному формату. Таким образом, некоторые
ошибки при вводе номеров телефонов могут быть исправлены автоматически.
Для отключения автоисправления передайте номер со знаком "+".
Также можно отправлять сообщение на группу номеров, указав специальный код "G<номер группы>".
Сообщение будет отправлено на все номера, принадлежащие данной группе. Для e-mail сообщения передается список e-mail адресов
получателей.
|
|---|
| mes | Текст отправляемого сообщения. Максимальный размер – 800 символов. Сообщение при
необходимости будет разбито на несколько SMS, отправленных абоненту и оплаченных по отдельности. Размер одного
SMS – 160 символов в латинице или 70 символов в кириллице. При разбивке сообщения на несколько SMS в каждую часть
добавляется заголовок для объединения частей в одно сообщение на телефоне получателя, и максимальная длина становится
67 для кириллицы и 153 для латинских букв. В текст сообщения можно добавлять комментарии,
предназначенные для просмотра отправителем истории в личном кабинете.
|
|---|
| id | Идентификатор сообщения. Назначается Клиентом. Служит для дальнейшей идентификации сообщения.
Если не указывать, то будет назначен автоматически. Не обязательно уникален. В случае 2-х одинаковых идентификаторов
по запросу статуса будет возвращен статус последнего сообщения. Идентификатор представляет собой 32-битное число в диапазоне
от 1 до 2147483647, либо строку длиной до 40 символов, состоящую из латинских букв, цифр и символов ".-_".
|
|---|
| sender | Имя отправителя, отображаемое в телефоне получателя.
Разрешены английские буквы, цифры, пробел и некоторые символы. Длина – 11 символов или 15 цифр.
Все имена регистрируются в личном кабинете. Для отключения Sender ID по умолчанию необходимо в качестве имени передать
пустую строку.
|
|---|
| tinyurl | Автоматически сокращать ссылки в сообщениях. Позволяет заменять ссылки в тексте
сообщения на короткие для сокращения длины, а также для отслеживания количества переходов на
этой странице.
0 (по умолчанию) – оставить ссылки в тексте сообщения без изменений.
1 – сократить ссылки.
|
|---|
| time | Время отправки SMS-сообщения абоненту.
Форматы:
- DDMMYYhhmm или DD.MM.YY hh:mm.
- h1-h2. Задает диапазон времени в часах. Если текущее время меньше h1, то SMS-сообщение
будет отправлено абоненту при наступлении времени h1, если текущее время попадает в промежуток от h1 до h2,
то сообщение будет отправлено немедленно, в другом случае отправка будет выполнена на следующий день при
достижении времени h1. Данная функция, например, полезна для того, чтобы не допустить получение SMS-сообщений
абонентами в ночное время.
- 0ts, где ts – timestamp, время в секундах, прошедшее с 1 января 1970 года.
- +m. Задает относительное смещение времени от текущего в минутах. Символ + должен кодироваться как %2B в http-запросе.
Если time = 0 (по умолчанию), то сообщение будет отправлено немедленно.
|
|---|
| query | Строка дополнительных параметров (только в send_sms2),
передаваемых в формате: 'параметр_1=значение_1&параметр_2=значение_2'.
|
|---|
| Дополнительные параметры передаваемые в 'query'
|
|---|
| tz | Часовой пояс, в котором задается параметр time. Указывается относительно московского времени.
Параметр tz может быть как положительным, так и отрицательным. Если tz равен 0, то будет использован московский часовой
пояс, если же параметр tz не задан, то часовой пояс будет взят из настроек Клиента.
|
|---|
| period | Промежуток времени, в течение которого необходимо отправить рассылку. Представляет собой число
в диапазоне от 0.1 до 720 часов. Применяется совместно с параметром freq. Данный параметр позволяет растянуть рассылку во
времени для постепенного получения SMS-сообщений абонентами.
|
|---|
| freq | Интервал или частота, с которой нужно отправлять SMS-рассылку на очередную группу номеров. Количество
номеров в группе рассчитывается автоматически на основе параметров period и freq. Задается в промежутке от 1 до 1440 минут.
Без параметра period параметр freq игнорируется.
|
|---|
| flash | Признак Flash сообщения, отображаемого сразу на экране телефона.
0 (по умолчанию) – обычное сообщение.
1 – Flash сообщение.
|
|---|
| bin | Признак бинарного сообщения.
0 (по умолчанию) – обычное сообщение.
1 – бинарное сообщение. В http-запросе необходимо закодировать с помощью функции urlencode.
2 – бинарное сообщение, представленное в виде шестнадцатеричной строки (hex).
Бинарное сообщение передается вместе с UDH заголовком в начале в параметре mes, в котором первый байт задает длину заголовка.
Чтобы передать бинарное сообщение без UDH заголовка, укажите нулевой байт в начале сообщения (00 в hex).
Для возможности передачи параметров pid и dcs необходимо в конец бинарного сообщения добавить специальную комбинацию
"\n~~~\n" (перевод строки, 3 символа тильды и снова перевод строки) и затем текст "pid: значение1, dcs: значение2" с точным сохранением
пробелов.
|
|---|
| push | Признак wap-push сообщения, с помощью которого можно отправить интернет-ссылку на телефон.
0 (по умолчанию) – обычное сообщение.
1 – wap-push сообщение. В параметре mes необходимо передать ссылку и заголовок через перевод строки.
|
|---|
| hlr | Признак HLR-запроса для получения информации о номере из базы оператора без отправки реального SMS.
0 (по умолчанию) – обычное сообщение.
1 – HLR-запрос. Будет выполнен HLR-запрос для каждого номера телефона в списке. Параметр mes не используется.
|
|---|
| ping | Признак специального SMS, не отображаемого в телефоне, для проверки номеров на доступность в реальном времени по статусу доставки.
0 (по умолчанию) – обычное сообщение.
1 – ping-sms. Будет отправлено Ping-SMS на каждый номер телефона в списке.
Параметр mes не используется.
|
|---|
| mms | Признак MMS-сообщения, с помощью которого можно передавать текст (txt), изображения различных форматов (jpg, gif, png),
музыку (wav, amr, mp3, mid) и видео (mp4, 3gp). Файлы передаются в теле http-запроса.
0 (по умолчанию) – обычное сообщение.
1 – MMS-сообщение. Будет отправлено MMS на каждый номер телефона в списке.
|
|---|
| mail | Признак e-mail сообщения. Файлы, прикрепляемые к сообщению, передаются методом POST в теле http-запроса.
0 (по умолчанию) – обычное сообщение.
1 – e-mail сообщение.
|
|---|
| call | Признак голосового сообщения. При формировании голосового сообщения можно передавать как текст, так и прикреплять файлы.
Файлы, добавляемые к сообщению, должны передаваться методом POST в теле http-запроса.
0 (по умолчанию) – обычное сообщение.
1 – голосовое сообщение.
|
|---|
| voice | Голос, используемый для озвучивания текста (только для голосовых сообщений).
m (по умолчанию) – мужской голос.
m2 – мужской альтернативный голос.
w – женский голос.
w2 – женский альтернативный голос 1.
w3 – женский альтернативный голос 2.
w4 – женский альтернативный голос 3.
|
|---|
| param | Разделенный запятой список параметров для голосового сообщения в формате "param=w,i,n".
Здесь:
- w – время ожидания поднятия трубки абонентом после начала звонка в секундах. Если в течение указанного времени абонент не поднимет трубку,
то звонок уйдет на повтор с ошибкой "абонент занят". Рабочий диапазон значений параметра от 10 до 35, но можно указывать интервал от 0 до 99
(в случае, если значение меньше 10, то оно будет приведено к 10, аналогично для верхней границы).
- i – интервал повтора, то есть промежуток времени, по истечении которого произойдет повторный звонок (в секундах). Рабочий диапазон параметра
от 10 до 999 (в случае, если значение меньше 10, то оно будет приведено к 10).
- n – общее количество попыток дозвона. Рабочий диапазон значений от 1 до 9 (0 будет приведен к 1).
При указании значения любого параметра, отличного от возможных, будут использованы значения всех параметров по умолчанию.
|
|---|
| subj | Тема MMS или e-mail сообщения. При отправке e-mail указание темы, текста и адреса отправителя обязательно. Для MMS обязательным
является указание темы или текста. Если не указать тему MMS, то в ее качестве будет использовано имя отправителя, переданное в запросе или
используемое по умолчанию.
|
|---|
| cost | Признак необходимости получения стоимости рассылки.
0 (по умолчанию) – обычная отправка.
1 – получить стоимость рассылки без реальной отправки.
2 – обычная отправка, но добавить в ответ стоимость выполненной рассылки.
3 – обычная отправка, но добавить в ответ стоимость и новый баланс Клиента.
|
|---|
| list | Список номеров телефонов и соответствующих им сообщений, разделенных двоеточием или точкой с запятой и
представленный в виде:
phones1:mes1
phones2:mes2
...
Строки разделяются через символ новой строки (%0A). В качестве phones можно указать несколько номеров телефонов через
запятую. Если в сообщении mes требуется передать символ новой строки, то укажите его через \n.
Параметр list позволяет выполнять множественную рассылку с разными сообщениями на несколько телефонов одним
http-запросом. Сообщениям в запросе присваивается единый идентификатор. Весь параметр должен быть закодирован с
помощью функции urlencode.
|
|---|
| valid | Срок "жизни" SMS-сообщения. Определяет время, в течение которого оператор будет пытаться доставить
сообщение абоненту. Диапазон от 1 до 24 часов. Также возможно передавать время в формате чч:мм в диапазоне от 00:01 до 24:00.
|
|---|
| maxsms | Максимальное количество SMS, на которые может разбиться длинное сообщение.
Слишком длинные сообщения будут обрезаться так, чтобы не переполнить количество SMS, требуемых
для их передачи. Этим параметром вы можете ограничить максимальную стоимость сообщений,
так как за каждое SMS снимается отдельная плата.
|
|---|
| imgcode | Значение буквенно-цифрового кода, введенного с "captcha" при использовании антиспам проверки.
Данный параметр должен использоваться совместно с параметром userip.
|
|---|
| userip | Значение IP-адреса, для которого будет действовать лимит на максимальное количество сообщений с одного IP-адреса в сутки,
установленный в настройках личного кабинета в пункте "Лимиты и ограничения".
|
|---|
| err | Признак необходимости добавления в ответ сервера списка ошибочных номеров.
0 (по умолчанию) – не добавлять список (обычный ответ сервера).
1 – в ответ добавляется список ошибочных номеров телефонов с соответствующими статусами.
|
|---|
| op | Признак необходимости добавления в ответ сервера информации по каждому номеру.
0 (по умолчанию) – не добавлять список (обычный ответ сервера).
1 – в ответ добавляется список всех номеров телефонов с соответствующими статусами.
|
|---|
| pp | Осуществляет привязку Клиента в качестве реферала к определенному ID партнера.
При передаче данного параметра в виде "pp=<ID партнера>" Клиент с логином login становится рефералом партнера
с ID <ID партнера>. Сделать рефералом можно только нового Клиента, зарегистрированного в сервисе не более месяца назад
и имеющего не более 1000 отправленных сообщений, который еще не является рефералом другого партнера. Данный параметр
позволяет устанавливать Клиента в качестве реферала из своих сервисов и программ, где нет возможности зарегистрировать
Клиента по реферальной ссылке.
|
|---|
Возвращаемые параметры:
| Значение | Описание
|
|---|
| id | Идентификатор сообщения, переданный Клиентом или назначенный Сервером автоматически.
|
|---|
| balance | Новый баланс Клиента.
|
|---|
| cost | Стоимость рассылки.
|
|---|
| cnt | Количество отправленных SMS, вычисляемое как количество SMS в сообщении, умноженное на количество получателей.
|
|---|
| error | Код ошибки.
|
|---|
Код ошибки может принимать следующие значения:
| Значение | Описание
|
|---|
| 1 | Ошибка в параметрах.
|
|---|
| 2 | Неверный логин или пароль.
|
|---|
| 3 | Недостаточно средств на счету Клиента.
|
|---|
| 4 | IP-адрес временно заблокирован из-за частых ошибок в запросах. Подробнее
|
|---|
| 5 | Неверный формат даты.
|
|---|
| 6 | Сообщение запрещено (по тексту или по имени отправителя).
|
|---|
| 7 | Неверный формат номера телефона.
|
|---|
| 8 | Сообщение на указанный номер не может быть доставлено.
|
|---|
| 9 | Отправка более одного одинакового запроса на передачу SMS-сообщения в течение минуты.
|
|---|
Сервер не принимает более одного одинакового запроса на отправку SMS-сообщений в течение
минуты для защиты от ошибок и зацикливаний в программе на стороне Клиента для того, чтобы снизить нагрузку и не расходовать
средства Клиента, а также не допустить многократной отправки сообщения одному абоненту.
Сервер также блокирует отправку более 50 сообщений одному абоненту, которые были отправлены с перерывом
между сообщениями менее 2-х минут, для защиты от флуда и лишнего списания средств со счета Клиента,
так как многие операторы не пропускают большое количество сообщений одному абоненту за короткий промежуток времени.
Получение стоимости
Для получения стоимости SMS можно использовать метод get_sms_cost или get_sms_cost2.
В get_sms_cost2 есть возможность добавлять дополнительные параметры.
$client = new SoapClient ('http://billing.smstraf.ru/sys/soap.php?wsdl');
$ret = $client->get_sms_cost(array('login'=>'alex', 'psw'=>'123', 'phones'=>'79999999999', 'mes'=>'Hello world!'));
Серверу передаются следующие параметры:
| Параметр | Значение
|
|---|
| login | Логин Клиента.
|
|---|
| psw | Пароль Клиента или MD5-хеш пароля в нижнем регистре.
|
|---|
| phones | Номер телефона.
|
|---|
| mes | Идентификатор сообщения.
|
|---|
| query | Строка дополнительных параметров (только в get_sms_cost2),
передаваемых в формате: 'параметр_1=значение_1&параметр_2=значение_2'.
Подробное описание параметров смотрите в описании метода send_sms.
|
|---|
Возвращаемые параметры:
| Параметр | Значение
|
|---|
| cost | Cтоимость рассылки.
|
|---|
| cnt | Количество отправленных SMS, вычисляемое как количество SMS в сообщении, умноженное на количество получателей.
|
|---|
| error | Код ошибки.
|
|---|
Проверка статуса
Для проверки статуса доставки SMS используются методы get_status и get_status2.
В методе get_status2 имеется возможность добавления дополнительных параметров.
$client = new SoapClient ('http://billing.smstraf.ru/sys/soap.php?wsdl');
$ret = $client->get_status(array('login'=>'alex', 'psw'=>'123', 'phone'=>'79999999999', 'id'=>'999', 'all'=>'0'));
Серверу передаются следующие параметры:
| Параметр | Значение
|
|---|
| login | Логин Клиента.
|
|---|
| psw | Пароль Клиента или MD5-хеш пароля в нижнем регистре.
|
|---|
| phone | Номер телефона.
|
|---|
| id | Идентификатор сообщения.
|
|---|
| all | 0 – (по умолчанию) получить статус сообщения в обычном формате.
1 – получить полную информацию об отправленном сообщении.
2 – добавить в информацию о сообщении данные об операторе и регионе абонента.
|
|---|
| query | Строка дополнительных параметров (только в get_status2),
передаваемых в формате: 'параметр_1=значение_1&параметр_2=значение_2'.
|
|---|
Возвращаемые параметры:
| Параметр | Значение
|
|---|
| status | Код статуса (список).
|
|---|
| last_date | Дата последнего изменения статуса. Формат DD.MM.YYYY hh:mm:ss.
|
|---|
| err | Код ошибки, если сообщение не может быть доставлено (список).
|
|---|
| error | Код ошибки, если статус не может быть запрошен.
|
|---|
| all = 1
|
|---|
| send_date | Дата отправки сообщения (формат DD.MM.YYYY hh:mm:ss).
|
|---|
| phone | Номер телефона абонента.
|
|---|
| cost | Стоимость сообщения.
|
|---|
| sender_id | Имя отправителя.
|
|---|
| status_name | Название статуса.
|
|---|
| message | Текст сообщения.
|
|---|
| all = 2
|
|---|
| operator | Название оператора абонента.
|
|---|
| region | Регион регистрации номера абонента.
|
|---|
Код ошибки (error) может принимать следующие значения:
| Значение | Описание
|
|---|
| 1 | Ошибка в параметрах.
|
|---|
| 2 | Неверный логин или пароль.
|
|---|
| 3 | Сообщение не найдено.
|
|---|
| 4 | IP-адрес временно заблокирован.
|
|---|
| 9 | Попытка отправки более пяти запросов на получение статуса одного и того же сообщения в течение минуты.
|
|---|
Проверка состояния баланса
Для запроса баланса используйте метод get_balance.
$client = new SoapClient ('http://billing.smstraf.ru/sys/soap.php?wsdl');
$ret = $client->get_balance(array('login'=>'alex', 'psw'=>'123'));
Серверу передаются следующие параметры:
| Параметр | Значение
|
|---|
| login | Логин Клиента.
|
|---|
| psw | Пароль Клиента или MD5-хеш пароля в нижнем регистре.
|
|---|
В ответ возвращается текущий баланс balance и номер ошибки error.
Номер ошибки может принимать следующие значения:
| Значение | Описание
|
|---|
| 0 | Ошибок нет.
|
|---|
| 1 | Ошибка в параметрах.
|
|---|
| 2 | Неверный логин или пароль.
|
|---|
| 4 | IP-адрес временно заблокирован.
|
|---|
| 9 | Попытка отправки более десяти запросов на получение баланса в течение минуты.
|
|---|
|
