HTTP/HTTPS Протокол

Взаимодействие с Платформой TERASMS осуществляется по протоколу HTTP/HTTPS. Можно применять как GET, так и POST запросы. По умолчанию предполагается, что текст SMS передается в кодировке utf-8. Если ваш текст в кодировке cp1251 (windows-1251), нужно добавить параметр cp=1251. Все параметры должны быть переданы в соответствии со спецификацией.

Описание параметров

Параметр Значение Описание
login строка обязательный параметр
Логин на Платформе TERASMS
sign строка Подпись запроса. Процедура формирования подписи описана в разделе Авторизация при использовании HTTP API
password строка Пароль партнёра на Платформе TERASMS. Может использоваться вместо параметра sign, однако использование подписи является рекомендуемым способом авторизации
target число обязательный параметр
Номер абонента в международном формате. При необходимости отправить одно и то же сообщение нескольким абонентам, то номера абонентов можно задать через запятую. Пример: 79161111111
sender строка обязательный параметр
Имя отправителя, зарегистрированное для вас на Платформе TERASMS. Имя отправителя, содержащее в себе латинские буквы (в любом регистре), может содержать от 2 до 11 символов, цифровое имя отправителя - от 2 до 15 символов.
message строка обязательный параметр
Текст сообщения. Текст 1 сообщения составляет 160 символов для латиницы и 70 символов для кириллицы. Сообщение, содержащее большее кол-во символов, разбивается на несколько сегментов и доставляется одним сообщением. Сообщение, состоящее более чем из 160 для латиницы или из 70 символов для кириллицы, разбивается на сегменты. Каждый сегмент составляет 153 для латиницы и 67 символов для кириллицы. По умолчанию сообщение может состоять максимум из 10 сегментов.
mass_push 1 или 0 необязательный параметр
Если необходимо отправить разный текст сообщения каждому абоненту, необходимо добавить параметр mass_push=1, поле message оставить пустым, а в поле target передать номера абонентов и тексты сообщений. В этом случае номер телефона и сообщение разделяются одним пробелом, а символ для разделения сообщений можно задать с помощью параметра delimiter
delimiter символ необязательный параметр
Символ для разделения сообщений в поле target. По умолчанию принимается символ перевода на новую строку \n.
flash 1 или 0 необязательный параметр
Для отправки сообщений в формате flash.
relative_time число необязательный параметр Время в секундах, в течение которого предпринимаются попытки доставить сообщение. Если параметр не задан, по умолчанию от 24 до 72 часов в зависимости от оператора.
date_schedule строка необязательный параметр
Дата и время отложенной отправки сообщения, задается в формате Y-m-d H:i:s. Если задан параметр timezone=1, то платформа сама определит часовой пояс абонента и скорректирует время отправки с учетом этих данных. Время отложенной отправки не должно превышать 30 дней от текущего времени. Если timezone не задан, отправка производится в по московскому времени (GMT +3)
timezone 1 необязательный параметр
Указывает учитывать ли часовой пояс абонента при отложенной отправке. Для определения часового пояса абонента номер должен принадлежать российским сотовым операторам, в противном случае планирование идет по московскому времени (GMT +3).
time_from дата и время в формате Y-m-d H:i:s (пример 2017-06-01 17:30:00) необязательный параметр (требует time_to)
Вместе с time_to задает временное окно для отправки смс абоненту с учетом часового пояса. Номер должен принадлежать российским сотовым операторам, если не удалось определить часовой пояс абонента сообщение отправляется сразу
В случае неверного формата даты возвращается код ошибки -130
Если указанное время в регионе абонента еще не наступило, дата отправки откладывается на дату старта (time_from)
Если временное окно в регионе абонента уже прошло, но мы попадаем в рамки по времени в на текущюю дату, то смс уходит сразу. Если смс не попадает в рамки и время прошло, переносим на дату старта на следующие сутки Если смс не попадает в рамки и время не наступил, оставляем текущюю дату в регионе и время старта из time_from
time_to дата и время в формате Y-m-d H:i:s (пример 2017-06-01 20:30:30) необязательный параметр (требует time_from)
Вместе с time_from задает временное окно для отправки смс абоненту с учетом часового пояса.
schedule_id ID рассылки, созданной с помощью метода add_delivery необязательный параметр
Позволяет указать ID именованной рассылки для группировки сообщений. Подробнее об именованных рассылках можно прочитать в описании http api

Описание обычного GET/POST-запроса

GET запросы передаются на адрес:
https://auth.terasms.ru/outbox/send

Пример запроса:
https://auth.terasms.ru/outbox/send/?login=terasms&password=12345&target=79017654321&sender=terasms&message=test

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

Возможные варианты реализации на языке программирования php

Отправка одиночного сообщения

GET:

$api_uri = 'https://auth.terasms.ru/outbox/send/';

$query_array = array(
    'login' => 'login',
    'password' => 'password',
    'target' => 'target',
    'message' => 'message',
    'sender' => 'sender'
);

$get_string = http_build_query( $query_array );
$id = file_get_contents( $api_uri . '?' . $get_string);

POST:

$api_uri = 'https://auth.terasms.ru/outbox/send/';

$query_array = array(
    'login' => 'login',
    'password' => 'password',
    'target' => 'target',
    'message' => 'message',
    'sender' => 'sender'
    );

$context = stream_context_create(array(
    'http' => array(
        'method'  => 'POST',
        'content' =>http_build_query( $query_array ),
        'timeout' => 10,
    ),
));

$id = file_get_contents( $api_uri, false, $context);

JSON:

$api_uri = 'https://auth.terasms.ru/outbox/send/json';

$query_array = array(
    'login' => 'login',
    'password' => 'password',
    'target' => 'target',
    'message' => 'message',
    'sender' => 'sender'
);

$context = stream_context_create(array(
    'http' => array(
        'method' => 'POST',
        'header' => "Content-Type: application/json\r\n",
        'timeout' => 10,
        'content' => json_encode( $query_array )
    )
));

$response = file_get_contents( $api_uri, false, $context );
$responseData = json_decode( $response, true );

XML:

$api_uri = 'https://auth.terasms.ru/outbox/send/json';

$context = stream_context_create(array(
    'http' => array (
        'method' => "POST",
        'content' => $query_xml,
        'timeout' => 10,
        'header' => "Content-Type: text/xml; charset=utf-8"
    )
));
$response = file_get_contents( $api_uri, false, $context );
$query_xml:
<?xml version="1.0"?>
    <request>
        <login>login</login>
        <password>password</password>
        <target>target</target>
        <message>message</message>
        <sender>sender</sender>
    </request>

Отправка сообщения нескольким абонентам

POST:

$api_uri = 'https://auth.terasms.ru/outbox/send/';
    $query_array = array(
        'login' => 'login',
        'password' => 'password',
        'target' => 'target1, target2, target3',
        'message' => 'message',
        'sender' => 'sender'
    );
    $context = stream_context_create(array(
        'http' => array(
            'method'  => 'POST',
            'content' =>http_build_query( $query_array ),
            'timeout' => 10,
        ),
));
    $ids = file_get_contents( $api_uri, false, $context);
Ответ придет в формате id1, id2, id3

JSON:

$api_uri = 'https://auth.terasms.ru/outbox/send/json';

$query_array = array(
    'login' => 'login',
    'password' => 'password',
    'target' => 'target1, target2, target3',
    'message' => 'message',
    'sender' => 'sender'
);

$context = stream_context_create(array(
    'http' => array(
        'method' => 'POST',
        'header' => "Content-Type: application/json\r\n",
        'timeout' => 10,
        'content' => json_encode( $query_array )
    )
));

$response = file_get_contents( $api_uri, false, $context );
$responseData = json_decode( $response, true );

XML:

$api_uri = 'https://auth.terasms.ru/outbox/send/json';

$context = stream_context_create(array(
    'http' => array (
        'method' => "POST",
        'content' => $query_xml,
        'timeout' => 10,
        'header' => "Content-Type: text/xml; charset=utf-8"
    )
));
$response = file_get_contents( $api_uri, false, $context );
$query_xml:
<?xml version="1.0"?>
    <request>
        <login>login</login>
        <password>password</password>
        <target>target1, target2, target3</target>
        <message>message</message>
        <sender>sender</sender>
    </request>

Отправка разных сообщений разным абонентам, mass_push

POST:

$api_uri = 'https://auth.terasms.ru/outbox/send/';
$query_array = array(
    'login' => 'login',
    'password' => 'password',
    'target' => 'target1 message1|target2 message2|target3 message3',
    'message' => '',
    'sender' => 'sender',
    'mass_push' => '1',
    'delimiter' => '|'
);
$context = stream_context_create(array(
    'http' => array(
        'method'  => 'POST',
        'content' =>http_build_query( $query_array ),
        'timeout' => 10,
    ),
));
$id = file_get_contents( $api_uri, false, $context);
Ответ придет в формате id1, id2, id3

JSON:

$api_uri = 'https://auth.terasms.ru/outbox/send/json';

$query_array = array(
    'login' => 'login',
    'password' => 'password',
    'target' => 'target1 message1|target2 message2|target3 message3',
    'message' => '',
    'sender' => 'sender',
    'mass_push' => '1',
    'delimiter' => '|'
);

$context = stream_context_create(array(
    'http' => array(
        'method' => 'POST',
        'header' => "Content-Type: application/json\r\n",
        'timeout' => 10,
        'content' => json_encode( $query_array )
    )
));

$response = file_get_contents( $api_uri, false, $context );
$responseData = json_decode( $response, true );

XML:

$api_uri = 'https://auth.terasms.ru/outbox/send/json';

$context = stream_context_create(array(
    'http' => array (
        'method' => "POST",
        'content' => $query_xml,
        'timeout' => 10,
        'header' => "Content-Type: text/xml; charset=utf-8"
    )
));
$response = file_get_contents( $api_uri, false, $context );
$query_xml:
<?xml version="1.0"?>
    <request>
        <login>login</login>
        <password>password</password>
        <target>target1 message1|target2 message2|target3 message3</target>
        <message></message>
        <sender>sender</sender>
        <mass_push>1</mass_push>
        <delimiter>|</delimiter>
    </request>

Возможные статусы ошибок

Статус Описание
-1 Неверный логин или пароль
-20 Пустой текст сообщения
-30 Пустой номер абонента
-40 Неправильно задан номер абонента
-45 Превышено количество номеров
-50 Неправильно задано имя отправителя
-60 Рассылка по данному направлению недоступна
-70 Недостаточно средств на счете
-80 Не установлена стоимость рассылки по данному направлению
-90 Рассылка запрещена
-100 Не указаны необходимые параметры
-110 Номер в черном списке
-120 Некорректно задано время отложенной отправки
-130 Некорректно задано временное окно отправки
-140 Передан некорректный ID рассылки
-160 Превышен дневной лимит рассылки (Вы можете установить максимальную сумму ежедневной рассылки после согласования с Вашим менеджером).

Формирование запроса в формате JSON

Пример запроса:


> POST auth.terasms.ru/outbox/send/json

{
	"login": "login",
	"password": "secret",
	"target": 71234567890,
	"message": "ку-ку",
	"sender": "terasms.ru"
}
                        

Пример ответа:


{
  "status": 0,
  "status_description": "OK",
  "message_infos": [
    {
      "msisdn": "78001234567890",
      "id": "566668915",
      "status": 0
    }
  ]
}
                        

Формирование запроса в формате XML

Пример запроса:


> POST auth.terasms.ru/outbox/send/xml

<?xml version="1.0"?>
<request>
    <login>login</login>
    <password>password</password>
    <target>71234567890</target>
    <message>ку-ку</message>
    <sender>terasms.ru</sender>
</request>
                         

Пример ответа:


<?xml version="1.0"?>
<response>
    <status>0</status>
    <status_description>OK</status_description>
    <message_infos>
        <message_info>
            <msisdn>71234567890</msisdn>
            <status>0</status>
        </message_info>
    </message_infos>
</response>
                        

Группировка сообщений в рассылки

Вы можете группировать сообщения в именованные рассылки — это даёт возможность получать отчёты, сгруппированные по этим рассылкам.

Для этого необходимо создать рассылку, отправив следующий запрос: https://auth.terasms.ru/outbox/add_delivery?login=terasms&password=12345&name=Имя%рассылки

В качестве ответа Вам придёт ID рассылки. В системе будет создана рассылка с именем "Имя рассылки". Если параметр name не указан, то в качестве имени рассылки будет использоваться текущая дата. Вы сможете увидеть свою рассылку в личном кабинете на странице График рассылки. Кроме того, на странице "Отчёты" будет отображена статистика по именованным рассылкам.
Обращаем Ваше внимание на то, что данные по рассылкам в системе обновляются не в режиме реального времени, а в течении 5-10 минут.

Затем при отправке сообщения необходимо добавлять параметр schedule_id со значением, полученным при создании рассылки: https://auth.terasms.ru/outbox/send/?login=terasms&password=12345&target=79017654321 &sender=terasms&message=test&schedule_id=1234

Каждое отправленное таким образом сообщение будет добавлено к Вашей рассылке "Имя рассылки"

Отправка нескольких сообщений одним запросом

Для отправки нескольких сообщений одним запросом существует метод msend_json. При использовании метода тело запроса должно быть в формате JSON, ответ также приходит в JSON. Параметры сообщения совпадают с параметрами, используемыми в методе outbox/send. Так же существует параметр sms_id, в котором вы можете указать любой идентификатор сообщения. Этот идентификатор будет присутствовать в ответе платформы вместе с остальной информацией о сообщении.

Пример запроса:


> POST http://auth.terasms.ru/outbox/msend_json
{
	"login": "login",
	"password": "password",
	"smsPackage": [
		{
			"target": 78002223344,
            "sms_id": 1,
			"sender": "terasms.ru",
			"message": "test"
		},
		{
			"target": 78002223345,
            "sms_id": 2,
			"sender": "terasms.ru",
			"message": "test2"
		}
	]
}

Ответ:


[
    {
        "sms_id": 1,
        "message_id": "365214379"
    },
    {
        "sms_id": 2,
        "message_id":"365214380"
    }
]
                        


Получение статусов нескольких сообщений одним запросом

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

Готовы начать работу?
Если остались вопросы, свяжитесь с нами по телефону: 8 800 555-9412