SMSPILOT.RU API-1 v1.9.17
2018-07-23
Быстрый старт
Отправка: https://smspilot.ru/api.php?send=hello&to=79087964781,79087964782&apikey=XYZ
Статус: https://smspilot.ru/api.php?check=23091,23092&apikey=XYZ
Баланс: https://smspilot.ru/api.php?balance=rur&apikey=XYZ
Получить API-ключ: https://smspilot.ru/my-settings.php?tab=api

Оглавление
1. Отправка SMS
1.1. Примеры
1.2. Коды статуса SMS
1.3. Рассчитать стоимость
1.4. Альтернативная авторизация по паролю
1.5. Коды ошибок
2. Проверка статусов SMS
2.1. Примеры
2.2. Коды статуса SMS
2.3. Ошибки
3. Баланс
3.1. Примеры
4. Информация о пользователе
5. Входящие SMS
6. HLR-запросы и PING-сообщения
6.1. PING-сообщения
7. Viber сообщения
7.1. Гибридный Viber
8. История изменений

1.	Отправка SMS
Для отправки SMS нужно сделать HTTP GET/POST запрос с заданными параметрами

https://smspilot.ru/api.php?send=hello&to=79087964781&from=smspilot&apikey=XYZ

https:// – может принимать значения http:// или https:// (безопасный)
Параметр	Описание	
send	Текст сообщения, Кодировка по умолчанию UTF-8
Длина одного SMS сообщения составляет 70 символов кириллицей либо 160 символов латиницей. Если количество символов превышает максимально допустимое, то SMS разбивается на кусочки по 67 символов для сообщения кириллицей и по 153 символа для сообщения латиницей
Текст HLR или PING для скрытых запросов см. 6	
to	Номер мобильного телефона, или список номеров через запятую (только цифры)
GET запрос в большинстве случаев имеет ограничение на длину 1024 символа, используйте POST запрос, если получателей больше 300.	
apikey	Буквенно-цифровой ключ
https://www.smspilot.ru/my-settings.php#api	
from	Зарегистрированный отправитель
https://www.smspilot.ru/my-sender.php	
format	Формат ответа сервера: text (по умолчанию), xml, json	
charset	Может принимать значение windows-1251, по умолчанию utf-8	
send_datetime	GMT (Лондон) время отправки, например:
2015-04-07 09:10:00
или UNIXSTAMP
1428397800	
ttl	«Время жизни сообщения» в минутах от 1 до 1440. Максимальное время, в течение которого сообщение должно быть доставлено на телефон. Если в течение этого времени доставка не возможна (абонент вне зоны действия сети, телефон выключен), сообщение не будет доставлено вовсе. Внимание, данная функция не работает для некоторых направлений, например, для CDMA телефонов.	
fields	Список возвращаемых атрибутов SMS через запятую: server_id, phone, price, status, sender, sender_orig, created, modified, parts, country, operator, error, error_en, error_ru), по умолчанию (server_id, phone, price, status), all – все	
cost	0 – обычная отправка (по умолчанию)
1 – рассчитать стоимость	
		
test	0 – обычная отправка
1 – без передачи оператору	
debug	для отладки HTTP запросов, значение должно быть адресом эл. почты, можно подставить в любой запрос к API	
callback	URL адрес скрипта для асинхронного приёма статуса, например:
http://ya.ru/status.php
будет вызван как:
http://ya.ru/status.php?server_id=1233211233&status=2&error=0

Также можно указать какие ещё нужны параметры через fields, например
http://ya.ru/status.php?fields=country,operator,message
будет вызван как:
http://ya.ru/status.php?server_id=1233211233&status=2&error=0&country=RU&operator=MTS&message=test

Дополнительные параметры передаются если это HLR запрос (см. 6)
Нужно обработать за 10 секунд и вывести текст: OK
Коды ошибок смотрите в https://smspilot.ru/apikey.php#err
Можно установить общий URL и протестировать в личном кабинете
https://smspilot.ru/my-settings.php?tab=api
	
callback_method	post или get (по умолчанию get)	
r	ID реферера, значение должно быть номером договора партнера, можно подставить в любой запрос к API	
полужирным отмечены обязательные параметры
1.1.	Примеры
https://smspilot.ru/api.php?send=Hello&to=79087964781,79161231212&from=test&apikey=XYZ
SUCCESS=SMS SENT 0.89/320.50
4566,79087964782,0.60,0
4568,79161231212,0.29,0
0.89 – cost, цена рассылки
320.50 – balance, баланс после рассылки
4566 – server_id, код SMS
0.60 – price, цена SMS
0 – status, статус SMS (-2 – ошибка, -1 – не доставлено, 0 – новое, 1 – в очереди, 2 – доставлено, 3 - отложено)
или
ERROR=204: SENDER (FROM) UNREGISTERED

https://smspilot.ru/api.php?send=Hello&to=79087964781&from=test&apikey=XYZ&format=xml
<send balance="2936.81" cost="0.43">
<sms server_id="9316848" phone="79087964781" price="0.43" status="0"/>
</send>
или
<error><code>111</code><description>Invalid phone</description><description_ru>Неправильный номер телефона</description_ru></error>

https://smspilot.ru/api.php?send=Hello&to=79087964781&from=test&apikey=XYZ&format=json
{"send":[
  {"server_id":"9316849","phone":"79087964781","price":"1.31","status":"0"}
],
"balance":"2935.50",
"cost":"1.31"}
или
{"error": {"code": "111", "description": "Invalid phone", "description_ru": "Неправильный номер телефона"}}
1.2.	Коды статуса SMS
Код	Статус	Финальный	
-2	ошибка (длина сообщения, номер телефона)	Да	
-1	не доставлено	Да	
0	новое сообщение, подготовка к отправке	Нет	
1	в очереди 	Нет	
2	доставлено	Да	
3	отложенная отправка (задан send_datetime)	Нет	
1.3.	Рассчитать стоимость
https://smspilot.ru/api.php?send=Hello&to=79087964781,79161231212&cost=1&apikey=XYZ
0.89
https://smspilot.ru/api.php?send=Hello&to=79087964781,79161231212&cost=1&apikey=XYZ&format=xml
<cost>0.89</cost>
https://smspilot.ru/api.php?send=Hello&to=79087964781,79161231212&cost=1&apikey=XYZ&format=json
{"cost": "0.89"}

1.4.	Альтернативная авторизация по паролю
https://smspilot.ru/api.php?send=Hello&to=79087964781,79161231212&from=test&login=info@smspilot.ru&password=123456

Добавлено в 1.8.9 для упрощения интеграции с популярными программами, можно использовать вместо apikey для всех операций

login – эл. почта пользователя
password – пароль от личного кабинета
1.5.	Коды ошибок
100	APIKEY is required	Не указан параметр apikey	
101	APIKEY is invalid	Неправильный apikey	
102	APIKEY not found	Такой ключ не найден	
106	APIKEY is blocked (spam)	Подозрение в рассылке спама. Свяжитесь со службой поддержки.	
220	TEXT is required	Пустое значение параметра send	
108	Phone is required	Пустое значение параметра to	
110	System error	Непредвиденная ошибка системы, возможно неверный адрес отправителя	
111	Invalid phone	Неправильный номер телефона или ни одного правильного номера в списке получателей to 	
112	No money	Попытка отправить много смс при низком балансе	
113	IP restriction	Попытка доступа с чужого сервера (при включенном ограничении по IP).	
115	Invalid sender	Ошибка значения отправителя (from): должен быть номер (6..14 цифр), или название 3-11 символов(A-Za-z0-9.-)	
204	Sender (from) unregistered	Имя отправителя (from) еще не зарегистрировано
https://smspilot.ru/my-sender.php	
215	Invalid phone length	Проверьте длину телефона, для России 11 цифр	
223	TEXT is an advertisement	Запрет на рекламу, текст не совпадает с шаблоном, номера нет в белом списке.
https://smspilot.ru/faq.php#q50	
243	Loop protection, blacklist	Сработала защита от дубликатов (то же сообщение, на тот-же номер), см. настройки API в личном кабинете. Возможно текст содержит запрещенные слова.	
250	Invalid SEND_DATETIME	Неправильное время отправки	
260	Invalid callback URL	Исправьте адрес скрипта (https не поддерживается)	
270	Invalid ttl	Исправьте время жизни сообщения, укажите в минутах от 10 до 1440	
400	User not found	Пользователь с такими логином и паролем не найден. Возможно неправильный пароль	
401	Invalid login details	Не указан login или password. Возможно неверный формат эл. почты для login	
Весь список ошибок https://smspilot.ru/apikey.php#err
2.	Проверка статусов SMS

Лучше получать статусы асинхронно на callback-URL указанный при отправке или в настройках в строке «Отправлять статусы SMS»
https://smspilot.ru/my-settings.php?tab=api

Для проверки текущего статуса отправленной SMS или группы SMS нужно сделать HTTP GET/POST запрос с заданными параметрами.

https://smspilot.ru/api.php?check=ID(s)&apikey=XYZ

https:// – может принимать значения http:// или https:// (безопасный)
check	со значением ID отправленной SMS или нескольких ID(s) разделённых запятыми, специальное значением "recent" вернёт список SMS за последние 24 часа;	
apikey	API-ключ (https://www.smspilot.ru/my-settings.php#api).	
fields	см. 1. Отправка SMS	
2.1.	Примеры
http://smspilot.ru/api.php?check=4566,4567&apikey=XYZ
4566,79087964782,0.29,-1
4567,79131231212,1.2,2
где 0.29 – price, цена, -1 – статус (см. ниже)

http://smspilot.ru/api.php?check=4566,4567&apikey=XYZ&format=xml
<check>
<sms server_id="4566" phone="79131437355" price="1.31" status="1"/>
<sms server_id="4577" phone="79087964781" price="0.00" status="-2"/>
</check>
http://smspilot.ru/api.php?check=4566,4567&apikey=XYZ&format=json
{"check":[
  {"server_id":"4566","phone":"79131437355","price":"1.31","status":"1"},
  {"server_id":"4577","phone":"79087964781","price":"0.00","status":"-2"}
]}
2.2.	Коды статуса SMS
Код	Статус	Финальный	
-2	не принято, неправильный номер, ID не найден	Да	
-1	сообщение не доставлено (телефон абонента выключен или вне сети)	Да	
0	новое сообщение, подготовка к отправке	Нет	
1	в очереди у оператора	Нет	
2	сообщение успешно доставлено	Да	
3	отложенная отправка (send_datetime)	Нет	
2.3.	Ошибки
300	SMS server_id is required	Статус: server_id не указан	
301	SMS server_id is invalid	Статус: server_id неправильный	
302	SMS server_id not found	Статус: SMS не найдена	
303	Invalid IDs list	Статус: ошибка запроса	

3.	Баланс
Для проверки текущего баланса ключа нужно сделать HTTP GET/POST запрос с заданными параметрами:

https://smspilot.ru/api.php?balance=rur&apikey=XYZ

https:// – может принимать значения http:// или https:// (безопасный)
balance – может принимать значения rur или sms, rur – вернуть баланс в рублях, sms – вернуть примерное кол-во оставшихся смс
apikey – API-ключ (http://www.smspilot.ru/apikey.php).

3.1.	Примеры
https://smspilot.ru/api.php?balance=rur&apikey=XYZ
308.25
https://smspilot.ru/api.php?balance=rur&apikey=XYZ&format=xml
<balance>2934.76</balance>
https://smspilot.ru/api.php?balance=rur&apikey=XYZ&format=json
{"balance":"2934.76"}
4.	Информация о пользователе

Для проверки учетной записи нужно сделать HTTP GET/POST запрос с заданными параметрами

https://smspilot.ru/api.php?apikey=XYZ
SUCCESS=APIKEY INFO
id=5671
tariff_id=5
email=info@example.ru
name=Иванов Сергей Николаевич
phone=79087964781
balance=2934.76
date=2010-06-03 09:45:41
default_sender=INFORM
any_sender=0
senders=79021121075,79087964781,INFORM,test

где
id	номер договора	
tariff_id	номер тарифа	
email	email пользователя
	
name	имя пользователя	
phone	телефон	
balance	текущий баланс (в рублях)	
date	дата/время регистрации	
default_sender	имя отправителя по умолчанию	
senders	список разрешенных имен отправителя (через запятую)	

https://smspilot.ru/api.php?apikey=XYZ&format=xml
<info>
<id>5671</id>
<tariff_id>5</tariff_id>
<email>info@example.com</email>
<name>Иванов Сергей Николаевич</name>
<phone>79087964781</phone>
<balance>2934.76</balance>
<date>2010-06-03 09:45:41</date>
<default_sender>INFORM</default_sender>
<senders>79021121075,79087964781,INFORM,test</senders>
</info>
https://smspilot.ru/api.php?apikey=XYZ&format=json
{"id":"5671","tariff_id":"5","email":"info@example.com","name":" Иванов Сергей Николаевич ","phone":"79087964781","balance":"2934.76","date":"2010-06-03 09:45:41","default_sender":"INFORM","senders":"79021121075,79087964781,INFORM,test"}
5.	Входящие SMS
https://smspilot.ru/api.php?inbound=all&apikey=XYZ
inbound – может принимать значение
  1) all – возврат всех входящих
  2) дату в формате 2010-06-03 09:45:41
  3) дату в формате UNIXSTAMP

6061,79087964781,79021121075,"5671 test","2014-10-20 19:11:21"
6060,79087964781,79021121075,"5671 test\nLine2","2014-10-20 19:10:30"

6061 – id, код
79087964781 – phone, тел. отправителя
7902111075 – num, сервисный номер
"5671 test" – text, текст
"2014-10-20 19:11:21" – created, дата/время
https://smspilot.ru/api.php?inbound=all&apikey=XYZ&format=xml
<inbound>
<sms id="6061" phone="79087964781" num="79021121075" created="2014-10-20 19:11:21">5671 test</sms>
<sms id="6060" phone="79087964781" num="79021121075" created="2014-10-20 19:10:30">5671 test
Line 2</sms>
</inbound>
https://smspilot.ru/api.php?inbound=all&apikey=XYZ&format=json
{"inbound":[
  {"id":"6061","phone":"79087964781","num":"79021121075","text":"51 test","created":"2014-10-20 19:11:21"},
{"id":"6060","phone":"79087964781","num":"79021121075","text":"51 test\nLine2","created":"2014-10-20 19:10:30"}
]}
6.	HLR-запросы и PING-сообщения
Лучше получать статусы HLR-запросов и других сообщений на свой скрипт: см. параметр callback или укажите адрес крипта в настройках https://smspilot.ru/my-settings.php?tab=api

В HLR (Home Location Register) базе хранятся данные об абонентах сетей GSM. Чтобы сделать HLR-запрос к базе оператора, отправьте сообщение с текстом HLR на нужный номер, а затем проверьте статус данного сообщения:
https://smspilot.ru/api.php?send=HLR&to=79087964781&apikey=XYZ&format=json
Параметр	Описание	
send	Текст HLR	
to	Номер мобильного телефона	
apikey	Буквенно-цифровой ключ
https://www.smspilot.ru/my-settings.php#api	
{"send":[
  {"server_id":"9316849","phone":"79087964781","price":"0.17","status":"0"}
],
"balance":"2935.50",
"cost":"0.17"}
https://smspilot.ru/api.php?check=4566,4567&apikey=XYZ&format=json
{"check":[
  {"server_id":"4566","phone":"79131437355","price":"0.17","status":"2","imsi":"250203122060176","msc":"790434","mcc":"250","mnc":"20","cn":"Russia","net":"Tele2","rcn"="","rnet"=""},
]}
Где
imsi	Уникальный код IMSI SIM-карты абонента.	
msc	Номер сервис-центра оператора, в сети которого находится абонент.	
mcc	Числовой код страны абонента.	
mnc	Числовой код оператора абонента.	
cn	Название страны регистрации абонента.	
net	Название оператора регистрации абонента.	
rcn	Название роуминговой страны абонента при нахождении в чужой сети.	
rnet	Название роумингового оператора абонента при нахождении в чужой сети.	

6.1.	PING-сообщения
PING-сообщения – скрытые бинарные Flash-сообщения для проверки абонента на доступность в реальном времени. Отправьте SMS с текстом PING или отправителем PING на нужный номер (см. 1), а затем проверьте статус (см. 2)
7.	Viber сообщения
Для отправки уведомлений до 1000 символов через мессенджер Viber измените имя отправителя на VIBER

Запрос:
https://smspilot.ru/api.php?send=test&to=79087964781&from=VIBER&format=json&apikey=XYZ

XYZ замените на свой API-ключ

Пример ответа:
{"send":[{"server_id":"10000","phone":"79087964781","price":"1.16","status":"0"}],"balance":"11908.50","cost":"1.16"}

Пример ошибки:
{"error":{"code":"215","description":"Invalid phone length","description_ru":"Неправильная длина номера телефона"}}
			
7.1.	Гибридный Viber
Для гибридной отправки используйте имя VIBERSMS. Если у абонента нет Viber-а, то будет отправлено обычное SMS-сообщение с именем отправителя установленным по-умолчанию

Запрос:
https://smspilot.ru/api.php?send=test&to=79087964781&from=VIBERSMS&format=json&apikey=XYZ

XYZ замените на свой API-ключ

Пример ответа:
{"send":[{"server_id":"10000","phone":"79087964781","price":"1.16","status":"0"}],"balance":"11908.50","cost":"1.16"}

Пример ошибки:
{"error":{"code":"212","description":"Phone in black list","description_ru":"Телефон в черном списке"}}
8.	История изменений
1.9.17                     2018-07-23
* теперь примеры с указанием httpS – лучше отправлять по защищенному каналу
+ Описание отправки сообщений через Viber 

1.9.16                    2017-03-29
+ HLR-запросы и PING-сообщения
+ указание нужных полей в &callback

1.9.15
+ &fields может содержать sender, а также принимать значение all
+ &format – text, xml, json формат ответа сервера
+ Список входящих

1.9.14
+ &test=1 – отключает передачу операторам
+ &cost=1 – рассчитать стоимость

1.9.13
+ ERROR=223: TEXT IS AN ADVERTISEMENT – ошибка запрета на рекламу
+ ERROR=215: INVALID PHONE LENGTH – неправильная длина номера телефона
+ &fields – список колонок
изменены коды и тексты некоторых ошибок (в соответствии API-2)

1.9.12
+ &callback_method – get или post вызов скрипта приёма статусов

1.9.11
+ &callback – можно задать скрипт приёма статусов
+ &ttl – можно задать время жизни сообщения (в минутах 10-1440)
+ ERROR=260: INVALID CALLBACK – ошибка возникает если указан неправильный адрес скрипта приёма статусов
+ ERROR=270: TTL – ошибка возникает если указано неправильное время жизни сообщения

1.9.10
в связи переходом на рубли значения баланса и стоимости возвращается в рублях
Изменения 1.8.92
+ &debug=info@smspilot.ru – поможет в отладке HTTP запросов, параметр можно добавлять к любому запросу API
+ &r=51 – укажите номер договора партнера для записи пользователя в список рефералов, также можно добавить к любому запросу к API
+ &send_datetime – поддерживается дата/время в UNIXSTAMP формате
- исправлена ошибка запроса на отправку sms без параметра from

1.8.91
+ ERROR=243: LOOP PROTECTION – сработала защита от дубликатов, см. настройки API в личном кабинете

1.8.9

+ &login=XXX&password=YYY - Добавлена возможность использовать логин и пароль от личного кабинета для работы с API
+ &send_datetime=YYYY-MM-DD HH:MM:SS – время отправки пакета
+ ERROR=401: INVALID LOGIN DETAILS – ошибка в login или password
+ERROR=115: INVALID SENDER – возвращается при указании отправителя в неправильном формате
+ERROR=116: DEPRICATED SENDER – возвращается если отправителя нет в списке разрешенных
+ERROR=250: SEND_DATETIME – неправильный формат даты/времени отправки или дата в прошлом
+ERROR=400:USER NOT FOUND - Пользователь с такими логином и паролем не найден. Возможно неправильный пароль

1.8.8
- ERROR=117: ACCOUNT RESTRICTION – не возвращается, т.к. сменилась политика верификации.
- ERROR=115: SENDER – эта ошибка не возвращается. Если имя отправителя неправильное, то используется подпись по умолчанию или smspilot.ru
- изменен состав информации о пользователе

1.8.7
- Отключена защита от дубликатов, ERROR=118: RATE LIMIT – не возвращается

1.8.6
+Добавлена поддержка параметра charset=windows-1251

1.8.5
+ ERROR=118: RATE LIMIT

Изменения 1.8.3
+ ERROR=116: DEPRICATED SENDER – запрещённые отправители (from)
- ERROR=117: ACCOUNT RESTRICTION – ограничения тестового аккаунта
- ERROR=103: APIKEY NOT PAID Ключ не оплачен (больше не поддерживается)
- ERROR=104: APIKEY NOT ACTIVATED Ключ ещё не активирован (больше не поддерживается)
- ERROR=105: APIKEY BLOCKED (EMPTY) Требуется пополнить баланс данного ключа (больше не поддерживается, в пользу ERROR=112: SMS LIMIT)
- при запросе баланса, не поддерживаются другие валюты кроме SMS-кредитов
~ изменились статусы ключа (-1 – бан, 0 – тестовый, 1 – полный доступ)

1.8.2
+ проверка отправителя, ERROR=115: SENDER

1.8.1
+ Добавлено описание параметра from (отправитель)
- Исправлено форматирование документа

1.8
- было SUCCESS=APIKEY INFO 123/20507, стало SUCCESS=APIKEY INFO
- удалён атрибут last_sms
+ добавлен атрибут allow_ip
+ добавлен атрибут balance