SMSPILOT.RU API v2.4.16 HTTP/XML/JSON
2018-09-06
Общение с сервисом осуществляется при помощи отправки XML или JSON запросов в кодировке UTF-8 на заданный адрес по протоколу HTTP/HTTPS методом POST.

Исторически сложилось что API-1 из-за простоты стал развиваться быстрее, документация там актуальнее и методов работы больше. Каким API пользоваться решайте исходя из задач.

Адрес сервиса: http://smspilot.ru/api2.php

POST /api2.php HTTP/1.1
Host: smspilot.ru
Content-Type: text/xml
Content-Length: 122
Connection: close

<?xml version="1.0" encoding="utf-8"?>
<info apikey="XXXXXXXXXXXXYYYYYYYYYYYYZZZZZZZZXXXXXXXXXXXXYYYYYYYYYYYYZZZZZZZZ" />

1.	Авторизация пользователя происходит путем передачи API-ключа в параметрах документа. Реальный API-ключ доступен в личном кабинете https://www.smspilot.ru/my-settings.php#api
2.	В версии 2.3 появилась возможна авторизация по логину и паролю к личному кабинету smspilot.ru.

<?xml version="1.0" encoding="utf-8"?>
<info login="info@smspilot.ru" password="123456"  />

3.	Наряду с POST/XML и POST/JSON  поддерживается обычные GET/POST запросы, где xml или json передается в виде строки:
http://smspilot.ru/api2.php?xml=.....
http://smspilot.ru/api2.php?json=.....

Содержание
1.	Отправка SMS
2.	Проверка статусов SMS
3.	Баланс
4.	Информация о пользователе
5.	Входящие
6.	Отладка и коды ошибок
1. Отправка SMS
XML
<?xml version="1.0" encoding="utf-8"?>
<send apikey="XYZ" test="0" cost="0">
    <sms id="12345" from="SMSPILOT" to="79131437355">Ура работает!</sms>
    <sms id="12346" from="ADVOKAT" to="89087964782" send_datetime="2012-10-18 18:00:00">Не забываем htmlspecialchars!</sms>
</send>

JSON
{"apikey": "XYZ",
"test": 0,
"cost": 0,
"send": [
  {"id": "12345", "from": "SMSPILOT", "to": "79087964781", "text": "Ура \"SMSPILOT\"!"},
  {"id": "12346", "from": "ADVOKAT", "to": "79087964782", "text": "json_encode!"}
]}

1)	apikey – буквенно-цифровой ключ (http://www.smspilot.ru/my.php)
2)	to – телефонный номер абонента, целое число
3)	id – уникальный код сообщения в вашей системе, целое число.
4)	from – имя отправителя,  по умолчанию задан в настройках или smspilot.ru
5)	send_datetime – GMT время отложенной отправки сообщения,
в формате YYYY-MM-DD HH:MM:SS или в UNIXSTAMP
6)	callback – URL адрес скрипта для приѐма статуса, например http://ya.ru/status.php. При смене статуса сообщения этот скрипт вызывается с параметрами server_id, status и error: http://ya.ru/status.php?server_id=1233211233&status=2&error=0
Нужно обработать за 10 секунд и вернуть текст: OK
Можно установить и протестировать в личном кабинете
https://www.smspilot.ru/my-settings.php#api
7)	callback_method – get или post вызов скрипта приёма статусов (по умолчанию get)
8)	ttl - «Время жизни сообщения» в минутах от 1 до 1440. Максимальное время, в течение которого сообщение должно быть доставлено на телефон. Если в течение этого времени доставка не возможна (абонент вне зоны действия сети, телефон выключен), сообщение не будет доставлено вовсе. Внимание, данная функция не работает для некоторых направлений, например для CDMA телефонов.
9)	test – 0 – обычная отправка (по-умолчанию), 1 – без передачи операторам
10)	cost – 0 – обычная отправка (по-умолчанию), 1 – рассчитать стоимость

Отправитель from может содержать:
- текст латиницей, цифры, символы "-" и "." длиной 3-11 символов (например "MYSHOP.RU", "Taxi-12.Ru")
- номер длиной 10-16 цифр в международном формате, без знака "+", например 79087964781

Длина одного SMS сообщения составляет 70 символов кириллицей либо 160 символов латиницей. Если количество символов превышает максимально допустимое, то SMS разбивается на кусочки по 67 символов для сообщения кириллицей и по 153 символа для сообщения латиницей. Максимальное количество частей 10.
Одно и то же сообщение, на тот же номер можно будет отправить только через несколько минут.

На полученный запрос сервис возвращает список отправляемых сообщений.
XML
<?xml version="1.0" encoding="utf-8"?>
<send server_packet_id="1234" balance="10000" cost="0.89"  >
    <sms id="12345" server_id="10005" from="SMSPILOT" to="79131437355" parts="1" price="0.29" status="0" error="0" send_datetime="" country="RU" operator="MTS">Ура &quot;SMSPILOT&quot; работает!</sms>
    <sms id="12346" server_id="10006" from="ADVOKAT" to="79087964782" price="0.60" parts="1" status="3" error="0" send_datetime="2012-10-18 18:00:00" country="RU" operator="TELE2">Не забываем htmlspecialchars!</sms>
</send>

JSON
{
    "send": [
        {
            "id": "12345",
            "server_id": "10005",
            "from": "SMSPILOT",
            "to": "79131437355",
            "text": "Ура \"SMSPILOT\" работает!",
            "parts": "1",
            "price": "0.29",
            "status": "0",
            "error": "0",
            "send_datetime": "0000-00-00 00:00:00",
            "country": "RU",
            "operator": "MTS"

        },
        {
            "id": "12346",
            "server_id": "10006",
            "from": "ADVOKAT",
            "to": "79087964782",
            "text": "json_encode в помощь!",
            "parts": "1",
            "price": "0.60",
            "status": "0",
            "error": "0",
            "send_datetime": "2012-10-18 18:00:00",
            "country": "RU",
            "operator": "TELE2"

        }
    ]
    "server_packet_id": "1234",
    "balance": "10000",
    "cost": "0.89",
}

1)	id – уникальный код сообщения в вашей системе, целое число.
2)	server_id – уникальный код присвоенный сообщению шлюзом, целое число
3)	from – имя отправителя
4)	to – телефонный номер абонента
5)	price – стоимость SMS, http://www.smspilot.ru/price.php
6)	parts – кол-во частей сообщения
7)	status – код статуса (-2 – не принято, 0 – принято)
8)	error – код ошибки, если сообщение не принято, см. в конце этого документа
9)	server_packet_id – код всего пакета назначенный шлюзом
10)	balance – баланс после отправки
11)	send_datetime – дата/время отложенной отправки
12)	country – страна
13)	operator - оператор

Рассчет стоимости
<?xml version="1.0" encoding="utf-8"?>
<send apikey="XYZ" cost="1">
    <sms to="79131437355">Сколько стоит SMS?</sms>
</send>
	{"apikey": "XYZ",
"cost": "1",
"send": [
  {"to": "79087964781", "text": "Сколько стоит?"}
]}
	
<?xml version="1.0" encoding="utf-8"?>
<cost>1.25</cost>	{"cost": "1.25"}	

2. Проверка статусов SMS
2.1 По списку серверных кодов сообщений

XML
<?xml version="1.0" encoding="utf-8"?>
<check apikey="XYZ">
    <sms server_id="10005" />
    <sms server_id="10006" />
</check>

JSON
{
    "apikey": "XYZ",
    "check": [
        {"server_id" : "10005"},
        {"server_id" : "10006"}
    ]
}

server_id – код сообщения назначенный шлюзом

2.2 По серверному коду всего пакета

XML
<?xml version="1.0" encoding="utf-8"?>
<check apikey="XYZ" server_packet_id="1234" />

JSON
{
    "apikey": "XYZ",
    "check": true,
    "server_packet_id" : "1234"
}

server_packet_id – код пакета назначенный шлюзом

2.3 Ответ сервера
На запросы 2.1 и 2.2 сервер возвращает список статусов.

XML
<?xml version="1.0" encoding="utf-8"?>
<check>
    <sms id="12345" server_id="10005" status="1" modified="2011-08-11 14:35:00" />
    <sms id="12346" server_id="10006" status="2" modified="2011-08-11 15:12:22" />
</check>

JSON
{
    "check": [
        {"id": "12345", "server_id" : "10005", "status": "1", "modified": "2011-08-11 14:35:00"},
        {"id": "12346", "server_id" : "10006", "status": "2", "modified": "2011-08-11 15:12:22"}
    ]
}

1)  id – код сообщения в вашей системе
2) server_id – код сообщения назначенный шлюзом
3) status – код статуса (см. 2.4)
4) modified – дата и время последнего изменения (доставки)

2.4 Коды статуса SMS
-2	сервер не получал это сообщение (ID не найден, ошибка)	
-1	сообщение не доставлено (телефон абонента выключен, оператор не поддерживается)	
0	принято	
1	у оператора	
2	доставлено	
3	отложенная отправка (send_datetime)	

Сообщения, у которых статус 0 или 1, нужно проверить через 1-2 минуты.
Лучше получать статусы на callback URL (см. параметры отправки SMS)
3. Баланс
XML
<?xml version="1.0" encoding="utf-8"?>
<balance apikey="XYZ" return="rur" />

JSON
{
    "apikey": "XYZ",
    "balance": "rur"
}

Возвращает текущий баланс пользователя  в рублях (rur) и в  примерном кол-ве оставшихся SMS (sms)
XML
<?xml version="1.0" encoding="utf-8"?>
<balance>405.60</balance>

JSON
{"balance": 405.60}

4. Информация о пользователе

XML
<?xml version="1.0" encoding="utf-8"?>
<info apikey="XYZ" />

JSON
{
    "apikey": "XYZ",
    "info": true
}

Результат
XML
<?xml version="1.0" encoding="utf-8"?>
<info>
    <id>1</id>
    <tariff_id>1</tariff_id>
    <email>info@smspilot.ru</email>
    <phone>79087964781</phone>
    <balance>405.60</balance>
    <date>2012-01-21 07:25</balance>
    <senders>smspilot.ru,TestSMS</senders>
    <default_sender>smspilot</default_sender>
    <any_sender>0</any_sender>
</info>

JSON
{
    "info": {
        "id":"1",
        "tariff_id":"1",
        "email":"info@smspilot.ru",
        "phone":"79087964781",
        "balance":"999737",
        "date":"2012-01-21 07:25",
        "senders":"mySHOP,SCHOOL,SERVER4,my-site.ru",
        "default_sender":"SERVER4",
        "any_sender":"1"
    }
}

* Количество свойств периодически меняется и зависит от версии шлюза. 

Id - номер договора
tariff_id - номер тарифа
email - email пользователя
phone - телефон пользователя
balance - текущий баланс (в рублях)
date - дата/время регистрации
senders - список разрешенных имен отправителя (через запятую)
default_sender - имя отправителя по умолчанию
any_sender – возможность подставлять любое имя
5. Входящие
XML
<?xml version="1.0" encoding="utf-8"?>
<inbound apikey="XYZ" since="YYYY-MM-DD HH:II:SS" />

JSON
{
    "apikey": "XYZ",
    "inbound": true
}

или

{
    "apikey": "XYZ",
    "inbound": true,
    "since": "YYYY-MM-DD HH:II:SS",
}

Где since – это дата/время с которого начинается выборка (GMT) (v2.3.3)
Может принимать значение new – выбрать только ещё не прочитанные сообщения, флаг seen = 0

Возвращает список зарегистрированных входящих SMS:

XML
<?xml version="1.0" encoding="utf-8"?>
<inbound>
    <sms id="12345" phone="79087964781" num="79021121075" created="2011-09-20 20:15" seen="0">1234 Ура работает!</sms>
    <sms id="12346" phone="79087964782" num="79021121075" created="2011-09-20 21:11" seen="1">1234 Дима Билан</sms>

</inbound>

JSON
{
    "apikey": "XYZ",
    "inbound": [
        {"id": "12345", "phone" : "79087964781", "num" : "79021121075", "text" : "1234 Ура работает!", "created" : "2011-09-20 20:15", "seen ": "0"},
        {"id": "12346", "phone" : "79087964782", "num" : "79021121075", "text" : "1234 Дима Билан!", "created" : "2011-09-20 21:11", "seen": "0"}
    ]
}
1)	id – уникальный код входящего сообщения в нашей системе.
2)	phone – номер отправителя
3)	num – сервисный номер
4)	text – текст сообщения (вместе с префиксом)
5)	created – время создания записи (мск)
6)	seen – 0-не просмотрено, 1 – просмотрено (возвращалось по запросу)
6. Отладка и коды ошибок
Для отладки используется 
1) параметр test=1 или 2) тестовый ключ:

XXXXXXXXXXXXYYYYYYYYYYYYZZZZZZZZXXXXXXXXXXXXYYYYYYYYYYYYZZZZZZZZ

Реальной отправки не происходит.
Так как по факту сообщения не сохраняются то при выполнении команды проверки статусов, клиентский  id будет нулевым, а статусы заполнены по спец. алгоритму.

В случае неверного запроса или ошибочных данных вы можете получить ошибку документа.
XML
<?xml version="1.0" encoding="utf-8"?>
<error>
    <code>241</code>
    <description>You don't have enough money</description>
</error>

JSON
{
    "error": {
        "code": "241",
        "description": "You don't have enough money"
    }
}
7.1 Коды ошибок
Код	Описание	Решение проблемы	
10	INPUT data is required	Проверьте правильность отправляемого http-запроса	
11	Unknown INPUT format	Формат определяется по первым символам, убедитесь, что тело запроса начинается на <?xml или { без пробела в самом начале	
12	XML structure is invalid	Проверьте структуру XML, возможно не закрыт тег или атрибут	
13	JSON structure is invalid	Проверьте структуру JSON, возможно используются одинарные кавычки	
14	Unknown COMMAND	Проверьте написание названия команды send, check, balance, info	
100	APIKEY is required	Укажите API-ключ как это описано в этом документе	
101	APIKEY is invalid	При копировании выделили не все символы ключа	
106	APIKEY is blocked (spam)	Вы нарушили правила сервиса, напишите объяснительную в службу поддержки	
108	Phone is required	Возможно, пустой номер телефона или пропущен параметр to	
110	System error	Шлюз недоступен, просто подождите и попытайтесь снова.	
111	Invalid phone	Исправьте номер телефона	
112	No money	Пополните баланс
https://www.smspilot.ru/my-order.php	
113	IP restriction	Проблемы с ограничением доступа по IP-адресу, см. личный кабинет -> настройки -> API	
115	Invalid sender	Исправьте имя отправителя, возможно длина больше 11 символов, или недопустимые символы	
204	Sender (from) unregistered	Имя отправителя (from) еще не зарегистрировано
https://www.smspilot.ru/my-sender.php	
212	Phone is depricated	Исключите этот номер из списка рассылки	
213	Unsupported zone	Не поддерживается отправка в эту страну или этому оператору, возможно городской номер	
215	Invalid phone length	Проверьте длину номера телефона	
220	TEXT is required	Введите текст сообщения	
221	TEXT too long	Сделайте текст короче	
223	TEXT is an advertisement	Запрет на рекламу, текст не совпадает с шаблоном, номера нет в белом списке.
http://www.smspilot.ru/faq.php#q50	
230	ID is invalid	Ваш ID сообщения должен быть числом	
231	PACKET_ID is invalid	-	
240	Invalid INPUT list	Нужен список сообщений для отправки	
242	SMS count limit (trial)	У вас тестовый доступ, можно только  2 сообщения в списке рассылки, удалите лишние	
243	Loop protection, blacklist	Не отправляйте одно и тоже сообщение на тот же номер чаще, чем указали в настройках защиты от дубликатов.	
250	Invalid SEND_DATETIME	Неправильное время отправки	
260	Invalid callback URL	Укажите правильный адрес скрипта, https не поддерживается	
270	Invalid ttl	Укажите время жизни сообщения в минутах от 10 до 1440	
300	SMS server_id is required	Укажите список ID для проверки статуса	
301	SMS server_id is invalid	Неправильный ID сообщения для проверки статуса	
302	SMS server_id not found	Возможно уже прошло больше 40 дней и сообщение уже удалено с сервера	
303	Invalid IDs list	Пустой или неправильный список ID сообщений для проверки статуса	
304	SERVER_PACKET_ID is invalid	Исправьте server_packet_id	
400	User not found	Не найден пользователь, возможно нужен новый API-ключ	
401	Invalid login details	Не указан login или password. Возможно неверный формат эл. почты для login	
500	Invalid -since- format, right is YYYY-MM-DD HH:II:SS	Укажите правильный формат даты/времени параметра since – ГГГГ-ММ-ДД ЧЧ:ММ:СС	
600	Expired	Не удалось доставить SMS за указанное время, либо больше суток от оператора нет ответа	
601	Undeliverable	Невозможно доставить, если номер блокирован или отключены SMS	
602	Destination unreachable	Направление (страна, оператор) не поддерживается	
603	Rejected	Отказано оператором	

ВНИМАНИЕ! Полный актуальны список ошибок см. здесь https://smspilot.ru/apikey.php#err
7.2 Отладка HTTP запроса
Для отправки HTTP заголовков и тела запроса на эл. почту добавьте GET параметр debug

http://smspilot.ru/api2.php?debug=info@smspilot.ru

8. Рефералы
Для поддержки партнерской программы существует возможность добавить привлеченного пользователя через API. Для того чтобы записать пользователя «к себе» добавьте к запросу GET параметр r 

http://smspilot.ru/api2.php?r=51

-	51 замените на свой номер договора

9. Изменения
2.4.16
+ выборка списка ещё не просмотренных сообщений since=new

2.4.15
+ test=1 отправка без передачи операторам
+ cost=1 – рассчитать стоимость
+ при отправке возвращается стоимость рассылки 

2.4.14
+ 223 ошибка запрета на рекламу
+ 215 ошибка – неправильный номер телефона
* изменились тексты некоторых ошибок

2.4.13
+ callback_method – get или post вызов скрипта приёма стутусов (по умолчанию get)

2.4.12
+ callback – можно указать адрес скрипта приёма статуса SMS
+ ttl – можно указать время жизни SMS в минутах от 10 до 1440
+ ошибка «260 Invalid callback URL» если указан неправильный адрес скрипта приёма статуса
+ ошибка «270 Invalid ttl» если указано неправильное время жизни SMS
+ ошибка «600 Expired» если не удалось доставить SMS за указанное время, либо прошло больше суток, от оператора нет ответа
+ ошибка «601 Undeliverable» если номер блокирован или отключены SMS
+ ошибка «602 Destination unreachable» если направление (страна,оператор) не поддерживается
+ ошибка «603 Rejected» если оператор отказался принимать SMS

2.4.11
+ запрос баланса XML: если указать атрибут return=”sms” то вернется примерное кол-во оставшихся SMS
+ запрос баланса JSON: то же самое если указать значение balance: “sms”

2.4.10
* в связи с переходом на рубли, баланс и цены на SMS возвращаются в рублях
+ отправка: появились атрибуты price – цена в рублях, operator – оператор
- отправка: удалены атрибуты zone и credits
* текст ошибки 241 You don't have enough credits заменен на You don't have enough money
2.3.3
+ параметр since для более точной выборки входящих
2.3.2
+ ?debug=info@smspilot.ru – поможет в отладке HTTP запросов, параметр можно добавлять к любому запросу API
+ ?r=51 – укажите номер договора партнера для записи пользователя в список рефералов, также можно добавить к любому запросу к API
+ send_datetime – поддерживается дата/время в UNIXSTAMP формате

2.3.1
+ error=243 – Loop error, защиту от дубликатов можно установить в личном кабинете

2.3
+ error=400 – пользователь не найден при авторизации по логину паролю
+ error=401 – неправильный логин и пароль, возможно пустые
+ send_datetime – дата/время отправки
+ country=RU – возвращается страна (в ISO)
+ status=3 – отложенная отправка

2.2
+ 204	FROM not found
* изменилась состав информации о пользователе

2.1.2
- 243 Rate limit

2.1.1
+ 243 Rate limit

2.1
+ server_packet_id и balance в ответах сервера на запрос отправки
+ поддержка проверки статусов по коду всего пакета
+ 304 SERVER_PACKET_ID is invalid