SMSPILOT.RU API-1 v1.10

pdf-icon SMSPILOT.RU-API-1.10.pdf

2021-11-03

Быстрый старт
API-1 подходит для быстрой упрощённой интеграции, API-2 для пакетной работы.
Отправка SMS: https://smspilot.ru/api.php?send=hello&to=79087964781&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
  1. Общение с сервисом осуществляется при помощи отправки запросов по протоколу HTTP или HTTPS методом GET или в формате application/x-www-form-urlencoded методом POST. Кодировка UTF-8.
  2. Адрес сервиса:
    https://smspilot.ru/api.php
  3. Авторизация пользователя происходит путем передачи API-ключа в параметрах запроса. Реальный API-ключ доступен в личном кабинете
  4. Также поддерживается авторизация по логину и паролю от личного кабинета smspilot.ru, однако этот способ не рекомендуется т.к. пароль от ЛК довольно часто меняется.
  5. Общие для всех запросов параметры:
    debug - эл. почта для отладки
    test - включение режима тестирования
    cost - узнать стоимость
    format - формат ответа (json,xml,text,v), по умолчанию text

пример

https://smspilot.ru/api.php?send=test&to=79087964781&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. Отправка SMS
    1.1 На один номер
    1.2 Рассылка одинаковых сообщений
    1.3 Рассчитать стоимость
  2. Статусы
    2.1 Получение статуса в реальном времени (рекомендуется)
    2.2 По запросу
  3. Проверка номеров
    3.1 HLR
    3.2 PING
    3.3 HLRVIP
  4. Голосовы уведомления (звонки)
  5. Входящие сообщения
    5.1 Получение входящих сообщений в реальном времени (рекомендуется)
    5.2 Получение списка входящих сообщений по запросу
  6. Двухсторонний обмен SMS
  7. Баланс
  8. Информация о пользователе
  9. Рефералы
  10. Отладка и коды ошибок
  11. История изменений

1 Отправка SMS

ПараметрОбязательныйОписание
sendДаТекст сообщения, Кодировка по умолчанию UTF-8 Длина одного SMS сообщения составляет 70 символов кириллицей либо 160 символов латиницей. Если количество символов превышает максимально допустимое, то SMS разбивается на кусочки по 67 символов для сообщения кириллицей и по 153 символа для сообщения латиницей
toДаНомер мобильного телефона или список номеров через запятую в международном формате без знака +
GET запрос в большинстве случаев имеет ограничение на длину 1024 символа, поэтому используйте POST запрос, если получателей больше 300
apikeyДаБуквенно-цифровой ключ для авторизации
Вместо apikey можно использовать пару login и password - эл. почту и пароль от ЛК
fromНетЗарегистрированное имя отправителя
formatНетФормат ответа сервера:
text (по умолчанию) - похож на CSV
xml - ответ в формате XML
json - JSON (рекомендуется)
v - самый короткий ответ
charsetНетКодировка запроса и ответа, может принимать значение из этого списка, например: windows-1251, UTF-16LE и др., по умолчанию UTF-8
langНетЯзык возвращаемых ошибок в режиме text и v: en (по умолчанию) или ru
send_datetimeНетUTC время отправки, например:
2021-12-31 10: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 запросов и ответов
callbackНетURL адрес скрипта для получения статуса. См. Получение статуса в реальном времени
callback_methodНетpost или get (по умолчанию get)
rНетID реферера, значение должно быть номером договора партнера, можно подставить в любой запрос к API

1.1 На один номер

JSON

https://smspilot.ru/api.php?send=Hello&to=79087964781&from=INFORM&apikey=XYZ&format=json

удачный ответ

{"send":[
  {"server_id":"9316849","phone":"79087964781","price":"1.31","status":"0"}
],
"balance":"2935.50", "cost":"1.31", "server_packet_id":"9316849"
}

ошибка

{"error": {"code": "111", "description": "Invalid phone", "description_ru": "Неправильный номер телефона"}}

XML

https://smspilot.ru/api.php?send=Hello&to=79087964781&from=INFORM&apikey=XYZ&format=xml

удачный ответ

<?xml version="1.0" encoding="utf-8"?>
<send balance="2936.81" cost="2.19" server_packet_id="9316848">
<sms server_id="9316848" phone="79087964781" price="2.19" status="0"/>
</send>

ошибка

<?xml version="1.0" encoding="utf-8"?>
<error><code>111</code><description>Invalid phone</description><description_ru>Неправильный номер телефона</description_ru></error>

TEXT

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

удачный ответ содержит заголовок SUCCESS=SMS SENT cost/balance, перенос строки (\n)
и далее через запятую перечислены server_id,phone,price,status

SUCCESS=SMS SENT 0.89/320.50
9316849,79087964782,0.60,0

ошибка, язык ошибки определяется параметром lang

ERROR=111: INVALID PHONE

V

https://smspilot.ru/api.php?send=Hello&to=79087964781&from=INFORM&apikey=XYZ&format=v

в случае удачного ответа возвращается server_id

9316849

ошибка, язык ошибки определяется параметром lang

Invalid phone

Cтруктура ответа зависит от результата и значения fields

  1. server_id – уникальный код присвоенный сообщению шлюзом, целое число
  2. sender – имя отправителя
  3. sender_orig - оригинальное значение, если произошла автозамена имени отправителя
  4. phone – телефонный номер абонента
  5. priceстоимость SMS
  6. partsкол-во частей сообщения
  7. status – код статуса (-2 – ошибка, 0 – принято, 3 - отложено)
  8. message - текст сообщения
  9. error – код ошибки, если сообщение не принято, см. здесь
  10. error_en - ошибка на англиском языке
  11. error_ru - ошибка на русском языке
  12. balance – баланс после отправки
  13. send_datetime – дата/время отложенной отправки
  14. country – страна
  15. operator - оператор
  16. server_packet_id - код пакета, позже можно проверить статус всей рассылки по этому коду

Статусы
Если нет возможности получить статусы в реальном времени, то через 5 минут запрашиваем статусы обычным способом.

1.2 Рассылка одинаковых сообщений

C помощью API-1 можно отправить большой пакет одинаковых сообщений, в API-2 поддерживается отправка разных сообщений в одном пакете.
JSON

https://smspilot.ru/api.php?send=Hello&to=79087964781,79161231212,79999999999&from=INFORM&apikey=XYZ&format=json

удачный ответ (валидных сообщений больше чем сообщений с ошибкой)

{"send":[
  {"server_id":"182132632","phone":"79087964781","price":"1.31","status":"0"},
  {"server_id":"182132633","phone":"79161231212","price":"2.21","status":"0"},
  {"server_id":"182132634","phone":"79999999999","price":"0.00","status":"-2","error": "212",
	  "error_en": "Phone in black list",
	  "error_ru": "Телефон в черном списке"}
],
"balance":"2935.50", "cost":"3.52", "server_packet_id":"182132632"}

ошибка (ошибок больше чем валидных сообщений)

{"error": {"code": "111", "description": "Invalid phone", "description_ru": "Неправильный номер телефона"}}

XML

https://smspilot.ru/api.php?send=Hello&to=79087964781,79161231212,79999999999&from=INFORM&apikey=XYZ&format=xml

удачный ответ (валидных сообщений больше чем сообщений с ошибкой)

<?xml version="1.0" encoding="UTF-8"?>
<send balance="1692.01" cost="5.23" server_packet_id="182132870">
	<sms server_id="182132870" phone="79087964781" price="2.85" status="0"/>
	<sms server_id="182132872" phone="79835271808" price="2.38" status="0"/>
	<sms server_id="182132873" phone="79999999999" price="0.00" status="-2" error="212" error_en="Phone in black list"
	     error_ru="Телефон в черном списке"/>
</send>

ошибка (ошибок больше чем валидных сообщений)

<?xml version="1.0" encoding="UTF-8"?>
<error>
	<code>212</code>
	<description>Phone in black list</description>
	<description_ru>Телефон в черном списке</description_ru>
	<ip>11.222.222.111</ip>
</error>

TEXT

https://smspilot.ru/api.php?send=Hello&to=79087964781,79161231212,79999999999&from=INFORM&apikey=XYZ

удачный ответ (валидных сообщений больше чем сообщений с ошибкой)

SUCCESS=SMS SENT 5.23/1686.78
182133021,79087964781,2.85,0
182133022,79835271808,2.38,0
182133023,79999999999,0.00,-2

ошибка (ошибок больше чем валидных сообщений)

ERROR=212: PHONE IN BLACK LIST

V

https://smspilot.ru/api.php?send=Hello&to=79087964781,79161231212,79999999999&from=INFORM&apikey=XYZ&format=v&lang=ru

удачный ответ (валидных сообщений больше чем сообщений с ошибкой), код пакета (совпадает с кодом 1-го сообщения в пакете)

182133021

ошибка (ошибок больше чем валидных сообщений)

Телефон в черном списке

Атрибуты ответа такие-же как при отправке на один номер.

Статусы
Если нет возможности получить статусы в реальном времени то через 5 минут запрашиваем статусы обычным способом.

1.3. Рассчитать стоимость

JSON

https://smspilot.ru/api.php?send=Hello&to=79087964781,79161231212&cost=1&apikey=XYZ&format=json
{"cost": "0.89"}

XML

https://smspilot.ru/api.php?send=Hello&to=79087964781,79161231212&cost=1&apikey=XYZ&format=xml
<cost>0.89</cost>

TEXT

https://smspilot.ru/api.php?send=Hello&to=79087964781,79161231212&cost=1&apikey=XYZ
0.89

V

https://smspilot.ru/api.php?send=Hello&to=79087964781,79161231212&cost=1&apikey=XYZ&format=v
0.89

2. Статусы

СтатусФинальныйSMS и голосовые уведомленияHLRPING
-2Даошибка, см. значение error здесь, не тарифицируется
-1Дасообщение не доставлено (телефон абонента выключен, установлен антиспам и др.)Номер не обслуживаетсяНе в сети
0Нетпринято (в очереди у нас)
1Нетпередано оператору
2ДаДоставленоОбслуживаетсяВ сети
3Нетотложенная отправка (задано время начала рассылки send_datetime)--

2.1 Получение статуса в реальном времени (рекомендуется)

  1. Можно получать статусы в реальном времени, если указать адрес скрипта в настройках или в параметрах callback и callback_method запроса send.
  2. В момент изменения статуса сообщения скрипт будет вызван методом GET или POST (см. callback_method)
  3. Передаются параметры server_id, phone, status и error, в случае ошибки также передаются error_en и error_ru
  4. Список дополнительных параметров можно перечислить через параметр fields адреса скрипта callback. Можно указать message,sender,sender_orig,created, modified, country, operator или all для передачи всех этих полей, например: https://example.com/sms-status.php?fields=message,modified
  5. Также через callback можно передать параметры простой HTTP авторизации: https://user:password@example.com/sms-status.php
  6. Ваш скрипт должен ответить очень быстро (HTTP статус 200, любой текст), соединение оборвётся через 30 секунд, поэтому не выполняйте тяжёлых задач

Допустим адрес вашего скрипта https://example.com/sms-status.php

JSON

https://smspilot.ru/api.php?send=test&to=79087964781&apikey=XYZ&format=json&callback=https%3A%2F%2Fexample.com%2Fsms-status.php

ответ такой-же как и без callback

{"send":[ {"server_id":"9316849","phone":"79087964781","price":"1.31","status":"0"}],
"balance":"2935.50",
"cost":"1.31"}

через несколько секунд указанному скрипту будету переданы результаты доставки:

GET /sms-status.php?server_id=182138593&phone=79087964781&status=2&error=0 HTTP/1.1

если что-то пошло не так, то результат будет таким:

GET /sms-status.php?server_id=182138593&phone=79087964781&status=-1&error=604&error_en=Undeliverable&error_ru=Невозможно%20доставить HTTP/1.1
  1. server_id - код сообщения
  2. phone - номер телефона
  3. status - статус
  4. error - код ошибки
  5. error_en и error_ru - текст ошибки на английском и русском языке.

Могут передаваться другие атрибуты сообщения

2.2 По запросу

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

ПараметрОбязательныйОписание
checkДавозможные значения:
12345 - вернётся статус по коду сообщения server_id
12345,12346 - вернётся список сообщений по перечисленым кодам
recent - вернутся статусы сообщений за последние сутки
packet - check=packet&id=123456, где id это код пакета, вернутся статусы всей рассылки
all - вернутся все статусы всех сообщений (макс 10 тыс.)
apikeyДаAPI-ключ
fieldsНетСписок возвращаемых полей (по-умолчанию server_id, phone, status, error), см. отправку SMS на один номер

JSON

https://smspilot.ru/api.php?check=4566,4567&apikey=XYZ&format=json

удачный ответ

{"check":[
  {"server_id":"4566","phone":"79131437355","price":"1.31","status":"2"},
  {"server_id":"4577","phone":"79087964781","price":"1.92","status":"-1"}
]}

ошибка

{"error": { "code": 303, "description": "Invalid IDs list", "description_ru": "Ошибка запроса",	"ip": "11.111.222.111" } }

XML

https://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="1.92" status="2"/>
</check>

ошибка

<?xml version="1.0" encoding="UTF-8"?>
<error>
	<code>303</code>
	<description>Invalid IDs list</description>
	<description_ru>Ошибка запроса</description_ru>
	<ip>92.126.211.147</ip>
</error>

TEXT

https://smspilot.ru/api.php?check=4566,4567&apikey=XYZ

удачный ответ

4566,79087964782,1.31,-1
4567,79131231212,1.92,2

ошибка

ERROR=303: INVALID IDS LIST

V

https://smspilot.ru/api.php?check=4566&apikey=XYZ&format=v

удачный ответ

2

ошибка

Invalid IDs list

3. Проверка номеров

Услуга позволяет проверить номера: HRL - обслуживается/не обслуживается, PING - в сети/выключен или вне зоны, HLRVIP - улучшенный гибридный вариант.

3.1. HLR

HLR-запросы нужны чтобы скрытно узнать обслуживается ли номер телефона или уже нет.

ПараметрОбязательныйОписание
sendДаHLR
toДаномера телефонов в международном формате перечисленные через запятую
apikeyДаAPI-ключ
callbackНетАдрес скрипта для получения статуса в реальном времени
callback_methodНетget или post вызов скрипта приёма статусов (по умолчанию get)
fieldsНетСписок возвращаемых атрибутов сообщения (по-умолчанию server_id, phone, status, error), другие см. здесь

JSON

https://smspilot.ru/api.php?send=HLR&to=79087964781,79620488646&apikey=XYZ&format=json

формат ответа такой же как на отправку SMS

{"send":[
  {"server_id":"182236219","phone":"79087964781","price":"0.15","status":"0"},
  {"server_id":"182236220","phone":"79620488646","price":"0.30","status":"0"}
],"balance":"1681.10","cost":"0.45","server_packet_id":"182236219"}

или ошибка

{
  "error": {
	"code": 215,
	"description": "Invalid phone length",
	"description_ru": "Неправильная длина номера телефона",
	"phone": "7962048864",
	"ip": "11.111.211.111"
  }
}

XML

https://smspilot.ru/api.php?send=HLR&to=79087964781,79620488646&apikey=XYZ&format=xml

формат такой же как на отправку SMS

<?xml version="1.0" encoding="UTF-8"?>
<send balance="1680.65" cost="0.45" server_packet_id="182237643">
	<sms server_id="182237643" phone="79087964781" price="0.15" status="0"/>
	<sms server_id="182237644" phone="79620488646" price="0.30" status="0"/>
</send>

или ошибка

<?xml version="1.0" encoding="UTF-8"?>
<error>
	<code>215</code>
	<description>Invalid phone length</description>
	<description_ru>Неправильная длина номера телефона</description_ru>
	<phone>7962048864</phone>
	<ip>11.121.111.111</ip>
</error>

TEXT

https://smspilot.ru/api.php?send=HLR&to=79087964781,79620488646&apikey=XYZ
SUCCESS=SMS SENT 0.45/1680.20
182238510,79087964781,0.15,0
182238511,79620488646,0.30,0

V

https://smspilot.ru/api.php?send=HLR&to=79087964781&apikey=XYZ&format=v

удачный ответ, код HLR-запроса:

182238510

ошибка

Invalid phone length

Статусы
Если нет возможности получить статусы в реальном времени, то через 5 минут запрашиваем статусы обычным способом.

3.2. PING

PING позволяет узнать в сети абонент или нет, это Flash-SMS с очень коротким временем жизни, которая не отображается на телефоне.

ПараметрОбязательныйОписание
sendДаPING
toДаномера телефонов в международном формате перечисленные через запятую
apikeyДаAPI-ключ
callbackНетАдрес скрипта для получения статуса в реальном времени
callback_methodНетget или post вызов скрипта приёма статусов (по умолчанию get)
fieldsНетСписок возвращаемых атрибутов сообщения (по-умолчанию server_id, phone, status, error), другие см. здесь

JSON

https://smspilot.ru/api.php?send=PING&to=79087964781,79620488646&apikey=XYZ&format=json

формат ответа такой же как на отправку SMS

{"send":[
  {"server_id":"182236219","phone":"79087964781","price":"0.15","status":"0"},
  {"server_id":"182236220","phone":"79620488646","price":"0.30","status":"0"}
],"balance":"1681.10","cost":"0.45","server_packet_id":"182236219"}

или ошибка

{
  "error": {
	"code": 215,
	"description": "Invalid phone length",
	"description_ru": "Неправильная длина номера телефона",
	"phone": "7962048864",
	"ip": "11.111.211.111"
  }
}

XML

https://smspilot.ru/api.php?send=PING&to=79087964781,79620488646&apikey=XYZ&format=xml

формат такой же как на отправку SMS

<?xml version="1.0" encoding="UTF-8"?>
<send balance="1680.65" cost="0.45" server_packet_id="182237643">
	<sms server_id="182237643" phone="79087964781" price="0.15" status="0"/>
	<sms server_id="182237644" phone="79620488646" price="0.30" status="0"/>
</send>

или ошибка

<?xml version="1.0" encoding="UTF-8"?>
<error>
	<code>215</code>
	<description>Invalid phone length</description>
	<description_ru>Неправильная длина номера телефона</description_ru>
	<phone>7962048864</phone>
	<ip>11.121.111.111</ip>
</error>

TEXT

https://smspilot.ru/api.php?send=PING&to=79087964781,79620488646&apikey=XYZ
SUCCESS=SMS SENT 0.45/1680.20
182238510,79087964781,0.15,0
182238511,79620488646,0.30,0

V

https://smspilot.ru/api.php?send=PING&to=79087964781&apikey=XYZ&format=v

удачный ответ, код HLR-запроса:

182238510

ошибка

Invalid phone length

Статусы
Если нет возможности получить статусы в реальном времени, то через 5 минут запрашиваем статусы обычным способом.

3.3. HLRVIP

Если в запросе указать HLRVIP вместо HLR, то система попытается вернуть дополнительные параметры, а текже отправит PING запрос операторам, которые не возвращают HLR-статусы или возвращают неправильные.

ПараметрОбязательныйОписание
sendДаHLRVIP
toДаНомера телефонов в международном формате перечисленные через запятую
apikeyДаAPI-ключ
callbackНетАдрес скрипта для получения статуса в реальном времени
callback_methodНетget или post вызов скрипта приёма статусов (по умолчанию get)
fieldsНетСписок возвращаемых атрибутов сообщения (по-умолчанию server_id, phone, status, error), другие см. здесь

JSON

https://smspilot.ru/api.php?send=HLRVIP&to=79087964781,79620488646&apikey=XYZ&format=json

формат ответа такой же как на отправку SMS

{"send":[
  {"server_id":"182236219","phone":"79087964781","price":"0.15","status":"0"},
  {"server_id":"182236220","phone":"79620488646","price":"0.30","status":"0"}
],"balance":"1681.10","cost":"0.45","server_packet_id":"182236219"}

или ошибка

{
  "error": {
	"code": 215,
	"description": "Invalid phone length",
	"description_ru": "Неправильная длина номера телефона",
	"phone": "7962048864",
	"ip": "11.111.211.111"
  }
}

XML

https://smspilot.ru/api.php?send=HLRVIP&to=79087964781,79620488646&apikey=XYZ&format=xml

формат такой же как на отправку SMS

<?xml version="1.0" encoding="UTF-8"?>
<send balance="1680.65" cost="0.45" server_packet_id="182237643">
	<sms server_id="182237643" phone="79087964781" price="0.15" status="0"/>
	<sms server_id="182237644" phone="79620488646" price="0.30" status="0"/>
</send>

или ошибка

<?xml version="1.0" encoding="UTF-8"?>
<error>
	<code>215</code>
	<description>Invalid phone length</description>
	<description_ru>Неправильная длина номера телефона</description_ru>
	<phone>7962048864</phone>
	<ip>11.121.111.111</ip>
</error>

TEXT

https://smspilot.ru/api.php?send=HLRVIP&to=79087964781,79620488646&apikey=XYZ
SUCCESS=SMS SENT 0.45/1680.20
182238510,79087964781,0.15,0
182238511,79620488646,0.30,0

V

https://smspilot.ru/api.php?send=HLRVIP&to=79087964781&apikey=XYZ&format=v

удачный ответ, код HLR-запроса:

182238510

ошибка

Invalid phone length

Статусы
Если нет возможности получить статусы в реальном времени, то через 5 минут запрашиваем статусы обычным способом.

Доп. информация, которую возвращает HLRVIP

  1. imsi - Уникальный код IMSI SIM-карты абонента.
  2. msc - Номер сервис-центра оператора, в сети которого находится абонент.
  3. mcc - Числовой код страны абонента.
  4. mnc - Числовой код оператора абонента.
  5. cn - Название страны регистрации абонента.
  6. net - Название оператора регистрации абонента.
  7. rcn - Название роуминговой страны абонента при нахождении в чужой сети.
  8. rnet - Название роумингового оператора абонента при нахождении в чужой сети.

4. Голосовые уведомления (звонки)

Робот позвонит и озвучит сообщение.
Формат запроса и ответа аналогичен отправке SMS, нужно только изменить имя отправителя на GOLOS

ПараметрОбязательныйОписание
sendДаТекст сообщения, поддерживаются русский и английский языки, иногда роботу нужны подсказки, например, мы пишем ЭСЭМЭСПИЛОТ вместо SMSPILOT для правильной озвучки
toДаНомера телефонов в международном формате перечисленные через запятую
fromДаGOLOS
apikeyДаAPI-ключ
callbackНетАдрес скрипта для получения статуса в реальном времени
callback_methodНетget или post вызов скрипта приёма статусов (по умолчанию get)
fieldsНетСписок возвращаемых атрибутов сообщения (по-умолчанию server_id, phone, status, error), другие см. здесь
другие параметрыНетсм. здесь

JSON

https://smspilot.ru/api.php?send=Hello&to=79087964781,79835271808,79999999999&from=GOLOS&ttl=60&apikey=XYZ&format=json

удачный результат (валидных сообщений больше чем сообщений с ошибкой)

{"send":[
    {"server_id":"182245438","phone":"79087964781","price":"0.50","status":"0"},
    {"server_id":"182245439","phone":"79835271808","price":"0.50","status":"0"},
    {"server_id":"182245440","phone":"79999999999","price":"0.00","status":"-2","error":"212","error_en":"Phone in black list","error_ru":"Телефон в черном списке"}],
 "balance":"1679.20","cost":"1.00","server_packet_id":"182245438"}

ошибка (не удалось отправить весь пакет)

{
  "error": {
	"code": 215,
	"description": "Invalid phone length",
	"description_ru": "Неправильная длина номера телефона",
	"phone": "7983527180",
	"ip": "11.222.222.1"
  }
}

XML

https://smspilot.ru/api.php?send=Hello&to=79087964781,79835271808,79999999999&from=GOLOS&ttl=60&apikey=XYZ&format=xml

удачный ответ (валидных сообщений больше чем сообщений с ошибкой)

<?xml version="1.0" encoding="UTF-8"?>
<send balance="1678.20" cost="1.00" server_packet_id="182245725">
  <sms server_id="182245725" phone="79087964781" price="0.50" status="0"/>
  <sms server_id="182245726" phone="79835271808" price="0.50" status="0"/>
  <sms server_id="182245727" phone="79999999999" price="0.00" status="-2" error="212" error_en="Phone in black list" error_ru="Телефон в черном списке"/>
</send>

ошибка (не удалось отправить весь пакет)

<?xml version="1.0" encoding="utf-8"?>
<error>
    <code>241</code>
    <description>You don't have enough money</description>
    <description_ru>Нет денег</description_ru>
    <ip>11.222.222.1</ip>
</error>

TEXT

https://smspilot.ru/api.php?send=Hello&to=79087964781,79835271808,79999999999&from=GOLOS&apikey=XYZ

удачный ответ (валидных сообщений больше чем сообщений с ошибкой)

SUCCESS=SMS SENT 1.00/1677.20
182246325,79087964781,0.50,0
182246326,79835271808,0.50,0
182246327,79999999999,0.00,-2

ошибка (не удалось отправить весь пакет)

ERROR=215: INVALID PHONE LENGTH

V

https://smspilot.ru/api.php?send=Hello&to=79087964781&from=GOLOS&apikey=XYZ&format=v

удачный ответ, код сообщения:

182246387

ошибка

Phone in black list

Cтруктура ответа зависит от результата и значения fields, описание см. здесь

Статус голосового сообщения можно получить в реальном времени или запросить через 5 минут по кодам сообщений или коду пакета.

5. Входящие сообщения

Пусть клиенты напишут вам, а вы сможете программно обработать SMS, отправленные абонентами на сервисный номер.
При получении SMS на общий номер:

  1. система ищет номер в списке исходящее SMS, на которое можно ответить (2WAY)
  2. если номер не найден, то проверяется префикс сообщения, он должен совпадать с кодом пользователя (номером договора)
  3. если номер всё ещё не найден, то поиск номера продолжается в системных таблицах: исходящие SMS, контакты, входящие SMS, пользователи.

5.1. Получение входящих сообщений в реальном времени (рекомендуется)

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

POST /sms-inbound.php HTTP/1.1
Host: example.com
Content-Type: application/x-www-form-urlencoded

phone=79087964781&message=restart%20server%20alfa&user_id=12345&id=54321&num=79533984570

Пример скрипта:

<?php // sms_inbound.php
file_put_contents('sms_inbound.log', print_r( $_POST, true ), FILE_APPEND );
// в файле будут записи
/*
 Array
 (
  [phone] => 79087964781
  [message] => restart server alfa
  [user_id] => 12345
  [id] => 54321,
  [num] => 79533984570
 )
*/
  1. phone - номер абонента
  2. message - сообщение (UTF8, префикс удаляется)
  3. user_id - код пользователя (номер договора)
  4. id - код сообщения
  5. num - сервисный номер для входящих

5.2. Получение списка входящих сообщений по запросу

Можно получить список всех входящих SMS или ограничить список только новыми сообщениями.

ПараметрОбязательныйОписание
inboundДаnew - получить список новых сообщений
all - список всех входящих сообщений
2021-11-10 14:05:00 - список сообщений полученных после указанных даты и времени
123456789 - список сообщений полученных после указанных даты и времени в формате UNIXSTAMP
apikeyДаAPI-ключ

JSON

https://smspilot.ru/api.php?inbound=all&apikey=XYZ&format=json

или

https://smspilot.ru/api.php?inbound=new&apikey=XYZ&format=json

удачный ответ

{"inbound": [
  {"id": "12345", "phone" : "79087964781", "num" : "79533984570", "text" : "Ура работает!", "created" : "2021-09-20 20:15", "seen ": "0"},
  {"id": "12346", "phone" : "79087964782", "num" : "79533984570", "text" : "Дима Билан!", "created" : "2021-09-20 21:11", "seen": "0"}
]}

ошибка

{
  "error": {
	"code": 500,
	"description": "Invalid -since- format YYYY-MM-DD HH:II:SS",
	"description_ru": "Неправильный формат параметра -since- YYYY-MM-DD HH:II:SS",
	"ip": "11.1111.211.111"
  }
}

XML

https://smspilot.ru/api.php?inbound=all&apikey=XYZ&format=xml

или

https://smspilot.ru/api.php?inbound=new&apikey=XYZ&format=xml

ответ

<?xml version="1.0" encoding="utf-8"?>
<inbound>
	<sms id="273500" phone="79835271808" num="79581000255" created="2021-10-14 10:14:06" seen="0">321</sms>
	<sms id="273499" phone="79087964781" num="79533984570" created="2021-10-14 10:12:15" seen="0">restart server 1</sms>
</inbound>

ошибка

<?xml version="1.0" encoding="utf-8"?>
<error>
	<code>500</code>
	<description>Invalid -since- format YYYY-MM-DD HH:II:SS</description>
	<description_ru>Неправильный формат параметра -since- YYYY-MM-DD HH:II:SS</description_ru>
	<ip>11.111.211.111</ip>
</error>

TEXT

https://smspilot.ru/api.php?inbound=all&apikey=XYZ

или

https://smspilot.ru/api.php?inbound=new&apikey=XYZ

ответ

6061,79087964781,79021121075,test,2021-10-20 19:11:21,0
6060,79087964781,79021121075,open the door,2014-10-20 19:10:30,1
  1. id - код входящего сообщения
  2. phone - номер телефона абонента
  3. num - сервисный номер для входящих
  4. text или содержание тега sms - текст входящего сообщения
  5. created - дата/время получения сообщения (UTC)
  6. seen - просмотрено/не просмотрено

6. Двухсторонний обмен SMS

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

  1. Замените отправителя на 2WAY
  2. Используйте шаблон, отмеченный как Опрос/голосование
  3. SMS придёт от сервисного номера, абонент сможет ответить.
  4. В зависимости от настроек входящих вы сможете получить это сообщение в реальном времени или запросить список входящих через несколько минут.

JSON

https://smspilot.ru/api.php?send=проверка&to=79087964781&from=2WAY&apikey=XYZ&format=json

Удачный ответ такой же как при обычной отправке SMS

{"send":[
  {"server_id":"182264859","phone":"79087964781","price":"3.13","status":"0"}
],"balance":"1673.57","cost":"3.13", "server_packet_id": "182264859"}

ошибка

{
  "error": {
	"code": 227,
	"description": "Spam protection (SURVEY)",
	"description_ru": "Защита от спама (для опросов\/голосований нужен спец. шаблон)",
	"phone": "79087964781",
	"ip": "11.122.211.111"
  }
}

XML

https://smspilot.ru/api.php?send=проверка&to=79087964781&from=2WAY&apikey=XYZ&format=xml

удачный ответ такой же как при отправке SMS

<?xml version="1.0" encoding="UTF-8"?>
<send balance="1670.25" cost="3.13" server_packet_id="182265465">
	<sms server_id="182265465" phone="79087964781" price="3.13" status="0"/>
</send>

ошибка

<?xml version="1.0" encoding="UTF-8"?>
<error>
	<code>227</code>
	<description>Spam protection (SURVEY)</description>
	<description_ru>Защита от спама (для опросов/голосований нужен спец. шаблон)</description_ru>
	<phone>79087964781</phone>
	<ip>11.121.211.111</ip>
</error>

TEXT

https://smspilot.ru/api.php?send=проверка&to=79087964781&from=2WAY&apikey=XYZ

удачный ответ такой же как при отправке SMS

SUCCESS=SMS SENT 3.13/1667.12
182265641,79087964781,3.13,0

ошибка

ERROR=227: SPAM PROTECTION (SURVEY)

V

https://smspilot.ru/api.php?send=проверка&to=79087964781&from=2WAY&apikey=v

удачный ответ, код исходящего сообщения

18226564

ошибка

Spam protection (survey)

Ответ абонента можно получить методами для входящих сообщений

7. Баланс

Текущий баланс пользователя можно получить в рублях или как примерное кол-во SMS.

ПараметрОбязательныйОписание
balanceДаrur - вернуть баланс в рублях
sms - вернуть примерное кол-во SMS, на которое хватит денег
apikeyДаAPI-ключ

JSON

https://smspilot.ru/api.php?balance=rur&apikey=XYZ&format=json
{"balance":"2934.76"}

XML

https://smspilot.ru/api.php?balance=rur&apikey=XYZ&format=xml
<balance>2934.76</balance>

TEXT

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

V

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

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

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

JSON

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":"INFORM,test"
}

ошибка

{
  "error": {
	"code": 106,
	"description": "User is blocked",
	"description_ru": "Пользователь блокирован за спам\/ошибки",
	"status": -5,
	"status_ru": "Проблемы с эл. почтой",
	"ip": "11.122.111.111"
  }
}

XML

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>

ошибка

<?xml version="1.0" encoding="UTF-8"?>
<error>
	<code>106</code>
	<description>User is blocked</description>
	<description_ru>Пользователь блокирован за спам/ошибки</description_ru>
	<status>-5</status>
	<status_ru>Проблемы с эл. почтой</status_ru>
	<ip>11.122.111.111</ip>
</error>

TEXT

https://smspilot.ru/api.php?apikey=XYZ&format=text

удачный ответ

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=INFORM,test

ошибка

ERROR=106: USER IS BLOCKED

V

https://smspilot.ru/api.php?apikey=XYZ&format=v

удачный ответ

info@example.com

ошибка

User is blocked

Атрибуты со временем могут измениться, это зависит от версии шлюза:

  1. id - номер договора
  2. tariff_id - номер тарифа
  3. email - email пользователя
  4. name - имя пользователя
  5. phone - телефон пользователя
  6. balance - текущий баланс (в рублях)
  7. created - дата/время регистрации
  8. default_sender - имя отправителя по умолчанию
  9. any_text - строгость фильтров (0 - очень строгий (только по шаблонам), 1 - стандартный, 2 - отключен, 3 - специальный (реклама, страхование, долги, займы)
  10. senders - список разрешенных имен отправителя (через запятую)

9. Рефералы (партнёрская программа)

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

https://smspilot.ru/api.php?send=test&to=79087964781&apikey=XYZ&r=51

51 замените на свой код пользователя (номер договора).

Информацию о подключенных рефералах см. здесь

10. Отладка и коды ошибок

Для включения режима тестировани используйте:

  1. параметр test=1
  2. или тестовый ключ apikey:

XXXXXXXXXXXXYYYYYYYYYYYYZZZZZZZZXXXXXXXXXXXXYYYYYYYYYYYYZZZZZZZZ

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

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

https://smspilot.ru/api.php?check=1000&apikey=XYZ&test=1

Режим отладки представляет собой трансляцию HTTP запросов и ответов на указанный адрес эл. почты:

  1. Почту для отладки можно передать через GET параметр debug https://smspilot.ru/api2.php?debug=info@example.com
  2. или в личном кабинете ЛК - Настройки - API, см. поле Эл. почта для отладки

Не забудьте включить отображение всех ошибок, в PHP это делается так:

ini_set('error_reporting', E_ALL);
ini_set('display_errors', true);

В случае неверного формата запроса или ошибочных данных вы можете получить ошибку:
JSON

{
  "error": {
	"code": 106,
	"description": "User is blocked",
	"description_ru": "Пользователь блокирован за спам\/ошибки",
	"status": -5,
	"status_ru": "Проблемы с эл. почтой",
	"ip": "11.122.111.111"
  }
}

XML

<?xml version="1.0" encoding="UTF-8"?>
<error>
	<code>106</code>
	<description>User is blocked</description>
	<description_ru>Пользователь блокирован за спам/ошибки</description_ru>
	<status>-5</status>
	<status_ru>Проблемы с эл. почтой</status_ru>
	<ip>11.122.111.111</ip>
</error>

TEXT

ERROR=106: USER IS BLOCKED

V

User is blocked
  1. code - код ошибки
  2. description - описание ошибки на английском языке
  3. description_ru - описание ошибки на русском языке
  4. status и status_ru - дополнительные необязательные атрибуты
  5. ip - IP адрес HTTP-клиента

Коды ошибок и описание опубликованы здесь:
https://smspilot.ru/apikey.php#err

11. История изменений

1.10 (2021-11-10)
* обновлена документация, улучшена работа с пакетами
* рекомендуется использовать JSON (format=json)  
+ Описан двухсторонний обмен сообщениями (2WAY)
+ server_packet_id - код пакета для рассылок, чтобы позже проверить статусы по этому коду
 
- Удалены методы работы с именами отправителя и шаблонами

1.9.19 (2020-12-21)
+ Голосовые сообщения
+ 2WAY сообщения
+ Упрощенный формат ответа в виде простого значения или текста ошибки &format=v
+ Поддержка дополнительных кодировок для запроса и ответа (например UTF-16LE родной для Windows)

1.9.18 (2018-09-06)
+ выбрать только новые входящие сообщения (inbound=new)

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

Что дальше?