API для SMS-рассылок

Отправка SMS (метод push_msg)

Отправка SMS сообщений

Для быстрого перехода используйте содержание:

1. Как включить API-шлюз.
2. Список всех параметров и их описание.
3. Пример HTTP запроса, который можно выполнить в браузере.
4. Примеры ответов сервера.
5. Коды ошибок.
6. Отложенная отправка SMS по московскому времени.
7. Отложенная отправка SMS по местному времени абонента



Вызов методов осуществляется посредством GET или POST HTTP-запросов к любому серверу:

Адрес сервера: http://api.sms-prosto.ru
Порт (протокол): 80 (HTTP)
Метод: GET или POST
Кодировка для запроса: UTF-8
Адрес сервера: https://ssl.bs00.ru
Порт (протокол): 443 (HTTPS)
Метод: GET или POST
Кодировка для запроса: UTF-8


В GET- или POST-переменных запроса передаются аргументы с именами:

Аргументы:

method - вызываемый метод.
- набор переменных, зависящий от конкретного метода (см. таблицу ниже).
format - (необязательный) формат выходных данных (XML, JSON), без указания этого параметра, по умолчанию данные выдаются в формате XML.

Все методы возвращают массив аргументов с именами:


msg - сообщение о выполнении действия в виде массива с ключами:
err_code - числовой код ошибки (0 - нет ошибок),
text - текстовое сообщение,
type - тип сообщения (message – нет ошибок, notice и error – ошибки).
data - запрашиваемые данные в виде массива.


1 Как включить API-шлюз

Вы можете проверить состояние API-шлюза на странице https://lk.sms-prosto.ru/settings.php?p=api. Если он не включен - напишите в поддержку на почту support@sms-prosto.ru с просьбой включить. Также рекомендуется указать примерный текст сообщений, который планируется отправлять по API, данная информация необходима, чтобы Вам выставили корректные приоритеты на отправляемые SMS сообщения, это позволит доставлять SMS через соответствующие каналы значительно быстрее обычных SMS сообщений.

Если Вы планируете для отправки SMS по API использовать apikey (параметр key) в место логина и пароля, его также необходимо запросить в Поддержке.




2 Список всех параметров

Параметр Тип (значение) Наличие в запросе Описание Пример
method push_msg Обязательный Инициирует отправку SMS method=push_msg
format json, JSON, xml, XML Не обязательный Значение json запрашивает ответ в формате json, в противном случае ответ будет в XML. format=json
email String (логин в системе) Обязательный, если авторизация осуществляется с помощью пары логин/пароль Необходим для авторизации. email=myemail@yandex.ru
password String (пароль в системе) Обязательный, если авторизация осуществляется с помощью пары логин/пароль Необходим для авторизации. password=myPassWord
key String (получить key можно в поддержке) Обязательный, если авторизация осуществляется с помощью key. Необходим для авторизации. В данном варианте параметры email и password передавать не нужно. key=Hfe8dn3SdgkdHGDer
text String Обязательный Максимальная длина 11 сегментов (737 символов кирилицей, либо 1683 латиницей), длинее передавать не рекомендуется, т.к. SMS может разбится на части, либо доставка будет не полностью text=Это текст СМС
phone Int Обязательный В любом формате 7ХХХYYYххyy, 8ХХХYYYххyy, +7ХХХYYYххyy, 7(ХХХ)YYY-хх-yy и т.д. phone=79162821111
sender_name String (max 11) Обязательный Имя отправителя, максимальная длина 11 символов. https://lk.sms-prosto.ru/help.php?faq=12. Также не забудьте согласовать свой отправитель с Мегафон и МТС, https://lk.sms-prosto.ru/help.php?faq=41. sender_name=MyBrandName
priority Int Не обязательный Приоритет отправляемой СМС. Если будет не указан, по умолчанию присваивается priority=2.

Допустимые значения:
1-только для СМС кодов и одиночных уведомлений требующих мгновенной доставки (например, "Ваша машина подана, выходите.", "Введите код: 2233");

2-для быстрой доставки одиночных уведомлений (Например, "Вы записаны на прием на 15:00", "Вы отменили запись на прием");

3 - Прочие уведомления, которые рассылаются в цикле небольшому количеству абонентов (например, "Ваш заказ доставлен, не забудьте зайти на почту");

4 - Массовые рассылки (например, "У нас скидки, акции!!! Только до 31 января!").

Важно! При злоупотреблении приоритетами при отправке СМС, Ваш приоритет может быть понижен на нашей стороне.
priority=2
external_id Int,String Не обязательный Любое значение, id сообщения на Вашей стороне. Уникальность этих значений не проверяется на нашей стороне. При получении статусов доставки https://lk.sms-prosto.ru/help.php?faq=48#auto-msg-report, в параметре external_id будет передано Ваше значение. Используется для более удобной идетификации сообщения на Вашей стороне.

Допустимые значения:
Int
1234567890

String, UUID
123e4567-e89b-12d3-a456-426655440000
external_id=12002457


3 Пример HTTP запроса, который Вы можете выполнить в браузере



/* Пример 1 (Используется Логин и Пароль от сервиса) */

http://api.sms-prosto.ru/?method=push_msg&email=YOUR_LOGIN&password=YOUR_PASSWORD&text=SMS_TEXT&phone=SMS_PHONE_NUMBER_OF_THE_RECIPIENT&sender_name=MyBrandName




/* Пример 2 (Используется API_KEY) */

http://api.sms-prosto.ru/?method=push_msg&key=YOUR_API_KEY&text=SMS_TEXT&phone=SMS_PHONE_NUMBER_OF_THE_RECIPIENT&sender_name=MyBrandName

YOUR_LOGIN - Логин в системе (Е-майл)
YOUR_PASSWORD - Пароль (получаем при регистрации в системе)
YOUR_API_KEY – API Key, который можно использовать вместо Логина и Пароля
SMS_TEXT - Текст SMS сообщения
SMS_PHONE_NUMBER_OF_THE_RECIPIENT - Номер телефона получателя SMS, в любом формате
MyBrandName - Буквенное имя отправителя



4 Примеры ответа сервера

Пример XML ответа, в случае ошибки


	/* XML */
	<response>
		<msg>
			<err_code>5</err_code>
			<text>Неизвестный метод</text>
		    <type>error</type>
		</msg>
	<data/>
	</response>

Пример JSON ответа, в случае ошибки


	/* JSON */
	{
	  "response": {
		"msg":{
		   "err_code":"5",
		   "text":"Неизвестный метод",
		   "type":"error"
		},
		"data":null
	  }
	}

Пример XML ответа, в случае успешной отправки SMS


	/* XML */
	<response>
		<msg>
			<err_code>0</err_code>
			<text>OK</text>
		    <type>message</type>
		</msg>
		<data>
			<id>21528183</id>
			<credits>0.60</credits>
		    <n_raw_sms>1</n_raw_sms>
			<sender_name>MyBrandName</sender_name>
		</data>
	</response>

Пример JSON ответа, в случае успешной отправки


	/* JSON */
   {
	"response":{
		"msg":{
			"err_code":"0",
			"text":"OK",
			"type":"message"
			},
			"data":{
				"id":21528183,
				"credits":"1.78",
				"n_raw_sms":1,
				"sender_name":"MyBrandName"
			}
		}
   }



5 Коды ошибок, которые возвращает параметр err_code

Код ошибки Тип Описание
0 Integer Сообщение принято для отправки
3 Integer API на Вашем аккаунте отключено. Обратитесь в поддержку.
7 Integer Заданы не все необходимые параметры
99 Integer Транзакция отправки SMS не прошла
602 Integer SMS не существует.
605 Integer Пользователь заблокирован
607 Integer Имя отправителя недопустимо
608 Integer Недопустимая длина имени отправителя
609 Integer Сотовый оператор не подключен
610 Integer Не подключен тариф пользователю
611 Integer Не корректно установлена стоимость SMS
617 Integer Неверный формат номера получателя SMS
618, 622 Integer Номер aбонента в Черном списке
620 Integer Имя отправителя должно быть на латинице
621 Integer В имени отправителе более 2-цифр или общая длина менее 4-х символов, что не допустимо.
623 Integer Не достаточно средств. Пополните баланс.
624 Integer Обнаружены запрещенные слова в тексте сообщения. Обратитесь в поддержку.
625 Integer API KEY не указан.
626 Integer Не удалось получить данные по API KEY.
627 Integer Не верный API KEY.
629 Integer Превышен лимит отправки номеров в одном запросе (допускается не более 1000 номеров в запросе).
631 Integer Сообщение отклонено. Нельзя смешивать русские и английские символы в одном слове. Сервис не принимает SMS, в которых в одном слове смешаны кириллица и латиница, т.к. операторы блокируют такие смс, воспринимая за попытку обойти СПАМ фильтр.
699 Integer Не удалось установить соединение.



6 Отложенная отправка SMS по московскому времени

Допустим Вам нужна доставка в 10:00 по МСК, тогда при отправке СМС необходимо добавить параметр set_aside_time (параметр отложенной отправки).

Например, set_aside_time=1562894502 (время в UNIX TIME). Доставка будет по Московскому времени.

Отложенная СМС будет храниться на платформе и доставлена абоненту в указанное время (по МСК).




7 Отложенная отправка SMS по местному времени абонента

Например, у Вас в рассылке есть абоненты МСК (Московский часовой пояс), а также, например, дальние регионы +8 (Магаданская область, Сахалинская область)

Допустим нужна доставка в 10:00 по местному времени каждого абонента.

Нужно понимать, что в таком случае (в этом примере) всю рассылку необходимо отправить примерно за 8 часов. (т.е. 10:00 по МСК минус 8 часов) т.е. получается, отправить нужно в 02:00 по Москве. Т.е. рассылку необходимо передать в 2 часа ночи.


Добавляем параметр отложенной доставки set_aside_time.

Например, set_aside_time=1562894502 (время в UNIX TIME), а также добавляем параметр time=local

В таком случае доставка будет согласно локальному времени абонента.



Важно! Не используйте параметры отложенной отправки при передаче срочных SMS (смс коды и т.д., а также сообщений, которые нужно доставить как можно быстрее).

Необходимо понимать, что когда осуществляется "отложенная доставка", сообщения попадают в некий буфер, откуда начинают отправляться в указанное время.

Теоретически можно указывать время отложенной отправки равное текущему времени, (NOW или CURRENT_TIME), т.е. "отправить сейчас", но это не будет работать быстро, потому что сообщения сначала будут попадать в буфер для их хранения. Потом из буфера будет отправка и это может составлять до 15 секунд, поэтому, для срочных отправок не передавайте параметр set_aside_time и time=local. Без указания этих параметров - сообщения будут помещаться сразу в отправщик (очередь отправки) и доставляться максимально быстро.

Получение статусов отправленных SMS

Получение статусов отправленных SMS сообщений

Для быстрого перехода используйте содержание:

1. Автоматическое получение статусов на Ваш сервер.

2. Получение статусов самостоятельно (метод get_msg_report).
     2.1 Список всех параметров для отправки запроса.
     2.2 Пример HTTP запроса, который Вы можете выполнить в браузере.
     2.3 Примеры ответа сервера (при успешном запросе).
     2.4 Коды статусов, которые возвращает параметр state (статусы SMS)
     2.5 Примеры значений, которые возвращает параметр state_text (текстовое описание статусов)
     2.6 Коды ошибок, которые возвращает параметр err_code (если ошибка запроса)
     2.7 Примеры ответа сервера (если ошибка запроса)



1 Автоматическое получение статусов на Ваш сервер

Вы можете настроить возможность автоматически получать на Ваш сервер статусы СМС сообщений, которые отправляете по API. Данный вариант рекомендуется, как более предпочтительный, т.к. статусы будут приходить Вам сразу после получения от оператора. Если запрашивать статусы самостоятельно, необходимо будет предусматривать повторные запросы по тем сообщениям, по которым нет статуса на момент первого запроса.


Как это работает?

Вы отправляете SMS сообщение по API (метод https://lk.sms-prosto.ru/help.php?faq=43). В ответ на успешную отправку сообщения Вы получаете уникальный ID SMS.


Как включить?

В личном кабинете, в разделе https://lk.sms-prosto.ru/settings.php?p=api Вы можете ввести URL адрес Вашего сайта (сервера), на который SMS-шлюз сделает GET запрос и передаст ID SMS, статус СМС сообщения и время доставки сообщения.


Какие параметры передает SMS шлюз?

id_sms - ID SMS сообщения на нашей стороне
state - ID статуса: 1-доставлено, 2-не доставлено, 34-не доставлено (просрочено), 16-отклонено оператором
last_update - Время доставки смс сообщения абоненту (время определяется по часовому поясу операторского СМС шлюза и может отличаться от часового пояса Москвы) (передается в формате UNIX_TIME)
state_date - Время поступления статуса от оператора (передается в формате UNIX_TIME)
phone - Номер Абонента получателя SMS
sender_name_change - Если была замена Вашего отправителя на какой-то наш, в этом параметре будет указан отправитель с которым реально было передано SMS оператору. Если замен не было, параметр передается с пустым значением.
external_id - Значение, которое было передано в момент отправки SMS (подразумевается, что тут будет ID сообщения на Вашей стороне), используется для более удобной идентификации сообщения по ID на Вашей стороне, а не по ID (параметр id_sms) на нашей стороне.

Другие параметры, которые будут переданы для идентификации платформы, от которой поступил статус:
reporter - идентификатор платформы.

Возможные значения:
reporter=sms
reporter=tg
reporter=vb
reporter=vk
reporter=wp
reporter=wait_call



2 Получение статусов самостоятельно (метод get_msg_report)

Вызов методов осуществляется посредством GET или POST HTTP-запросов к любому серверу:

Адрес сервера: http://api.sms-prosto.ru
Порт (протокол): 80 (HTTP)
Метод: GET или POST
Кодировка для запроса: UTF-8
Адрес сервера: https://ssl.bs00.ru
Порт (протокол): 443 (HTTPS)
Метод: GET или POST
Кодировка для запроса: UTF-8


В GET- или POST-переменных запроса передаются аргументы с именами:

Аргументы:

method - вызываемый метод.
- набор переменных, зависящий от конкретного метода (см. таблицу ниже).
format - (необязательный) формат выходных данных (XML, JSON), без указания этого параметра, по умолчанию данные выдаются в формате XML.

Все методы возвращают массив аргументов с именами:


msg - сообщение о выполнении действия в виде массива с ключами:
err_code - числовой код ошибки (0 - нет ошибок),
text - текстовое сообщение,
type - тип сообщения (message – нет ошибок, notice и error – ошибки).
data - запрашиваемые данные в виде массива.


2.1 Список всех параметров для отправки запроса

Параметр Тип (значение) Наличие в запросе Описание Пример
method get_msg_report Обязательный Инициирует отправку SMS method=get_msg_report
format json, JSON, xml, XML Не обязательный Значение json запрашивает ответ в формате json, в противном случае ответ будет в XML. format=json
email String (логин в системе) Обязательный, если авторизация осуществляется с помощью пары логин/пароль Необходим для авторизации. email=myemail@yandex.ru
password String (пароль в системе) Обязательный, если авторизация осуществляется с помощью пары логин/пароль Необходим для авторизации. password=myPassWord
key String (получить key можно в поддержке) Обязательный, если авторизация осуществляется с помощью key. Необходим для авторизации. В данном варианте параметры email и password передавать не нужно. key=Hfe8dn3SdgkdHGDer
id Int Обязательный id sms, который Вы получили при успешной отправке SMS методом https://lk.sms-prosto.ru/help.php?faq=43 id=23138764


2.2 Пример HTTP запроса, который Вы можете выполнить в браузере



/* Пример 1 (Используется Логин и Пароль от сервиса) */

http://api.sms-prosto.ru/?method=get_msg_report&email=YOUR_LOGIN&password=YOUR_PASSWORD&id=ID_SMS




/* Пример 2 (Используется API_KEY) */

http://api.sms-prosto.ru/?method=get_msg_report&key=YOUR_API_KEY&id=ID_SMS

YOUR_LOGIN - Логин в системе (Е-майл)
YOUR_PASSWORD - Пароль (получаем при регистрации в системе)
YOUR_API_KEY – API Key, который можно использовать вместо Логина и Пароля
ID_SMS - ID SMS который был получен при отправке методом https://lk.sms-prosto.ru/help.php?faq=43



2.3 Примеры ответа сервера (при успешном запросе)

Пример XML ответа, в случае успешного запроса



	/* XML */
	<response>
			<msg>
				<err_code>0</err_code>
				<text>OK</text>
				<type>message</type>
			</msg>
		<data>
			<id>23138764</id>
			<sender_name>BrandName</sender_name> /* Отправитель с которым передалась SMS */
			<text>Текст отправленный SMS</text>
			<phone>79032920834</phone> /* номер Абонента */
			<type>1</type> /* Тип сообщения ("0" - flash SMS, "1" - cтандартная SMS) */
			<n_raw_sms>2</n_raw_sms> /* Количество сегментов SMS */
			<start_time>2018-09-15 18:28:54</start_time> /* Время отправки SMS */
			<last_update>2018-09-15 18:29:00</last_update> /* Время доставки SMS абоненту */
			<id_tarifs_group>3</id_tarifs_group> /* id тарифной группы, как правило совпадает с id Оператора связи, список id можно запросить в Поддержке */
			<state>1</state> /* 1 - 'Доставлено', 2 - 'Не доставлено', 16 - 'Не доставлено в SMSC', 34 - 'Не доставлено (просрочено)', 0 - 'Отправлено'  */
			<credits>2.190</credits> /* стоимости одного сегмента */
			<state_text>Доставлено</state_text> /* 'Доставлено', 'Не доставлено', 'Не доставлено в SMSC', 'Не доставлено (просрочено)', 'Отправлено' */
		</data>
	</response>



Пример JSON ответа, в случае успешного запроса


	/* JSON */

	{
	 "response":{
		"msg":{
				"err_code":"0",
				"text":"OK",
				"type":"message"
		},
		"data":{
				"id":"23138764",
				"sender_name":"SSMS.SU",
				"text":"Текст отправленной SMS",
				"phone":"79032920834",
				"type":"1",
				"n_raw_sms":"2",
				"start_time":"2018-09-15 18:28:04",
				"last_update":"2018-09-15 18:29:00",
				"id_tarifs_group":"3", /* id тарифной группы, как правило совпадает с id Оператора связи, список id можно запросить в Поддержке */
				"state":"1", /* 1 - 'Доставлено', 2 - 'Не доставлено', 16 - 'Не доставлено в SMSC', 34 - 'Не доставлено (просрочено)', 0 - 'Отправлено'  */
				"credits":"2.190",
				"state_text":"Доставлено" /* 'Доставлено', 'Не доставлено', 'Не доставлено в SMSC', 'Не доставлено (просрочено)', 'Отправлено' */
				}
		}
	}



Важное замечание по параметрам state и state_text

параметр state - выдает всегда цифровой код (0,1,2,16,34) обозначающий основное состояние SMS сообщения, для основных состояний SMS (Отправлено, Доставлено, Не доставлено в SMSC, Не доставлено (просрочено) или Не доставлено).

параметр state_text - передает текстовое описание (указанное в примере Выше) основного состояния SMS сообщения. Текстовое описание Вы можете также сохранять себе, для расшифровки. В логике работы своего кода это текстовое описание лучше не использовать, т.к. текстовое описание может меняться.

Также state_text может принимать другую более детальную расшифровку, кроме перечисленного выше основного состояния SMS.


Например,
Вы отправили SMS, и сразу же моментально запросили статус, при этом Вы получите state = 0 ("Отправлено", т.к. фактически для Вас эта СМС отправлена), но параметр state_text выдаст "Ожидает отправку" (более детальная расшифровка). Это означает что, сообщение еще находится в нашей очереди на отправку и будет отправлено в течение ~1 секунды.
При следующем запросе (например, через 1-5 секунд) Вы можете получить также state = 0 ("Отправлено"), при этом state_text будет содержать текстовое описание "Отправлено" (что соответствует основному состоянию SMS)
Обратите внимание, что сообщения как правило доставляются за 1-2-3 секунды, при этом статусы поступают от оператора в течение 10-20, иногда 30 секунды после факта доставки SMS. Скорость доставки статусов различная и зависит от оператора, а также от канала отправки.
state_text также может принимать и другие (они перечислены тут) текстовые значение (описания), при этом state всегда будет равна (0,1,2,16 или 32).

Приведем еще один пример.
Вы отправили СМС сообщение, например, на Билайн. Запрашиваете статус, при этом получаете state = 0 ("Отправлено"), при этом state_text может быть равна "644 Сбой на стороне оператора Билайн. Сообщения будут отправлены после устранения сбоя."
В данном примере сообщение считается Отправленным, но фактически, если у оператора наблюдается сбой, оно не может быть доставлено сразу. В данном примере, сообщение сохраняется на нашей стороне до момента устранения сбоя, после чего будет Доставлено.
В данном примере, необходимо будет запросить статус повторно, т.к. state = 0 ("Отправлено") не является конечным статусом.

Подведем итог.
Старайтесь настроить интервалы запроса статусов с разумной периодичностью, в зависимости от того, какие статусы Вы хотите получить "Конечные" или "Не конечные" (промежуточные).
Если Вы хотите в основном получать конечные статусы (Доставлено), запрашивайте статус не сразу после отправки.

2.4 Коды статусов, которые возвращает параметр state (статусы SMS)

Код статуса Тип Описание Комментарий
0 Integer Отправлено Не конечный, нужно сделать запрос повторно.

Важно! Этот статус будет конечным, если он не поменялся за 25 часов с момента отправик СМС.
Сообщение отправлено или находится в очереди на отправку. Это не конечный статус, поэтому необходимо повторить запрос через некоторое время.

Важно! Максимальное время "жизни" СМС коммерческих рассылок - 24 часа. Служба коротких текстовых сообщений не идеальна, может так случиться, что статус по СМС не поступит даже после истечения срока "жизни" СМС. Поэтому запрашивать статус спустя 25 часов просто нет смысла, он точно не измениться. Если спустя 25 часов state=0, это означает что сообщение Отправлено, оно возможно даже Доставлено или Не доставлено, но статус не вернулся от оператора. Поэтому спустя 25 часов этот статус считается конечным. И запрашивать его повторно не нужно, т.к. больше он точно не измениться.
1 Integer Доставлено Конечный Сообщение доставлено абоненту. Это конечный статус.
2 Integer Не доставлено Конечный Сообщение абоненту не доставлено. Это конечный статус.
16 Integer Не доставлено в SMSC Конечный Сообщение абоненту не доставлено. Это конечный статус. SMSC (Short Message Service Centre) - это оборудование, которое отвечает за работу службы коротких сообщений сети мобильной связи. Обычно такой статус может поступить в случае если Вы отправите два и более сообщения с одним и темже текстом на один и тотже номер в короткий промежуток времени. У операторов в данном примере может сработать система защиты от зависания и рассылки дублирующих СМС (защита от флуда).
34 Integer Не доставлено (просрочено) Конечный Сообщение абоненту не доставлено. Это конечный статус. Такой статус может поступить, в случае, если абонент был не в сети, при этом время доставки СМС (время "жизни" СМС) истекло.




2.5 Примеры значений, которые возвращает параметр state_text (текстовое описание статусов)

Значение state_text Тип Какой при этом будет state Комментарий
Ожидает отправку String, другая более детальная расшифровка промежуточного состояния SMS state=0 Сообщение отправляется, т.е. находится в очереди на отправку.
644 Сбой на стороне оператора {Название оператора/операторов}. Сообщения будут отправлены после устранения сбоя String, другая более детальная расшифровка промежуточного состояния SMS state=0 Для Вас фактически сообщение еще отправляется (при этом значение state=0)
Отправлено String, основное состояние state=0 Сообщение отправлено оператору.
Доставлено String, основное состояние state=1 Сообщение доставлено абоненту.
Не доставлено String, основное состояние state=2 Сообщение не доставлено абоненту.
Не доставлено в SMSC String, основное состояние state=16 Сообщение не доставлено абоненту.
Не доставлено (просрочено) String, основное состояние state=34 Сообщение не доставлено абоненту, срок "жизни" СМС истек.
645 Отклонено String, другая более детальная расшифровка конечного состояния SMS state=2 Сообщение не доставлено абоненту. Причину необходимо уточнить у службы поддержки сервиса.
643 Отправка в указанный Регион - запрещена, обратитесь в поддержку. String, другая более детальная расшифровка конечного состояния SMS state=2 Сообщение не доставлено абоненту. Запрещена отправка в указанный регион. По умолчанию для отправки SMS доступны все регионы Российской Федерации. Эта ошибка будет только в том случае, если Вы просили доставку SMS только в конкретный регион, при этом отправку осуществляете в регионы, которые у Вас отключены.



2.6 Коды ошибок, которые возвращает параметр err_code (если ошибка запроса)

Параметр err_code возвращает ошибку, в случае, если запрос на получения статусов по SMS не прошел (например, если API на уккаунте отключено.)

Код ошибки Тип Описание
3 Integer API на Вашем аккаунте отключено. Обратитесь в поддержку.
7 Integer Заданы не все необходимые параметры
602 Integer SMS не существует.
605 Integer Пользователь заблокирован
625 Integer API KEY не указан.
626 Integer Не удалось получить данные по API KEY.
627 Integer Не верный API KEY.
699 Integer Не удалось установить соединение.



2.7 Примеры ответа сервера (если ошибка запроса)

Пример XML ответа, в случае ошибки


	/* XML */
	<response>
		<msg>
			<err_code>5</err_code>
			<text>Неизвестный метод</text>
		    <type>error</type>
		</msg>
	<data/>
	</response>

Пример JSON ответа, в случае ошибки


	/* JSON */
	{
	  "response": {
		"msg":{
		   "err_code":"5",
		   "text":"Неизвестный метод",
		   "type":"error"
		},
		"data":null
	  }
	}



Получение информации об остатке баланса (метод get_profile)

Для быстрого перехода используйте содержание:

1. Список всех параметров и их описание.
2. Пример HTTP запроса, который можно выполнить в браузере.
3. Примеры ответов сервера.
4. Коды ошибок.



Вызов методов осуществляется посредством GET или POST HTTP-запросов к любому серверу:

Адрес сервера: http://api.sms-prosto.ru
Порт (протокол): 80 (HTTP)
Метод: GET или POST
Кодировка для запроса: UTF-8
Адрес сервера: https://ssl.bs00.ru
Порт (протокол): 443 (HTTPS)
Метод: GET или POST
Кодировка для запроса: UTF-8


В GET- или POST-переменных запроса передаются аргументы с именами:

Аргументы:

method - вызываемый метод.
- набор переменных, зависящий от конкретного метода (см. таблицу ниже).
format - (необязательный) формат выходных данных (XML, JSON), без указания этого параметра, по умолчанию данные выдаются в формате XML.

Все методы возвращают массив аргументов с именами:


msg - сообщение о выполнении действия в виде массива с ключами:
err_code - числовой код ошибки (0 - нет ошибок),
text - текстовое сообщение,
type - тип сообщения (message – нет ошибок, notice и error – ошибки).
data - запрашиваемые данные в виде массива.


Если Вы планируете для запросов по API использовать apikey (параметр key) в место логина и пароля, его также необходимо запросить в Поддержке (эл. почта указана в правом верхнем углу страницы).




2 Список всех параметров

Параметр Тип (значение) Наличие в запросе Описание Пример
method get_profile Обязательный Инициирует отправку SMS method=get_profile
format json, JSON, xml, XML Не обязательный Значение json запрашивает ответ в формате json, в противном случае ответ будет в XML. format=json
email String (логин в системе) Обязательный, если авторизация осуществляется с помощью пары логин/пароль Необходим для авторизации. email=myemail@yandex.ru
password String (пароль в системе) Обязательный, если авторизация осуществляется с помощью пары логин/пароль Необходим для авторизации. password=myPassWord
key String (получить key можно в поддержке) Обязательный, если авторизация осуществляется с помощью key. Необходим для авторизации. В данном варианте параметры email и password передавать не нужно. key=Hfe8dn3SdgkdHGDer


3 Пример HTTP запроса, который Вы можете выполнить в браузере



/* Пример 1 (Используется Логин и Пароль от сервиса) */

http://api.sms-prosto.ru/?method=get_profile&email=YOUR_LOGIN&password=YOUR_PASSWORD




/* Пример 2 (Используется API_KEY) */

http://api.sms-prosto.ru/?method=get_profile&key=YOUR_API_KEY

YOUR_LOGIN - Логин в системе (Е-майл)
YOUR_PASSWORD - Пароль (получаем при регистрации в системе)
YOUR_API_KEY – API Key, который можно использовать вместо Логина и Пароля




4 Примеры ответа сервера

Пример XML ответа, в случае ошибки


	/* XML */
	<response>
		<msg>
			<err_code>5</err_code>
			<text>Неизвестный метод</text>
		    <type>error</type>
		</msg>
	<data/>
	</response>

Пример JSON ответа, в случае ошибки


	/* JSON */
	{
	  "response": {
		"msg":{
		   "err_code":"5",
		   "text":"Неизвестный метод",
		   "type":"error"
		},
		"data":null
	  }
	}

Пример XML ответа, в случае успешного запроса


	/* XML */
	<response>
		<msg>
			<err_code>0</err_code>
			<text>OK</text>
			<type>message</type>
		</msg>
		<data>
			<id>211</id>
			<email>mailto:email@mail.ru</email>
			<first_name>Иван</first_name>
			<last_name>Иванов</last_name>
			<credits>25.110</credits>
			<credits_used>32966.900</credits_used>
			<credits_name>руб.</credits_name>
			<currency>руб.</currency>
			<sender_name>MyBrandName</sender_name>
			<referral_id>1</referral_id>
		</data>
	</response>



Пример JSON ответа, в случае успешного запроса


	/* JSON */
   {
	"response":{
		"msg":{
			 "err_code":"0",
			 "text":"OK",
			 "type":"message"
		},
		"data":{
			"id":"211",
			"mailto:email",
			"first_name":"Иван",
			"last_name":"Иванов",
			"credits":"25.110",
			"credits_used":"32966.900",
			"credits_name":"руб.",
			"currency":"руб.",
			"sender_name":"MyBrandName",
			"referral_id":"1"
		}
	}
   }



5 Коды ошибок, которые возвращает параметр err_code

Код ошибки Тип Описание
0 Integer Запрос выполнен успешно.
3 Integer API на Вашем аккаунте отключено. Обратитесь в поддержку.
7 Integer Заданы не все необходимые параметры
605 Integer Пользователь заблокирован
625 Integer API KEY не указан.
626 Integer Не удалось получить данные по API KEY.
627 Integer Не верный API KEY.
699 Integer Не удалось установить соединение.

Получение информации по стоимости СМС (метод get_prices)

Для быстрого перехода используйте содержание:

1. Список всех параметров и их описание.
2. Пример HTTP запроса, который можно выполнить в браузере.
3. Примеры ответов сервера.
4. Коды ошибок.



Для лучшего понимания выдаваемых сервером данных, необходимо различать следующее:

Группа маршрутов (group_directions) - это тип канала, или тип отправки. Платформа поддерживает одновременно несколько групп маршрутов (каналов, типов отправки), обратите внимание, у Вас на странице https://lk.sms-prosto.ru/tarifs.php в таблице (в левом столбце) указаны все имеющиеся группы маршрутов (или типы каналов). Например, "Буквенное имя", "Буквенное имя (скидка на Билайн, Теле2)" и т.д. Чем отличаются между собой Группы маршрутов можно посмотреть по этой https://lk.sms-prosto.ru/help.php?faq=34.

Тарифная группа (tarif_group) - это группа операторов, объедененных по цене или каналом отправки. Например, "МТС" - это тарифная группа в которую входит только один оператор, при этом, например, "Группа компаний TELE2" - в нее входит множество операторов, таких как ООО "Т2-Мобайл", ОАО "Теле2-Санкт-Петербург" и т.д. На платформе, для удобства все операторы объеденены в тарифные группы, например, - "Группа компаний TELE2".

Список всех тарифных групп можно посмотреть на странице https://lk.sms-prosto.ru/tarifs.php.


Вызов методов осуществляется посредством GET или POST HTTP-запросов к любому серверу:

Адрес сервера: http://api.sms-prosto.ru
Порт (протокол): 80 (HTTP)
Метод: GET или POST
Кодировка для запроса: UTF-8
Адрес сервера: https://ssl.bs00.ru
Порт (протокол): 443 (HTTPS)
Метод: GET или POST
Кодировка для запроса: UTF-8


В GET- или POST-переменных запроса передаются аргументы с именами:

Аргументы:

method - вызываемый метод.
- набор переменных, зависящий от конкретного метода (см. таблицу ниже).
format - (необязательный) формат выходных данных (XML, JSON), без указания этого параметра, по умолчанию данные выдаются в формате XML.

Все методы возвращают массив аргументов с именами:


msg - сообщение о выполнении действия в виде массива с ключами:
err_code - числовой код ошибки (0 - нет ошибок),
text - текстовое сообщение,
type - тип сообщения (message – нет ошибок, notice и error – ошибки).
data - запрашиваемые данные в виде массива. (Могут содержать вложенные массивы, смотрите подробнее на структуру выходных данных.)


Если Вы планируете для запросов по API использовать apikey (параметр key) в место логина и пароля, его также необходимо запросить в Поддержке (эл. почта указана в правом верхнем углу страницы).




2 Список всех параметров

Параметр Тип (значение) Наличие в запросе Описание Пример
method get_prices Обязательный Инициирует отправку SMS method=get_prices
format json, JSON, xml, XML Не обязательный Значение json запрашивает ответ в формате json, в противном случае ответ будет в XML. format=json
email String (логин в системе) Обязательный, если авторизация осуществляется с помощью пары логин/пароль Необходим для авторизации. email=myemail@yandex.ru
password String (пароль в системе) Обязательный, если авторизация осуществляется с помощью пары логин/пароль Необходим для авторизации. password=myPassWord
key String (получить key можно в поддержке) Обязательный, если авторизация осуществляется с помощью key. Необходим для авторизации. В данном варианте параметры email и password передавать не нужно. key=Hfe8dn3SdgkdHGDer
group_directions Int Не обязательный Используется для запроса цен по конкретному "Типу канала" (Группе маршрутов). Если group_directions не передается, в таком случае будут выведены цены по всем Группам маршрутов. group_directions=1


3 Пример HTTP запроса, который Вы можете выполнить в браузере



/* Пример 1 (Используется Логин и Пароль от сервиса) */

http://api.sms-prosto.ru/?method=get_prices&email=YOUR_LOGIN&password=YOUR_PASSWORD




/* Пример 2 (Используется API_KEY) */

http://api.sms-prosto.ru/?method=get_prices&key=YOUR_API_KEY


/* Пример 3 (Используется API_KEY, если нужно запросить цены только по конкретной группе маршрутов) */

http://api.sms-prosto.ru/?method=get_prices&key=YOUR_API_KEY&group_directions=1

YOUR_LOGIN - Логин в системе (Е-майл)
YOUR_PASSWORD - Пароль (получаем при регистрации в системе)
YOUR_API_KEY – API Key, который можно использовать вместо Логина и Пароля




4 Примеры ответа сервера

Пример XML ответа, в случае ошибки


	/* XML */
	<response>
		<msg>
			<err_code>5</err_code>
			<text>Неизвестный метод</text>
		    <type>error</type>
		</msg>
	<data/>
	</response>

Пример JSON ответа, в случае ошибки


	/* JSON */
	{
	  "response": {
		"msg":{
		   "err_code":"5",
		   "text":"Неизвестный метод",
		   "type":"error"
		},
		"data":null
	  }
	}

Пример XML ответа, в случае успешного запроса


	/* XML */
	<response>
		<msg>
			<err_code>0</err_code>
			<text>OK</text>
			<type>message</type>
		</msg>
		<data>
			<group_directions> /* Это массив Группы маршрутов */
				<key1> /* ключ массива совпадает с id Группы маршрутов (group_directions_id) */
					<group_directions_id>1</group_directions_id> /* id группы маргрутов */
					<group_directions_title>Буквенное имя</group_directions_title> /* Название Группы маршрутов */
					<key1> /* Это ключ массива, который совпадает с id Тарифной группы (tarif_group_id) */
						<tarif_group_id>1</tarif_group_id> /* id Тарифной группы */
						<tarif_group_title>Группа компаний TELE2</tarif_group_title> /* Название Тарифной группы */
						<price>2.58</price> /* Стоимость */
					</key1>
					<key2>
						<tarif_group_id>2</tarif_group_id>
						<tarif_group_title>Мобильные ТелеСистемы (МТС)</tarif_group_title>
						<price>1.89</price>
					</key2>
					<key3>
						<tarif_group_id>3</tarif_group_id>
						<tarif_group_title>ВымпелКом (Билайн)</tarif_group_title>
						<price>2.68</price>
					</key3>
					<key4>
						<tarif_group_id>4</tarif_group_id>
						<tarif_group_title>МегаФон</tarif_group_title>
						<price>2.19</price>
					</key4>
					<key6>
						<tarif_group_id>6</tarif_group_id>
						<tarif_group_title>Другие сотовые Операторы</tarif_group_title>
						<price>2.65</price>
					</key6>
					<key8>
						<tarif_group_id>8</tarif_group_id>
						<tarif_group_title>Екатеринбург-2000 (МОТИВ)</tarif_group_title>
						<price>1.20</price>
					</key8>
					<key10>
						<tarif_group_id>10</tarif_group_id>
						<tarif_group_title>Скартел (Yota)</tarif_group_title>
						<price>2.65</price>
					</key10>
				</key1>
			</group_directions>
		</data>
	</response>


Пример JSON ответа, в случае успешного запроса (при group_directions=1). Если group_directions не передается, будут выведены все group_directions, т.е. массив group_directions будет содержать несколько вложенных массивов


	/* JSON */
	{
	"response":
		{"msg":{
			"err_code":"0",
			"text":"OK",
			"type":"message"
		},
		"data":
			{"group_directions": {
				"1":{
					 "group_directions_id":"1",
					 "group_directions_title":"Буквенное имя",
					 "1":{"tarif_group_id":1,"tarif_group_title":"Группа компаний TELE2","price":"2.58"},
					 "2":{"tarif_group_id":2,"tarif_group_title":"Мобильные ТелеСистемы (МТС)","price":"1.89"},
					 "3":{"tarif_group_id":3,"tarif_group_title":"ВымпелКом (Билайн)","price":"2.68"},
					 "4":{"tarif_group_id":4,"tarif_group_title":"МегаФон","price":"2.19"},
					 "6":{"tarif_group_id":6,"tarif_group_title":"Другие сотовые Операторы","price":"2.65"},
					 "8":{"tarif_group_id":8,"tarif_group_title":"Екатеринбург-2000 (МОТИВ)","price":"1.20"},
					 "10":{"tarif_group_id":10,"tarif_group_title":"Скартел (Yota)","price":"2.65"}
					}
				}
			}
		}
	}




5 Коды ошибок, которые возвращает параметр err_code

Код ошибки Тип Описание
0 Integer Запрос выполнен успешно.
3 Integer API на Вашем аккаунте отключено. Обратитесь в поддержку.
7 Integer Заданы не все необходимые параметры
605 Integer Пользователь заблокирован
625 Integer API KEY не указан.
626 Integer Не удалось получить данные по API KEY.
627 Integer Не верный API KEY.
699 Integer Не удалось установить соединение.

Отправка SMS-кода с функцией "Защита вызовом" new

Для быстрого перехода используйте содержание:

1. Как это работает?
2. Рекомендации по формулировке информации, предоставляемой абоненту по алгоритму действий при авторизации методом "Входящего звонка от абонента".
3. Список параметров и их описание.
4. Примеры ответов сервера.



1 Как это работает?


Под словом Защита понимается - возможность авторизовать абонента в любом случае, даже если SMS сообщение с кодом не будет доставлено по причинам, зависящим от Оператора связи, оказывающего Услуги абоненту.

Вы отправляете SMS-коды как обычно (см. https://lk.sms-prosto.ru/help.php?faq=43#primer-http-zaprosa), при этом в запрос добавляете соответствующий параметр call_protection=200, где 200 - время (секунды) ожидания звонка от абонента.

SMS-сообщения как правило доставляются сразу, без каких либо задержек. Но, в случае сбоя у какого либо оператора, либо по другим причинам (помехи, вызванные естественными препятствиями, подвальные помещения, ограничение связи абоненту, в связи с задолженностью перед оператором, отключена услуга приема SMS и т.д.) В таких случаях - сообщение может быть не доставлено или будет доставляться дольше обычного, При этом, как правило, абонент не понимает почему ему не доходят SMS.

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

И так, допустим через 20 секунд ожидания SMS, Вы можете показать абоненту ссылку (кнопку и т.д.) "Мне не пришел СМС код", по нажатию на которую выдать информацию о том, что для авторизации нужно позвонить на такой-то номер. (см. наши рекомендации по формулировке) Как Вы помните, при отправке SMS, мы уже ждем звонка 200 секунд.

Этот параметр можно добавлять во все SMS, которые содержат СМС-код авторизации, т.к. в большенстве случае SMS-сообщение будет доставлено сразу, при этом авторизация методом "Входящего звонка от абонента" не потребуется. В данном случае Вы платите только за SMS.

В случае, если СМС все-таки не дойдет сразу, у Вас уже есть запасной вариант - это авторизация методом "Входящего звонка от абонента", при этом никаких дополнительных запросов делать не потребуется. Вам нужно только, в момент ожидания звонка от абонента проверять, к примеру раз в 2 секунды, поступила ли от нас информация о входящем вызове.



Также, Вы можете абоненту предлагать самостоятельно выбрать способ авторизации:

  • - авторизация по SMS, при этом использовать функцию "Отправка SMS кода с функцией "Защита вызовом";
  • - авторизация методом "Входящего звонка от абонента" (вместо SMS);



2Рекомендации по формулировке информации, предоставляемой абоненту по алгоритму действий при авторизации методом "Входящего звонка от абонента"


"Для прохождения авторизации, позвоните на бесплатный номер 8800-ХХХ-ХХХХ, дождитесь ответа о том, что абонент занят, далее можно положить трубку, либо звонок будет сброшен после оканчания проигрывания сообщения".




3 Список параметров и их описание

Параметр Тип (значение) Наличие в запросе Описание Пример
call_protection Integer (допустимые значения от 60 до 300), секунды Обязательный, если нужно отправить SMS-код с функцией "Защита вызовом" Платформа ожидает входящий вызов от указанного абонента в соответствии с значением параметра call_protection call_protection=200



4 Примеры ответа сервера

Пример XML ответа, в случае успешной отправки SMS


	/* XML */
	<response>
		<msg>
			<err_code>0</err_code>
			<text>OK</text>
		    <type>message</type>
		</msg>
		<data>
			<id>21528183</id>
			<credits>0.60</credits>
		    <n_raw_sms>1</n_raw_sms>
			<sender_name>MyBrandName</sender_name>
			<call_to_number>88003025421</call_to_number> /* Ответ такой же, как при отправке SMS, только тут - дополнительный параметр call_to_number */
		</data>
	</response>

Пример JSON ответа, в случае успешной отправки


	/* JSON */
   {
	"response":{
		"msg":{
			"err_code":"0",
			"text":"OK",
			"type":"message"
			},
			"data":{
				"id":21528183,
				"credits":"1.78",
				"n_raw_sms":1,
				"sender_name":"MyBrandName",
				"call_to_number":"88003025421" /* Ответ такой же, как при отправке SMS, только тут - дополнительный параметр call_to_number */
			}
		}
   }



Авторизация методом "Входящего звонка от абонента", вместо SMS кодов. (Метод wait_call) new

Для быстрого перехода используйте содержание:

1. Как это работает?
2. Как включить API-шлюз.
3. Список всех параметров и их описание.
4. Пример HTTP запроса, который можно выполнить в браузере.
5. Примеры ответов сервера.
6. Коды ошибок.
7. Какие параметры поступят на Ваш URL



Вызов методов осуществляется посредством GET или POST HTTP-запросов к любому серверу:

Адрес сервера: http://api.sms-prosto.ru
Порт (протокол): 80 (HTTP)
Метод: GET или POST
Кодировка для запроса: UTF-8
Адрес сервера: https://ssl.bs00.ru https://ping-admin.ru/uptime/67f907eead9de432cc4df9106b38d6d188537.html
Порт (протокол): 443 (HTTPS)
Метод: GET или POST
Кодировка для запроса: UTF-8


В GET- или POST-переменных запроса передаются аргументы с именами:

Аргументы:

method - вызываемый метод.
- набор переменных, зависящий от конкретного метода (см. таблицу ниже).
format - (необязательный) формат выходных данных (XML, JSON), без указания этого параметра, по умолчанию данные выдаются в формате XML.

Все методы возвращают массив аргументов с именами:


msg - сообщение о выполнении действия в виде массива с ключами:
err_code - числовой код ошибки (0 - нет ошибок),
text - текстовое сообщение,
type - тип сообщения (message – нет ошибок, notice и error – ошибки).
data - запрашиваемые данные в виде массива.



1 Как это работает?


Данный функционал можно использовать полноценно вместо отправки SMS кодов, совместно с отправкой SMS (см. функцию https://lk.sms-prosto.ru/help.php?faq=59), а также комбинировать, предоставляя абоненту возможность выбрать способ авторизации по SMS или звонком.

Абонент предоставляет Вам свой номер телефона, который необходимо авторизовать (проверить), точно также, как при авторизации с помощью отправки SMS кода на проверяемый номер,

И так, для проверки номера телефона, - Вы делаете запрос на наше API method=wait_call, при этом передаете номер проверяемого телефона абонента phone=79670311122 и устанавливаете время ожидания звонка от абонента (параметр call_protection=200), а также другие параметры, необходимые для авторизации на платформе (логин/пароль или api key).

Наша платформа в ответ выдает номер, на который необходимо позвонить для проверки.

При этом абоненту необходимо выдать сообщение, примерно следующего содержания (см. https://lk.sms-prosto.ru/help.php?faq=59#rekomendacii-abonenty).

"Для прохождения авторизации, позвоните на бесплатный номер 8800-ХХХ-ХХХХ, дождитесь ответа о том, что абонент занят, далее можно положить трубку, либо звонок будет сброшен после оканчания проигрывания сообщения".

В момент поступления звонка от проверяемого абонента, - Вы получите HTTP запрос с информацией о входящем вызове, на основании которой Вы должны произвести авторизацию абонента в своей системе.

Указать URL, на который будет осуществлен GET запрос необходимо в разделе "Настройки" -> https://lk.sms-prosto.ru/settings.php?p=api -> раздел "Настройка получения информации о входящих вызовах"




2 Как включить API-шлюз

Вы можете проверить состояние API-шлюза на странице https://lk.sms-prosto.ru/settings.php?p=api. Если он не включен - напишите в поддержку на почту support@sms-prosto.ru с просьбой включить. Также рекомендуется указать примерный текст сообщений, который планируется отправлять по API, данная информация необходима, чтобы Вам выставили корректные приоритеты на отправляемые SMS сообщения, это позволит доставлять SMS через соответствующие каналы значительно быстрее обычных SMS сообщений.

Если Вы планируете для отправки SMS по API использовать apikey (параметр key) в место логина и пароля, его также необходимо запросить в Поддержке.




3 Список всех параметров

Параметр Тип (значение) Наличие в запросе Описание Пример
method wait_call Обязательный Инициирует ожидание входящего звонка от абонента method=wait_call
format json, JSON, xml, XML Не обязательный Значение json запрашивает ответ в формате json, в противном случае ответ будет в XML. format=json
email String (логин в системе) Обязательный, если авторизация осуществляется с помощью пары логин/пароль Необходим для авторизации. email=myemail@yandex.ru
password String (пароль в системе) Обязательный, если авторизация осуществляется с помощью пары логин/пароль Необходим для авторизации. password=myPassWord
key String (получить key можно в поддержке) Обязательный, если авторизация осуществляется с помощью key. Необходим для авторизации. В данном варианте параметры email и password передавать не нужно. key=Hfe8dn3SdgkdHGDer
phone Int Обязательный В любом формате 7ХХХYYYххyy, 8ХХХYYYххyy, +7ХХХYYYххyy, 7(ХХХ)YYY-хх-yy и т.д. phone=79162821111
call_protection Integer (допустимые значения от 60 до 300), секунды Обязательный Платформа будет ожидать вызов в течение 200 секунд call_protection=200



4 Пример HTTP запроса, который Вы можете выполнить в браузере



/* Пример 1 (Используется Логин и Пароль от сервиса) */

http://api.sms-prosto.ru/?method=wait_call&email=YOUR_LOGIN&password=YOUR_PASSWORD&&phone=SMS_PHONE_NUMBER_OF_THE_RECIPIENT&call_protection=TIME_SECONDS




/* Пример 2 (Используется API_KEY) */

http://api.sms-prosto.ru/?method=wait_call&key=YOUR_API_KEY&phone=SMS_PHONE_NUMBER_OF_THE_RECIPIENT&call_protection=TIME_SECONDS

YOUR_LOGIN - Логин в системе (Е-майл)
YOUR_PASSWORD - Пароль (получаем при регистрации в системе)
YOUR_API_KEY – API Key, который можно использовать вместо Логина и Пароля
SMS_PHONE_NUMBER_OF_THE_RECIPIENT - Номер телефона получателя SMS, в любом формате
TIME_SECONDS - Количество секунд, которое необходимо ожидать Вызов от абонента



5 Примеры ответа сервера

Пример XML ответа, в случае ошибки


	/* XML */
	<response>
		<msg>
			<err_code>5</err_code>
			<text>Неизвестный метод</text>
		    <type>error</type>
		</msg>
	<data/>
	</response>

Пример JSON ответа, в случае ошибки


	/* JSON */
	{
	  "response": {
		"msg":{
		   "err_code":"5",
		   "text":"Неизвестный метод",
		   "type":"error"
		},
		"data":null
	  }
	}

Пример XML ответа, в случае успешной инициации ожидания Вызова от абонента


	/* XML */
	<response>
		<msg>
			<err_code>0</err_code>
			<text>OK</text>
		    <type>message</type>
		</msg>
		<data>
			<call_to_number>88003025421</call_to_number>
			<id_call>57858b0d-cbf3-4c9b-9119-f7ee7f363b34</id_call>
			<waiting_call_from>MyBrandName</waiting_call_from>
		</data>
	</response>

Пример JSON ответа, в случае успешной инициации ожидания вызова от абонента


	/* JSON */
   {
	"response":{
		"msg":{
			"err_code":"0",
			"text":"OK",
			"type":"wait_call"
			},
			"data":{
				"call_to_number":"88003025421",
				"id_call":"57858b0d-cbf3-4c9b-9119-f7ee7f363b34",
				"waiting_call_from":"79670312233"
			}
		}
   }



6 Коды ошибок, которые возвращает параметр err_code

Код ошибки Тип Описание
0 Integer Инифиировано ожидание звонка от абонента
3 Integer API на Вашем аккаунте отключено. Обратитесь в поддержку.
7 Integer Заданы не все необходимые параметры
605 Integer Пользователь заблокирован
609 Integer Сотовый оператор не подключен
610 Integer Не подключен тариф пользователю
611 Integer Не корректно установлена стоимость SMS
617 Integer Неверный формат номера получателя SMS
623 Integer Не достаточно средств. Пополните баланс.
625 Integer API KEY не указан.
626 Integer Не удалось получить данные по API KEY.
627 Integer Не верный API KEY.
699 Integer Не удалось установить соединение.


7 Какие параметры поступят на Ваш URL



Пример GET запроса на Ваш URL


	/* пример GET запроса, который будет выполнен на Ваш URL в момент поступления вызова от абонента */

	https://Ваш_URL/?reporter=wait_call&call_to_number=88003025421&phone=79670310000&sms_id=0&id_call=39e40f42-055e-40ed-80dd-09bf6d9f15e4


	/* Представление в виде массива */

array(5) {
  ["reporter"]=>
  string(9) "wait_call"  /* Информация о том, что запрос поступил от wait_call Reporter*/
  ["call_to_number"]=>
  string(11) "88003025421" /* Бесплатный номер, на который позвонил абонент */
  ["phone"]=>
  string(11) "79670311122" /* Номер абонента */
  ["sms_id"]=>
  string(1) "0" /* sms_id, - передается в случае если использовалась функция "Отправка SMS-кода с функцией "Защита вызовом", т.е. отправлялась SMS с последующим ожиданием Вызова. Передается 0, если использовалась функция "Авторизация методом "Входящего звонка от абонента" (вместо SMS кодов), без отправки SMS */
  ["id_call"]=>
  string(36) "39e40f42-055e-40ed-80dd-09bf6d9f15e4" /* ID задачи на ожидание, этот id был выдан при запросе на ожидание, используется для понимания - на какой именно "запрос на ожидание" был фактически осуществлен входящий звонок. */
}




Отправка SMS Telegram (метод push_msg)

Для быстрого перехода используйте содержание:

1. Как это работает?
2. Отправка только в Telegram.
3. Отправка в Telegram с автоматической переотправкой в другие мессенджеры или SMS.
4. Список параметров и их описание.
5. Примеры ответов сервера.
6. Как получить статусы?


1 Как это работает?


Вы можете отправлять сообщения пользователям Telegram по мобильному номеру абонента и дополнительно использовать возможность каскадной рассылки.

При каскадной рассылке сообщение отправляется сначала в Telegram, а если приложение Telegram не установлено, или абонент не подписан/отказался от подписки, то осуществляется автоматическая отправка обычного смс-сообщения или отправка в другие мессенджеры (согласно переданным параметрам).



Важно! Перед отправкой сообщений в Telegram, необходимо предварительно создать и согласовать ваш отправитель для Telegram, для этого заполните специальную форму в личном кабинете, в разделе "Отправители" - https://lk.sms-prosto.ru/sender_names.php?p=senders_telegram.

Вам понадобиться следующая информация:

  • логотип, который будет использоваться в приложении формата png, jpg; размер должен быть не менее 150х150 и не более 1000х1000 пикселей
  • а также некоторые другие данные: информация о компании, контактная информация.


После согласования Вам будут предоставлены реквизиты Вашего Информера. Доставка сообщений пользователю Telegram возможна только, в случае добровольной подписки, которая осуществляется:

  • по url ссылке, которая будет предоставлена после создания информера. url ссылку можно использовать в SMS, email рассылках, а также разместить на сайте.
  • по QR коду, который будет предоставлен после создания информера. QR код можно распечатать и использовать в магазине, на кассе, в офисе и т.д., чтобы перейти к информеру, QR код необходимо отсканировать камерой телефона.






2 Отправка только в Telegram


Чтобы отправить SMS в Telegram, необходимо использовать https://lk.sms-prosto.ru/help.php?faq=43#primer-http-zaprosa, который используется для отправки обычной SMS, при этом в запрос добавляется дополнительный параметр route=tg, где tg - значение, отвечающее за отправку SMS в Telegram.


3 Отправка в Telegram с автоматической переотправкой в другие мессенджеры или SMS



Если необходимо отправить сообщение в Telegram, с последующей переотправкой (если абонент не подписан и не может получить сообщение в Telegram) в другие месенджеры, необходимо параметр route передавать следующим образом route=tg-sms, или route=tg-vk-sms или route=tg-vk-wp-sms

где:
tg - значение, отвечающее за отправку SMS в Telegram.
vk - Вконтакте
wp - WhatsApp
sms - SMS


Более подробное описание всех параметров смотрите ниже.


! Если у Вас нет возможности менять/дорабатывать Ваше API, Вы можете обратиться в службу поддержки на mailto:support@sms-prosto.ru с просьбой настроить указанную маршрутизацию на нашей стороне, в таком случае, Ваше API будет работать без необходимости что-либо менять на вашей стороне.





2 Список параметров и их описание

Параметр Тип (значение) Наличие в запросе Описание Пример
route String Обязательный, если нужно отправить SMS в Telegram При наличии параметра route платформа начинает использовать указанный маршрут (при наличии технической возможности) route=tg



3 Примеры ответа сервера

Пример XML ответа, в случае успешной отправки SMS


	/* XML */
	<response>
		<msg>
			<err_code>0</err_code>
			<text>OK</text>
		    <type>message</type>
		</msg>
		<data>
			<id>21528183</id>
			<credits>1.90</credits>
		    <n_raw_sms>1</n_raw_sms>
			<sender_name>MyBrandName</sender_name>
		</data>
	</response>

Пример JSON ответа, в случае успешной отправки


	/* JSON */
   {
	"response":{
		"msg":{
			"err_code":"0",
			"text":"OK",
			"type":"message"
			},
			"data":{
				"id":21528183,
				"credits":"1.90",
				"n_raw_sms":1,
				"sender_name":"MyBrandName",
			}
		}
   }





4 Как получить статусы


Вариант 1 - запрашивать статусы сомостоятельно, как и запрашиваете https://lk.sms-prosto.ru/help.php?faq=48#get-msg-report. Список статусов "Доставлено", "Не доставлено" можно посмотреть https://lk.sms-prosto.ru/help.php?faq=48#error-codes-state.


Вариант 2 (рекомендуется, более быстрый) - в разделе https://lk.sms-prosto.ru/settings.php?p=api - подраздел "Настройка получения статусов SMS от Telegram" необходимо прописать URL, на который платформа будет направлять все статусы GET запросом.


Пример запроса, который поступит на Ваш сервер



  /* GET запрос */
  https://site.ru/dir/?reporter=tg&phone=79050312233&id_sms=181139138&state=45&state_date=1608210989&last_update=1608221840

  /* GET массив */
  array(6) {
   ["reporter"]=>
	string(14) "tg" //Признак Telegram платформы
	["phone"]=>
	string(11) "79050312233" //Номер абонента
	["id_sms"]=>
	string(9) "181139138" //ID смс, также этот id был получен при отправке
	["state"]=>
	string(2) "1" // Варианты статусов: 1-Доставлено, 2-Не доставлено
	["state_date"]=>
	string(10) "1608210989" //Дата статуса unixtime
	["last_update"]=>
	string(10) "1608221840" //Дата получения статуса unixtime
	}


Отправка SMS WhatsApp (метод push_msg)

Для быстрого перехода используйте содержание:

1. Как это работает?
2. Отправка только в WhatsApp
3. Отправка в WhatsApp с автоматической переотправкой в другие мессенджеры или SMS
4. Список параметров и их описание.
5. Примеры ответов сервера.
6. Как получить статусы.


1 Как это работает?


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

Важная особенность канала: принимаются только сервисные сообщения, также короткие сообщения, состоящие из 1 сегмента (т.е. не более 70 символов кириллицей или 160 символов латиницей). Важно! Рекламные сообщения запрещены и передаваться не будут. Если Ваше сообщение будет больше указанной длины, то в таком случае при каскадной рассылке отправка в WhatsApp будет пропущена и сработает доотправка в следующий мессенджер или SMS (согласно переданным параметрам).

С учетом этого, при использовании WhatsApp рекомендуем задавать доотправку в другие мессенджеры и/или SMS.








Важно! Перед отправкой сообщений в WhatsApp, необходимо предварительно согласовать шаблоны текстов, которые планируются к отправке, для этого направьте заявку со списком планируемых к отправке текстов в службу поддержки на mailto:support@sms-prosto.ru





2 Отправка только в WhatsApp


Чтобы отправить SMS в WhatsApp, необходимо использовать https://lk.sms-prosto.ru/help.php?faq=43#primer-http-zaprosa, который используется для отправки обычной SMS, при этом в запрос добавляется дополнительный параметр route=wp, где wp - значение, отвечающее за отправку SMS в WhatsApp.


3 Отправка в WhatsApp с автоматической переотправкой в другие мессенджеры или SMS



Если необходимо отправить сообщение в WhatsApp, с последующей переотправкой (если абонент не может получить сообщение в WhatsApp) в другие месенджеры, необходимо параметр route передавать следующим образом route=wp-sms, или route=wp-vk-sms или route=wp-tg-vk-sms

где:
wp - значение, отвечающее за отправку SMS в WhatsApp.
tg - Telegram
vk - Вконтакте
sms - SMS


Более подробное описание всех параметров смотрите ниже.



! Если у Вас нет возможности менять/дорабатывать Ваше API, Вы можете обратиться в службу поддержки на mailto:support@sms-prosto.ru с просьбой настроить указанную маршрутизацию на нашей стороне, в таком случае, Ваше API будет работать без необходимости что-либо менять на вашей стороне.





2 Список параметров и их описание

Параметр Тип (значение) Наличие в запросе Описание Пример
route String Обязательный, если нужно отправить SMS в WhatsApp При наличии параметра route платформа начинает использовать указанный маршрут (при наличии технической возможности) route=wp



3 Примеры ответа сервера

Пример XML ответа, в случае успешной отправки SMS


	/* XML */
	<response>
		<msg>
			<err_code>0</err_code>
			<text>OK</text>
		    <type>message</type>
		</msg>
		<data>
			<id>21528183</id>
			<credits>1.90</credits>
		    <n_raw_sms>1</n_raw_sms>
			<sender_name>MyBrandName</sender_name>
		</data>
	</response>

Пример JSON ответа, в случае успешной отправки


	/* JSON */
   {
	"response":{
		"msg":{
			"err_code":"0",
			"text":"OK",
			"type":"message"
			},
			"data":{
				"id":21528183,
				"credits":"1.90",
				"n_raw_sms":1,
				"sender_name":"MyBrandName",
			}
		}
   }





4 Как получить статусы


Вариант 1 - запрашивать статусы сомостоятельно, как и запрашиваете https://lk.sms-prosto.ru/help.php?faq=48#get-msg-report. Список статусов "Доставлено", "Не доставлено" можно посмотреть https://lk.sms-prosto.ru/help.php?faq=48#error-codes-state.


Вариант 2 (рекомендуется, более быстрый) - в разделе https://lk.sms-prosto.ru/settings.php?p=api - подраздел "Настройка получения статусов SMS от WhatsApp" необходимо прописать URL, на который платформа будет направлять все статусы GET запросом.


Пример запроса, который поступит на Ваш сервер



  /* GET запрос */
  https://site.ru/dir/?reporter=wp&phone=79050312233&id_sms=181139138&state=45&state_date=1608210989&last_update=1608221840

  /* GET массив */
  array(6) {
   ["reporter"]=>
	string(14) "wp" //Признак WhatsApp
	["phone"]=>
	string(11) "79050312233" //Номер абонента
	["id_sms"]=>
	string(9) "181139138" //ID смс, также этот id был получен при отправке
	["state"]=>
	string(2) "1" // Варианты статусов: 1-Доставлено, 2-Не доставлено
	["state_date"]=>
	string(10) "1608210989" //Дата статуса unixtime
	["last_update"]=>
	string(10) "1608221840" //Дата получения статуса unixtime
	}


Отправка SMS методом каскадной маршрутизации

Для быстрого перехода используйте содержание:

1. Что такое каскадная маршрутизация SMS?
2. Варианты каскадной маршрутизации SMS
3. Как начать использовать?


1 Что такое каскадная маршрутизация SMS?

Метод каскадной маршрутизации SMS - это способ последовательной отправки сообщения сначала в один канал, а в случае, если сообщение не доставляется, то осуществляется автоматическая отправка в другой канал. Каналов может быть несколько, например, https://lk.sms-prosto.ru/help.php?faq=63, https://lk.sms-prosto.ru/help.php?faq=61, https://lk.sms-prosto.ru/help.php?faq=62, https://lk.sms-prosto.ru/help.php?faq=64, https://lk.sms-prosto.ru/help.php?faq=43.

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

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


2 Варианты каскадной маршрутизации SMS

Возможные варианты каскадной рассылки в зависимости от значения route=хх-хх-хх-хх, где хх - идентификатор мессенджера

Каскад из 2 каналов
вариант 1 tg-sms
вариант 2 vk-sms
вариант 3 wp-sms
вариант 4 vb-sms

Каскад из 3 каналов
вариант 5 tg-vk-sms
вариант 6 tg-wp-sms
вариант 7 tg-vb-sms
вариант 8 vk-wp-sms
вариант 9 vk-vb-sms
вариант 10 wp-vb-sms

Каскад из 4 каналов
вариант 11 tg-vk-wp-sms
вариант 12 vk-wp-vb-sms

Каскад из 5 каналов
вариант 13 tg-vk-wp-vb-sms

Возможны и другие варианты каскадной рассылки. Если Вас интересует индивируальное решение, пожалуйста, напишите нам на mailto:support@sms-prosto.ru



3 Как начать использовать каскадную маршрутизацию SMS?

Вариант 1
Параметры каскада можно задавать самостоятельно при отправке SMS по API. Для этого используйте параметр route. Вы можете назначить любые варианты маршрутизации на каждое отправляемое сообщение в зависимости от Вашей потребности.

Обращаем внимание, что отправку SMS-кодов или срочных SMS c помощью каскадной рассылки осуществлять не рекомендуется, т.к. сообщение может быть доставлено с задержкой.

Вы можете предложить абоненту выбрать, в какой мессенджер отправить ему SMS-код, и использовать один из вариантов каскада из 2-х каналов. Например, если абонент выбирает способ получения SMS кода в WhatsApp, необходимо использовать маршрутизацию route=wp-sms


Вариант 2
Согласуйте со службой поддержки шаблоны отправляемых сообщений, определив разные типы каскада по каждому типу сообщения исходя из текста SMS.

Как это работает?
Например, у Вас салон красоты и вы отправляете клиенту несколько сообщений:
1. SMS-код при регистрации или записи на прием.
2. Напоминание за 1 день до начала визита.
3. Напоминание за 1 час до начала приема.
4. Уведомление в случае отмены визита.
5. Сообщение с просьбой оценить качество услуг после визита.

В этом случае, мы можем настроить отправку указанных сообщений следующим образом:
1. Обычное SMS, т.к. сообщение срочное.
2. vk-wp-vb-sms.
3. tg-wp-sms или только обычная SMS, т.к. актуальность информации 1 час.
4. tg-wp-sms.
5. tg-vk-wp-vb-sms.

Вы отправляете SMS сообщения как обычно по API. На Вашей стороне вносить изменения не требуется. Просто согласуйте со службой поддержки тексты SMS и варианты каскадной маршрутизации.

Важно! Для использования всех каналов каскадной маршрутизации, пожалуйста, ознакомьтесь с порядком подключения каждого маршрута. С некоторыми мессенджерами требуется согласование имени отправителя и шаблонов планируемых сообщений к отправке.

Если у Вас остались вопросы, пожалуйста, напишите нам на mailto:support@sms-prosto.ru



Подписка на рассылку

Хотите получить доступ к секретным тарифам для избранных клиентов?

Нажимая на кнопку, Вы даете согласие на обработку своих персональных данных

Благодарим за заявку, мы свяжемся с вами в ближайшее время!

Спасибо!
Ваш отзыв принят!

Если вам необходима консультация, пожалуйста, оставьте заявку. Мы свяжемся с вами в ближайшее время!
Обязательное поле

Нажимая кнопку, вы даете согласие на обработку персональных данных в соответствии с условиями, указанными по ссылке

Благодарим за заявку, мы свяжемся с вами в ближайшее время!

Хотите дешевле? Оставьте свои контакты и мы сделаем индивидуальное предложение!
Обязательное поле

Нажимая кнопку, Вы даете согласие на обработку персональных данных в соответствии с условиями, указанными по ссылке

Благодарим за заявку, мы свяжемся с вами в ближайшее время!

Не нашли, что искали? Оставьте контакты и мы обязательно сможем вам помочь!
Обязательное поле

Нажимая кнопку, Вы даете согласие на обработку персональных данных в соответствии с условиями, указанными по ссылке

Благодарим за заявку, мы свяжемся с вами в ближайшее время!

Чем отличаются каналы рассылок?
"Буквенный"
"Специальный"
"СМАРТ"
Нужно ли оформлять договор?
Да
Нет
Да
Время работы канала
Круглосуточно
Отправка осуществляется в будние дни с 10:00 до 20:00 по московскому времени. Планировать рассылку необходимо в первой половине дня (до 12:00 по МСК). Рассылка может быть отправлена на следующий день.
Отправка осуществляется в будние дни с 10:00 до 20:00 по московскому времени. Планировать рассылку необходимо в первой половине дня (до 12:00 по МСК). Рассылка может быть отправлена на следующий день.
Качество доставки
Гарантированная доставка
~85%
~97%
Отчет о доставке сообщений
Да
Нет
Нет
Какой отправитель используется?
"Буквенный, который указан в рассылке (при условии, что отправитель согласован с оператором)"
Цифровой (произвольные номера)
Цифровой (произвольные номера)
Скорость отправки SMS
~1500 SMS в секунду
Отправка осуществляется плавно в течение дня, либо на следующий день
Отправка осуществляется плавно в течение дня, либо на следующий день
Возможность отправлять одиночные SMS
Да
Нет
Нет
Возможность отправлять по API, SMPP
Да
Нет
Нет
Скорость доставки SMS
В течение 2-10 секунд после отправки
Плавная, в течение дня. Если запуск был во второй половине дня, SMS могут быть доставлены на следующий день.
Плавная, в течение дня. Если запуск был во второй половине дня, SMS могут быть доставлены на следующий день.
Количество символов в 1 SMS/сегменте
70 кириллицей или 160 латиницей
66 кириллицей или 156 латиницей
66 кириллицей или 156 латиницей
Максимальное количество сегментов в рассылке
11
3
4
Выберите Ваш город