Часто задаваемый вопрос

Все категории » Интеграция / Работа с API

Руководство по взаимодействию с сервисом коротких сообщений (SMS) на основе HTTPS протокола в JSON формате

Последнее Обновление 7 месяцев назад

Общие принципы отправки

На определенный адрес сервера отправляются JSON документы (описание JSON документов, их назначение и адреса сервера приведены ниже). При этом используется POST метод.

Заголовки отправляемых данных должны содержать:

Content-Type: application/json; charset=utf-8

Кодировка JSON документов UTF-8.

Пример передачи JSON документа на php

$param = array(
    'security' => array('login' => 'Логин', 'password' => 'Пароль'),
    'type' => 'sms'
);
$param_json = json_encode($param, true);
// JSON-документ
$href = 'https://имя_хоста/sendsmsjson.php'; // адрес сервера
$ch = curl_init();
curl_setopt($ch, CURLOPT_HTTPHEADER, array('Content-Type: application/json','charset=utf-8','Expect:'));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, $param_json);
curl_setopt($ch, CURLOPT_TIMEOUT, 600);
curl_setopt($ch, CURLOPT_URL, $href);
curl_setopt ($ch, CURLOPT_SSL_VERIFYPEER, 0);
curl_setopt ($ch, CURLOPT_SSL_VERIFYHOST, 0);
$res = curl_exec($ch);
$result = json_decode($res, true);
curl_close($ch);
print_r($result);

Отправка SMS

Адрес сервера:

https://имя_хоста/sendsmsjson.php

JSON-документ:

{
	"security":{
		"login":"логин",
		"password":"пароль"
	},
	"type":"sms",
	"message":[
		{
			"type":"sms",
			"sender":"Отправитель 1",
			"text":"Текст сообщения 1",
			"name_delivery":"Рассылка 1",
			"translite":"1",
			"abonent":[
				{"phone":"79033256699","number_sms":"1","client_id_sms":"100","time_send":"2016-11-09 12:40","validity_period":"2016-11-09 13:30"},
				{"phone":"79033256699","number_sms":"2","client_id_sms":"101"}
			]
		},
		{
			"type":"sms",
			"sender":"Отправитель 2",
			"text":"Текст сообщения 2",
			"name_delivery":"Рассылка 2",
			"abonent":[
				{"phone":"79033256699","number_sms":"1","client_id_sms":"111"},
				{"phone":"79033256699","number_sms":"2","client_id_sms":"112"}
			]
		}
	]
}

PHP-данные:

$param = array(
    'security' => array('login' => 'логин', 'password' => 'пароль'),
    'type' => 'sms',
    'message' => array(
        array(
            'type' => 'sms',
            'sender' => 'Отправитель 1',
            'text' => 'Текст сообщения 1',
            'name_delivery' => 'Рассылка 1',
            'translite' => '1',
            'abonent' => array(
                array('phone' => '79033256699', 'number_sms' => '1', 'client_id_sms' => '100', 'time_send' => '2016-11-09 12:40', 'validity_period' => '2016-11-09 13:30'),
                array('phone' => '79033256699', 'number_sms' => '2', 'client_id_sms' => '101')
            )
        ),
 	array(
            'type' => 'sms',
            'sender' => 'Отправитель 2',
            'text' => 'Текст сообщения 2',
            'name_delivery' => 'Рассылка 2',
            'abonent' => array(
                array('phone' => '79033256699', 'number_sms' => '1', 'client_id_sms' => '111'),
                array('phone' => '79033256699', 'number_sms' => '2', 'client_id_sms' => '112')
            )
        )
    )
);

Где:

security - данные для авторизации:
- login - ваш логин в системе;
- password - ваш пароль в системе;
type - тип запроса (sms - отправка SMS);
message - данные отправляемых SMS:
- type - тип отправляемого SMS сообщения (sms - обычная SMS);
- sender – отправитель SMS. Именно это значение будет выводиться на телефоне абонента в поле от кого SMS;
- text – текст SMS;
- name_delivery – Название рассылки. По умолчанию "Шлюз";
- translite - транслитерация текста SMS с кириллицы на латиницу (не обязательный параметр). Для транслитерации данный параметр должен быть равен 1;
- abonent - получатели SMS;
  - phone – номер абонента, которому адресована SMS. В международном формате, например, 79000000001 (Для России), 380442589632 (Для Украины) и т.д.;
  - number_sms - номер сообщения в пределах отправляемого JSON документа;
  - client_id_sms - число. Необязательный параметр, позволяет избежать повторной отправки. Если раннее с этого аккаунта уже было отправлено SMS с таким номером, то повторная отправка не производится, а возвращается номер ранее отправленного SMS;
  - time_send – дата и время отправки в формате: YYYY-MM-DD hh:mm где, YYYY-год, MM-месяц, DD-день, hh-часы, mm-минуты. Если не задано, то SMS отправляется сразу же;
  - validity_period – дата и время, после которых не будут делаться попытки доставить SMS в формате: YYYY-MM-DD hh:mm, где YYYY-год, MM-месяц, DD-день, hh-часы, mm-минуты. Если не задано, то SMS имеет максимальный срок жизни.

В ответ может быть выдан один из следующих JSON-документов:

В случае возникновения ошибки в отправляемом JSON-документе

JSON:

{
	"error":"текст ошибки"
}

PHP (массив, полученный через php функцию json_decode):

array ('error' => 'текст ошибки')

error - текст ошибки может принимать следующие значения:

Неправильный формат JSON документа;
Неправильный логин или пароль;
POST данные отсутствуют;

В случае получения правильного JSON-документа:

JSON:

{
	"sms":[
		{"number_sms":"1","id_sms":"ID SMS в системе для проверки статуса","parts":"1","action":"Статус/сообщение об ошибке"},
		{"number_sms":"2","id_sms":"ID SMS в системе для проверки статуса","parts":"1","action":"Статус/сообщение об ошибке"}
	]
}

PHP (массив, полученный через php функцию json_decode):

Array(
 [sms] => Array(
 	[0] => Array ( [number_sms] => 1 [id_sms] => ID SMS в системе для проверки статуса [parts] => 1 [action] => Статус/сообщение об ошибке )
 	[1] => Array ( [number_sms] => 2 [id_sms] => ID SMS в системе для проверки статуса [parts] => 1 [action] => Статус/сообщение об ошибке )
 )
)

Где:

number_sms - номер сообщения указанный при отправке JSON документа;
id_sms - номер SMS сообщения. Используется для проверки статуса SMS. Если в процессе отправки SMS произошла ошибка, то id_sms не передается;
parts - количество частей SMS;
action - статус сообщения («send»), если SMS была отправлена. Или сообщение об ошибке, если в процессе отправки SMS произошла ошибка:

    1. У нас закончились SMS. Для разрешения проблемы свяжитесь с менеджером.
    2. Закончились SMS.
    3. Аккаунт заблокирован.
    4. Укажите номер телефона.
    5. Номер телефона присутствует в стоп-листе.
    6. Данное направление закрыто для вас.
    7. Данное направление закрыто.
    8. Недостаточно средств для отправки SMS. SMS будет отправлена как только вы пополните счет по данному направлению.
    9. Текст SMS отклонен модератором.
    10. Нет отправителя.
    11. Отправитель не должен превышать 15 символов для цифровых номеров и 11 символов для буквенно-числовых.
    12. Номер телефона должен быть меньше 15 символов.
    13. Нет текста сообщения.
    14. Нет ссылки.
    15. Такого отправителя Нет.
    16. Отправитель не прошел модерацию.
    17. Данное сообщение уже было отправлено.

Запрос статуса SMS сообщения

Адрес сервера:

https://имя_хоста/sendsmsjson.php

JSON-документ:

{
	"security":{
		"login":"логин",
		"password":"пароль"
	},
	"type":"state",
	"get_state":["ID SMS в системе для проверки статуса","ID SMS в системе для проверки статуса"]
}

PHP-данные:

$param = array(
    'security' => array('login' => 'логин', 'password' => 'пароль'),
    'type' => 'state',
    'get_state' => array('ID SMS в системе для проверки статуса', 'ID SMS в системе для проверки статуса')
);

Где:

security - данные для авторизации:
- login - ваш логин в системе;
- password - ваш пароль в системе;
type - тип запроса (state - статусы SMS сообщений);
get_state - номера SMS сообщений, полученные в ответном JSON-документе в процессе отправки SMS сообщения.

В ответ может быть выдан один из следующих JSON-документов:

В случае возникновения ошибки в отправляемом JSON-документе:

JSON:

{
	"error":"текст ошибки"
}

PHP (массив, полученный через php функцию json_decode):

array ('error' => 'текст ошибки')

error - текст ошибки может принимать следующие значения:

Неправильный формат JSON документа;
Неправильный логин или пароль;
POST данные отсутствуют;

В случае получения правильного JSON-документа:

JSON:

{
	"state":[
		{"id_sms":"ID SMS в системе для проверки статуса","time":"2016-03-02 18:31:38","state":"Статус/сообщение об ошибке","num_parts":"2","price":"1.15"},
		{"id_sms":"ID SMS в системе для проверки статуса","time":"2016-03-02 18:31:39","state":"Статус/сообщение об ошибке","num_parts":"1","price":"1.15"}
	]
}

PHP (массив, полученный через php функцию json_decode):

Array (
 [state] => Array (
 	[0] => Array ( [id_sms] => ID SMS в системе для проверки статуса [time] => 2016-03-02 18:31:38 [state] => Статус/сообщение об ошибке [num_parts] => 2 [price] => 1.15 )
 	[1] => Array ( [id_sms] => ID SMS в системе для проверки статуса [time] => 2016-03-02 18:31:39 [state] => Статус/сообщение об ошибке [num_parts] => 1 [price] => 1.15 )
 )
)

Где:

id_sms - номер SMS сообщения, полученный в ответном JSON-документа в процессе отправки SMS сообщения.
time - время изменения статуса.
state - статус сообщения:
1. «send» - статус сообщения не получен. В этом случае передается пустой time (time="");
2. «not_deliver» - сообщение не было доставлено. Конечный статус (не меняется со временем);
3. «expired» - абонент находился не в сети в те моменты, когда делалась попытка доставки. Конечный Статус (не меняется со временем;
4. «deliver» - сообщение доставлено. Конечный статус (не меняется со временем);
5. «partly_deliver» - сообщение было отправлено, но статус так и не был получен. Конечный статус (не меняется со временем). В этом случае для разъяснения причин отсутствия статуса необходимо связаться со службой тех. поддержки;
num_parts - Количество частей в СМС.
price - Цена за одну часть СМС.

Запрос проверки баланса

Адрес сервера:

https://имя_хоста/sendsmsjson.php

JSON-документ:

{
	"security":{
		"login":"логин",
		"password":"пароль"
	},
	"type":"balance"
}

PHP-данные:

$param = array(
    'security' => array('login' => 'логин', 'password' => 'пароль'),
    'type' => 'balance'
);

Где:

security - данные для авторизации:
- login - ваш логин в системе;
- password - ваш пароль в системе;
type - тип запроса (balance - баланс и количество доступных SMS по операторам).

В ответ может быть выдан один из следующих JSON-документов:

В случае возникновения ошибки в отправляемом JSON-документе:

JSON:

{
	"error":"текст ошибки"
}

PHP (массив, полученный через php функцию json_decode):

array ('error' => 'текст ошибки')

error - текст ошибки может принимать следующие значения:

Неправильный формат JSON документа;
Неправильный логин или пароль;
POST данные отсутствуют;

В случае получения правильного JSON-документа:

JSON:

{
	"money":{"currency":"RUR","value":"150"},
	"sms":[
		{"area":"МТС ","number":"140"},
		{"area":"Мегафон","number":"141"}
	]
}

PHP (массив, полученный через php функцию json_decode):

Array (
 [money] => Array ( [currency] => RUR [value] => 356.1 )
 [sms] => Array (
 	[0] => Array ( [area] => МТС [number] => 356.1 )
 	[1] => Array ( [area] => Мегафон [number] => 356.1 )
 )
)

Где:

money - баланс пользователя:
- currency - валюта баланса;
- value - сумма средств;
sms - количество доступных SMS сообщений по направлениям:
- area - направление в котором может быть отправлено SMS;
- number - количество доступных SMS сообщений для данного направления.

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

Пример

У вас на балансе 10 y.e. Стоимость SMS сообщения отправленного на МТС составляет 1 y.e. Стоимость SMS сообщения отправленного на Мегафон составляет 2 y.e.

При этом вам вернется документ следующего содержания. JSON:

{
	"money":{"currency":"RUR","value":"10"},
	"sms":[
		{"area":"МТС ","number":"10"},
		{"area":"Мегафон","number":"5"}
	]
}

PHP (массив, полученный через php функцию json_decode):

Array (
 [money] => Array ( [currency] => RUR [value] => 10 )
 [sms] => Array (
 	[0] => Array ( [area] => МТС [number] => 10 )
 	[1] => Array ( [area] => Мегафон [number] => 5 )
 )
)

Запрос на получения списка отправителей

Адрес сервера:

https://имя_хоста/sendsmsjson.php

JSON-документ:

{
	"security":{
		"login":"логин",
		"password":"пароль"
	},
	"type":"originator"
}

PHP-данные:

$param = array(
    'security' => array('login' => 'логин', 'password' => 'пароль'),
    'type' => 'originator'
);

Где:

security - данные для авторизации:
- login - ваш логин в системе;
- password - ваш пароль в системе;
type - тип запроса (originator - список отправителей).

В ответ может быть выдан один из следующих JSON-документов:

В случае возникновения ошибки в отправляемом JSON-документе:

JSON:

{
	"error":"текст ошибки"
}

PHP (массив, полученный через php функцию json_decode):

array ('error' => 'текст ошибки')

error - текст ошибки может принимать следующие значения:

Неправильный формат JSON документа;
Неправильный логин или пароль;
POST данные отсутствуют;

В случае получения правильного JSON-документа:

JSON:

{
	"any_originator":"FALSE",
	"list_originator":[
		{"state":"completed","originator":"Отправитель 1"},
		{"state":"order","originator":"Отправитель 2"},
		{"state":"rejected","originator":"Отправитель 3"}
	]
}

PHP (массив, полученный через php функцию json_decode):

Array ( 
 [any_originator] => FALSE
 [list_originator] => Array (
 	[0] => Array ( [state] => completed [originator] => Отправитель 1 )
 	[1] => Array ( [state] => order  [originator] => Отправитель 2 )
 	[2] => Array ( [state] => rejected  [originator] => Отправитель 3 )
 )
)

Где:

any_originator - TRUE/FALSE - может ли клиент отправлять от любого отправителя или только от заранее одобренных. Если TRUE, то клиент может использовать любого отправителя. При этом список отправителей не возвращается. FALSE – можно использовать только отправителей со статусом «completed»;
state - статус отправителя:
1. «order» - оформляется;
2. «completed» - готов к использованию;
3. «rejected» – отклонен.

Запрос входящих SMS

Адрес сервера:

https://имя_хоста/sendsmsjson.php

JSON-документ:

{
	"security":{
		"login":"логин",
		"password":"пароль"
	},
	"type":"incoming",
	"time":{
		"start":"2016-08-25 15:28:37",
		"end":"2012-02-31 12:23:00"
	}
}

PHP-данные:

$param = array(
    'security' => array('login' => 'логин', 'password' => 'пароль'),
    'type' => 'incoming',
    'time' => array('start' => '2012-01-31 12:23:00', 'end' => )
);

Где:

security - данные для авторизации:
- login - ваш логин в системе;
- password - ваш пароль в системе;
type - тип запроса (incoming - cписок входящих SMS);
time - время входящие SMS:
- start - время (не включительно), с которого запрашиваются входящие SMS;
- end - время (не включительно), по которое запрашиваются входящие SMS. Не обязательный параметр. Если не задан, то будут возвращены все смс.

В ответ может быть выдан один из следующих JSON-документов:

В случае возникновения ошибки в отправляемом JSON-документе:

JSON:

{
	"error":"текст ошибки"
}

PHP (массив, полученный через php функцию json_decode):

array ('error' => 'текст ошибки')

error - текст ошибки может принимать следующие значения:

Неправильный формат JSON документа;
Неправильный логин или пароль;
POST данные отсутствуют;

Категории Заявок

Техническая поддержка / Работа с API

Часто задаваемый вопрос

Руководство по взаимодействию с сервисом коротких сообщений (SMS) на основе HTTPS протокола в JSON формате

Общие принципы отправки

Пример передачи JSON документа на php

Отправка SMS

В случае возникновения ошибки в отправляемом JSON-документе

В случае получения правильного JSON-документа:

Запрос статуса SMS сообщения

В случае возникновения ошибки в отправляемом JSON-документе:

В случае получения правильного JSON-документа:

Запрос проверки баланса

В случае возникновения ошибки в отправляемом JSON-документе:

В случае получения правильного JSON-документа:

Запрос на получения списка отправителей

В случае возникновения ошибки в отправляемом JSON-документе:

В случае получения правильного JSON-документа:

Запрос входящих SMS

В случае возникновения ошибки в отправляемом JSON-документе:

Пожалуйста, подождите!