| РазноеПодключение выделенных номеров для приема сообщенийВы можете через специальные команды API получать список свободных выделенных номеров для приема SMS-сообщений
и подключать любой номер к своему логину, оплачивая стоимость за остаток дней в текущем месяце. При подключении
выделенного номера вы автоматически соглашаетесь с правилами использования таких номеров.
Для получения списка доступных выделенных номеров необходимо вызвать методом GET или POST следующий адрес:
https://smsc.kz/sys/receive_phones.php?get=1&login=<login>&psw=<password>
Для подключения выделенного номера необходимо вызвать методом GET или POST адрес:
https://smsc.kz/sys/receive_phones.php?buy=1&login=<login>&psw=<password>&phone=<phone>
Для изменения признака продления выделенного номера на следующий месяц необходимо вызвать методом GET или POST адрес:
https://smsc.kz/sys/receive_phones.php?chg=1&login=<login>&psw=<password>&phone=<phone>&noprolong=<noprolong>
Описание параметров, передаваемых Серверу:
| Параметр | Значение
|
|---|
| login | Логин Клиента.
|
|---|
| psw | Пароль Клиента (можно добавить или изменить на данной странице).
|
|---|
| apikey | Специальный API-ключ, используемый для упрощенной авторизации вместо пары "логин+пароль" (можно создать на данной странице).
|
|---|
| phone | Подключаемый номер.
|
|---|
| noprolong | Признак продления выделенного номера на следующий месяц. Данный параметр также возможно указывать при подключении
номера в команде buy.
0 (по умолчанию) – включить автоматическое продление номера.
1 – отключить автоматическое продление номера.
|
|---|
В случае ошибки Сервер возвращает следующую строку:
- ERROR = N (описание)
- При fmt = 1:
0,-N
- При fmt = 2:
<result>
<error>описание</error>
<error_code>N</error_code>
</result> |
- При fmt = 3:
{
"error": "описание",
"error_code": N
} |
N – номер ошибки, может принимать следующие значения:
| Значение | Описание
|
|---|
| 1 | Ошибка в параметрах.
|
|---|
| 2 | Неверный логин или пароль. Также возникает при попытке отправки сообщения с IP-адреса, не входящего в список разрешенных Клиентом (если такой список был настроен Клиентом ранее).
|
|---|
| 3 | Недостаточно средств на счете для аренды номера.
|
|---|
| 4 | IP-адрес временно заблокирован.
|
|---|
| 9 | Попытка отправки более двух одинаковых запросов на получение списка доступных для аренды номеров или подключение номера,
либо изменение свойств выделенного номера в течение минуты.
Данная ошибка возникает также при попытке отправки пятнадцати и более запросов одновременно с разных подключений под одним логином (too many concurrent requests).
|
|---|
В случае успешного запроса Сервер возвращает ответ в виде строки.
Для получения списка доступных номеров:
- при fmt = 0:
phone = <phone>, type = <type>, cost = <cost>, current_cost = <current_cost>, info = <info>
... |
- при fmt = 1:
<phone>,<type>,<cost>,<current_cost>,<info>
... |
- при fmt = 2:
<list>
<receive_phone>
<phone>phone</phone>
<type>type</type>
<cost>cost</cost>
<current_cost>current_cost</current_cost>
<info>info</info>
</receive_phone>
...
</list>
|
- при fmt = 3:
[{
"phone": "<phone>",
"type": <type>,
"cost": "<cost>",
"current_cost": "<current_cost>"
"info": "<info>"
},
...] |
Где:
<phone> – номер телефона.
<type> – тип номера: 1,4 – выделенный виртуальный номер, 2 – номер на услуге SIM-хостинга.
<cost> – стоимость аренды номера за полный месяц.
<current_cost> – стоимость аренды номера за остаток дней до конца текущего месяца.
<info> – название оператора и поддерживаемые типы уведомлений.
Для аренды номера:
- при fmt = 0: cost = <cost>
- при fmt = 1: <cost>
- при fmt = 2:
<phone>
<cost>cost</cost>
</phone>
|
- при fmt = 3:
Где:
<cost> – сумма, списанная со счета Клиента за аренду номера.
Для изменения признака продления номера:
- при fmt = 0,1: OK
- при fmt = 2:
<result>OK</result>
- при fmt = 3:
Примеры:
Получение списка свободных номеров для аренды:
https://smsc.kz/sys/receive_phones.php?get=1&login=alex&psw=123
Подключение номера "79999999999":
https://smsc.kz/sys/receive_phones.php?buy=1&login=alex&psw=123&phone=79999999999
Отключение возможности продления выделенного номера "79999999999" на следующий месяц:
https://smsc.kz/sys/receive_phones.php?chg=1&login=alex&psw=123&phone=79999999999&noprolong=1
Сервер не принимает более двух одинаковых запросов в течение минуты на получение списка свободных
для аренды номеров или подключение номера, либо изменение свойств выделенного номера для снижения нагрузки и защиты
от ошибок и зацикливаний в программе на стороне Клиента.
Передача статусов и сообщений на обработчик КлиентаВ личном кабинете Клиента в "Настройках пользователя" имеется возможность
указания http(s)-адреса (URL) скрипта для обработки статусов доставки сообщений, входящих SMS-сообщений,
а также служебных сообщений (при использовании услуги "Подтверждение номера с помощью звонка") на стороне Клиента. Указанный скрипт будет вызываться Сервером после каждого получения статуса доставки ранее отправленного Клиентом сообщения, после получения входящего SMS-сообщения от абонента или звонка от абонента (при использовании услуги "Подтверждение номера с помощью звонка").
В адресе обработчика можно указать параметр charset для выбора кодировки передаваемых параметров:
?charset=utf-8
?charset=koi8-r
?charset=windows-1251
По умолчанию используется кодировка windows-1251.
Также в адресе обработчика статусов и входящих сообщений можно передавать параметр fmt для указания формата возвращаемых параметров. Возможные значения: fmt=2 (для формата xml) и fmt=3 (для формата json). При передаче параметра fmt кодировка koi8-r не используется.
Для защиты передаваемых данных от подмены в адресе обработчика дополнительно можно указать любой из параметров md5, sha1, crc32,
определяющих алгоритм подсчета контрольного параметра с хешем строки:
"id:phone:status:<секретная строка>" − для статуса доставки
"phone:mes:to:<секретная строка>" − для входящего сообщения
"phone:ts:<секретная строка>" − для подтверждения номера с помощью звонка
в виде:
?md5=<секретная строка>
?sha1=<секретная строка>
?crc32=<секретная строка>
В качестве символов секретной строки можно использовать латинские буквы, цифры, минус и подчеркивание.
Обработчику будет передан соответствующий параметр, в котором секретная строка будет заменена на значение хеша передаваемых данных.
Все параметры передаются методом POST (для fmt=2 и fmt=3 параметры передаются в теле запроса). В случае необходимости передачи параметров,
указанных в URL обработчика методом GET требуется прописать их специальным образом через символ "!" (например, в URL
"https://mysite.ru/!param1¶m2?param3¶m4" параметры param1 и param2 будут переданы методом GET, а param3 и param4 методом POST).
Передаваемые параметры для статуса SMS-сообщения:
| Параметр | Значение
|
|---|
| id | Идентификатор сообщения.
|
|---|
| phone | Номер телефона.
|
|---|
| status | Статус сообщения.
|
|---|
| time | Время изменения статуса (или доставки SMS-сообщения абоненту).
Формат: DD.MM.YY hh:mm:ss (по часовому поясу, указанному в настройках).
|
|---|
| ts | Время изменения статуса в виде штампа в секундах.
|
|---|
| err | Код ошибки, если сообщение не может быть доставлено (список). Передается, если не равен нулю.
|
|---|
| syserr | Дополнительная ошибка от оператора, присутствует не всегда.
|
|---|
| cnt | Количество частей (при отправке SMS-сообщения) либо количество секунд (при голосовом сообщении (звонке)).
|
|---|
| type | Тип сообщения (0 – SMS, 1 – Flash-SMS, 2 – Бинарное SMS, 3 – Wap-push, 4 – HLR-запрос, 5 – Ping-SMS, 6 – MMS, 7 –
Звонок, 10 – Viber, 12 – Соцсети).
|
|---|
| cost | Стоимость сообщения.
|
|---|
| flag | Флаг в виде 2-х байтового числа, содержащий различную информацию о сообщении. Возможны комбинации значений битов разных характеристик.
Биты 0-3 (тип сообщения):
0 (по умолчанию) – SMS.
1 – Flash-SMS.
2 – Бинарное SMS.
3 – Wap-push.
4 – HLR-запрос.
5 – Ping-SMS.
6 – MMS.
7 – Звонок.
8 – E-mail.
10 – Viber.
12 – Соцсети.
Бит 5 – оплата сообщения со второго баланса.
Бит 8 – признак шаблонного сообщения.
Биты 10,9 – тип шаблонного сообщения:
00 - сервисное.
01 - транзакционное.
10 - авторизационное.
11 - рекламное.
|
|---|
| sender | Имя отправителя, отображаемое в телефоне получателя.
|
|---|
| dtmf | Последовательность символов, набираемая абонентом на цифровой клавиатуре во время прослушивания голосового сообщения (звонка).
|
|---|
| cmt | Комментарии клиента, передаваемые при отправке сообщения. В случае возникновения overtime при голосовом сообщении он будет передан
в комментарии отдельной строкой в виде "overtime: mm:ss".
|
|---|
| md5 | MD5-хеш строки "id:phone:status:<секретная строка>". Передается, если был указан в качестве дополнительного параметра
в http(s)-адресе обработчика.
|
|---|
| sha1 | sha1-хеш строки "id:phone:status:<секретная строка>". Передается, если был указан в качестве дополнительного параметра
в http(s)-адресе обработчика.
|
|---|
| crc32 | Контрольная сумма crc32 строки "id:phone:status:<секретная строка>". Передается, если был указан в качестве дополнительного параметра
в http(s)-адресе обработчика.
|
|---|
| Дополнительные параметры для HLR-запросов
|
|---|
| imsi | Уникальный код IMSI SIM-карты абонента.
|
|---|
| msc | Номер сервис-центра оператора, в сети которого находится абонент.
|
|---|
| mcc | Числовой код страны абонента.
|
|---|
| mnc | Числовой код оператора абонента.
|
|---|
| cn | Название страны регистрации абонента.
|
|---|
| net | Название оператора регистрации абонента.
|
|---|
| rcn | Название роуминговой страны абонента при нахождении в чужой сети.
|
|---|
| rnet | Название роумингового оператора абонента при нахождении в чужой сети.
|
|---|
Передаваемые параметры для входящего SMS-сообщения:
| Параметр | Значение
|
|---|
| id | Уникальный идентификатор входящего сообщения, назначаемый Сервером автоматически.
|
|---|
| sms_id | Идентификатор сообщения, на которое получен ответ. Данный параметр отсутствует, если сообщение от абонента было отправлено на выделенный входящий номер либо при указании абонентом префикса "логин, двоеточие и пробел".
|
|---|
| phone | Номер телефона абонента.
|
|---|
| mes | Текст SMS-сообщения.
|
|---|
| to | Входящий номер телефона, на который было отправлено сообщение абонентом.
|
|---|
| smsc | SMS-центр оператора, от которого было получено входящее сообщение.
|
|---|
| sent | Время отправки сообщения абонентом в виде штампа в секундах.
|
|---|
| time | Время получения сообщения Сервером в виде штампа в секундах.
|
|---|
| md5 | MD5-хеш строки "phone:mes:to:<секретная строка>". Передается, если был указан в качестве дополнительного параметра
в http(s)-адресе обработчика.
|
|---|
| sha1 | sha1-хеш строки "phone:mes:to:<секретная строка>". Передается, если был указан в качестве дополнительного параметра
в http(s)-адресе обработчика.
|
|---|
| crc32 | Контрольная сумма crc32 строки "phone:mes:to:<секретная строка>". Передается, если был указан в качестве дополнительного параметра
в http(s)-адресе обработчика.
|
|---|
Передаваемые параметры при использовании услуги "Подтверждение номера с помощью звонка":
| Параметр | Значение
|
|---|
| waitcall | 1 – признак служебного сообщения для услуги "Подтверждение номера с помощью звонка".
|
|---|
| phone | Номер телефона абонента, с которого поступил звонок.
|
|---|
| ts | Время звонка.
|
|---|
| md5 | MD5-хеш строки "phone:ts:<секретная строка>". Передается, если был указан в качестве дополнительного параметра
в http(s)-адресе обработчика.
|
|---|
| sha1 | sha1-хеш строки "phone:ts:<секретная строка>". Передается, если был указан в качестве дополнительного параметра
в http(s)-адресе обработчика.
|
|---|
| crc32 | Контрольная сумма crc32 строки "phone:ts:<секретная строка>". Передается, если был указан в качестве дополнительного параметра
в http(s)-адресе обработчика.
|
|---|
Дополнительные параметры, передаваемые при использовании функции голосового меню в звонках:
| Параметр | Значение
|
|---|
| calltime | Время разговора, по истечении которого была нажата клавиша на цифровой клавиатуре телефона абонента или общее время разговора.
|
|---|
| callmenu | Последовательность клавиш цифровой клавиатуры телефона, нажатые абонентом во время прохождения по голосовому меню.
|
|---|
| ringtime | Время ожидания поднятия трубки абонентом.
|
|---|
Помимо описанных выше стандартных параметров Сервер также будет передавать методом POST все параметры,
указанные в http(s)-адресе обработчика после знака "?".
Для различия статуса сообщения, входящего SMS-сообщения или служебного сообщения (при использовании услуги "Подтверждение номера с помощью звонка") в одном обработчике можно выполнить проверку на наличие параметра mes (для входящего сообщения) и waitcall (для услуги подтверждения номера):
if (isset($_POST["mes"])) {
// message
}
elseif (isset($_POST["waitcall"])) {
// confirmation
}
else {
// status
}
Пересылка статусов на обработчик Клиента осуществляется только при отправке сообщений
по протоколам HTTP/HTTPS, SMTP или SMPP. При отправке сообщений с личного кабинета передача статусов на обработчик Клиента
не происходит.
В случае если от обработчика Клиента вернется ответ с кодом ошибки, отличным от 200 или 404, то Сервер с определенной периодичностью будет повторять запрос на обработчик (1 запрос каждые 4 минуты, всего 50 попыток). Подключение антиспам проверки (captcha) к сайтуИногда возникает необходимость отправки сообщений со своего сайта по запросу пользователей, и в таких случаях для исключения автоматизированных
спам-рассылок с помощью роботов можно легко внедрить антиспам проверку, используя наш сервис.
Для этого достаточно на форме для отправки сообщений разместить специальный код для вывода картинки (captcha) и поля для ввода кода:
Код с картинки <img src="https://smsc.kz/sys/imgcode.php?1.1" onclick="src+=1" width="50" height="18" border="1">
<input type="text" size="9" name="code">
и передать его с другими данными формы в соответствующий скрипт отправки сообщений в качестве значения параметра imgcode.
Также с данным параметром необходимо передавать значение IP-адреса пользователя, которому отображалась картинка в качестве значения параметра userip.
Примеры:
Пример скрипта для отправки сообщений, использующего код с картинки (captcha), полученный с формы:
include_once "smsc_api.php";
if ($_POST["sendsms"]) {
$r = send_sms($_POST["phone"], "Ваш код для регистрации на сайте mysite.com 123321.", 0, 0, 0, 0, false, "imgcode=".$_POST["code"]."&userip=".$_SERVER["REMOTE_ADDR"]);
if ($r[1] > 0)
echo "<script>alert('Сообщение отправлено на номер ".$_POST["phone"]."')</script>";
elseif ($r[1] == -10)
echo "<script>alert('Вы ввели неверный код с картинки!')</script>";
}
Подтверждение номера телефона с помощью звонкаПри различного рода операциях, таких как восстановление паролей, авторизация в общественных сетях Wi-Fi, подтверждение денежных переводов, вход в личный кабинет и так далее требуется отправка аутентификационных данных. Используя наш API можно организовать процедуру подтверждения номера телефона с помощью звонка самим абонентом.
Для создания запроса на получение номера телефона, по которому абонент должен будет осуществить подтверждающий звонок, необходимо вызвать методом GET или POST адрес:
https://smsc.kz/sys/wait_call.php?login=<login>&psw=<password>&phone=<phone>
Серверу передаются следующие параметры:
| Параметр | Значение
|
|---|
| login | Логин Клиента.
|
|---|
| psw | Пароль Клиента (можно добавить или изменить на данной странице).
|
|---|
| apikey | Специальный API-ключ, используемый для упрощенной авторизации вместо пары "логин+пароль" (можно создать на данной странице).
|
|---|
| phone | Номер телефона абонента, с которого будет осуществлен подтверждающий звонок.
|
|---|
В случае ошибки Сервер возвращает следующую строку:
- ERROR = N (описание)
- При fmt = 1:
0,-N
- При fmt = 2:
<result>
<error>описание</error>
<error_code>N</error_code>
</result> |
- При fmt = 3:
{
"error": "описание",
"error_code": N
} |
N – номер ошибки, может принимать следующие значения:
| Значение | Описание
|
|---|
| 1 | Ошибка в параметрах.
|
|---|
| 2 | Неверный логин или пароль. Также возникает при попытке отправки сообщения с IP-адреса, не входящего в список разрешенных Клиентом (если такой список был настроен Клиентом ранее).
|
|---|
| 3 | Недостаточно средств на счете Клиента.
|
|---|
| 4 | IP-адрес временно заблокирован.
|
|---|
| 5 | Указанный номер телефона абонента находится в черном списке Клиента.
|
|---|
| 6 | Не удалось получить стоимость услуги из-за настроек в личном кабинете Клиента (разрешенные номера, время отправки и т.п.).
|
|---|
| 9 | Попытка отправки более пятидесяти одинаковых запросов на получение номера телефона для подтверждения в течение минуты.
Данная ошибка возникает также при попытке отправки пятнадцати и более запросов одновременно с разных подключений под одним логином (too many concurrent requests).
|
|---|
В случае успешного запроса Сервер возвращает ответ в виде строки.
- при fmt = 0:
phone = <phone>, all_phones = <all_phones>
- при fmt = 1 (первым идет номер, на который необходимо позвонить абоненту):
<all_phones>
- при fmt = 2:
<result>
<phone>phone</phone>
<all_phones>
<phone>phone</phone>
...
<phone>phone</phone>
</all_phones>
</result> |
- при fmt = 3:
{
"phone": "<phone>",
"all_phones": [
<phone>",
...
"<phone>"
]
} |
Где:
<phone> – номер телефона, на который в течение 15 минут должен осуществить звонок абонент для подтверждения своего номера телефона.
<all_phones> – список всех возможных номеров телефонов, один из которых был назначен системой для звонка абонента (в зависимости от страны).
После звонка абонента Сервер зафиксирует факт звонка в виде входящего сообщения с текстом "[waitcall]" и отправит на обработчик Клиента всю необходимую информацию о данном звонке.
Сервер не принимает более пятидесяти одинаковых запросов на получение номера телефона для подтверждения в течение минуты для снижения нагрузки и защиты от ошибок и зацикливаний в программе на стороне Клиента.
Действия с отложенными заданиямиДля снижения нагрузки на Сервер при выгрузке большого пакета отправленных сообщений в системе был реализован механизм отложенных заданий. Данный механизм с определенной периодичностью производит выборку активных заданий на выгрузку пакетов сообщений и выполняет их. Это позволяет не только снизить нагрузку на Сервер, но и исключить задержки с формированием и выгрузкой пакетов сообщений в браузере Клиента.
Для получения списка отложенных заданий необходимо вызвать методом GET или POST адрес:
https://smsc.kz/sys/downloads.php?login=<login>&psw=<password>&get_list=1
Для получения файла задания с отправленными сообщениями необходимо вызвать методом GET или POST адрес:
https://smsc.kz/sys/downloads.php?login=<login>&psw=<password>&get_file=1&id=<id>
или
https://smsc.kz/sys/downloads.php?login=<login>&psw=<password>&get_file=1&name=<name>
Серверу передаются следующие параметры:
| Параметр | Значение
|
|---|
| login | Логин Клиента.
|
|---|
| psw | Пароль Клиента (можно добавить или изменить на данной странице).
|
|---|
| apikey | Специальный API-ключ, используемый для упрощенной авторизации вместо пары "логин+пароль" (можно создать на данной странице).
|
|---|
| cnt | Количество отложенных заданий, возвращаемых Сервером.
|
|---|
| after_id | Данный параметр указывает Серверу на необходимость возврата в ответе списка заданий с идентификаторами, следующими за after_id.
|
|---|
| id | Загрузить файл задания с идентификатором, равным id.
|
|---|
| name | Загрузить файл задания с именем name.
|
|---|
В случае ошибки Сервер возвращает следующую строку:
- ERROR = N (описание)
- При fmt = 1:
0,-N
- При fmt = 2:
<result>
<error>описание</error>
<error_code>N</error_code>
</result> |
- При fmt = 3:
{
"error": "описание",
"error_code": N
} |
N – номер ошибки, может принимать следующие значения:
| Значение | Описание
|
|---|
| 1 | Ошибка в параметрах.
|
|---|
| 2 | Неверный логин или пароль. Также возникает при попытке отправки сообщения с IP-адреса, не входящего в список разрешенных Клиентом (если такой список был настроен Клиентом ранее).
|
|---|
| 4 | IP-адрес временно заблокирован.
|
|---|
| 5 | Отложенная задача или файл для скачивания не найдены в системе.
|
|---|
| 9 | Попытка отправки более трех одинаковых запросов на получение списка заданий или на скачивание файла в течение минуты.
Данная ошибка возникает также при попытке отправки пятнадцати и более запросов одновременно с разных подключений под одним логином (too many concurrent requests).
|
|---|
В случае успешного запроса Сервер возвращает ответ в виде строки.
При получении списка отложенных заданий:
- при fmt = 0:
id = <id>, name = <name>, status = <status>, created = <created>, time = <time>, file = <file>
- при fmt = 1:
<id>,<name>,<status>,<created>,<time>,<file>
- при fmt = 2:
<list>
<task>
<id>id</id>
<name>name</name>
<status>status</status>
<created>created</created>
<time>time</time>
<file>file</file>
</task>
...
</list> |
- при fmt = 3:
[{
"id": id,
"name": "name",
"status": "status",
"created": "created",
"time": "time",
"file": "file"
},
...] |
Где:
<id> – идентификатор отложенного задания.
<name> – название задания.
<status> – статус задания (0 - ожидает выполнения, 1 - выполняется, 2 - выполнено, 3 - отменено, 4 - ошибка выполнения).
<created> – дата создания задания.
<time> – время запуска задания.
<file> – название файла задания.
После присвоения отложенному заданию статуса 2 (выполнено) появится возможность скачать файл с пакетом отправленных сообщений в формате csv.
Сервер не принимает более трех одинаковых запросов на получение списка заданий или на скачивание файла в течение минуты для снижения нагрузки и защиты от ошибок и зацикливаний в программе на стороне Клиента.
|
РАЗНОЕ
