SMSPILOT.RU API-1 v1.12

SMSPILOT.RU-API-1.12.pdf

2024-08-13

Быстрый старт

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. FlashCall (код как последние цифры номерах)
6. Входящие сообщения
   6.1 Получение входящих сообщений в реальном времени (рекомендуется)
   6.2 Получение списка входящих сообщений по запросу
7. Двухсторонний обмен SMS
8. Баланс
9. Информация о пользователе
10. Рефералы
11. Отладка и коды ошибок
12. История изменений

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.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 для передачи всех этих полей
5. Также через callback можно передать параметры простой HTTP авторизации
6. Ваш скрипт должен ответить очень быстро (HTTP статус 200, любой текст), соединение оборвётся через 30 секунд, поэтому не выполняйте тяжёлых задач

 https://example.com/sms-status.php`
 https://example.com/sms-status.php?fields=message,modified
 https://user:password@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 По запросу

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

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

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

3.1. HLR

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

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 с очень коротким временем жизни, которая не отображается на телефоне.

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-статусы или возвращают неправильные.

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 - Название роумингового оператора абонента при нахождении в чужой сети.

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

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 минут по кодам сообщений или коду пакета.

Робот позвонит от номера, где посление 4 цифры мы можем менять.

JSON

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

удачный результат

{"send":[
    {"server_id":"182245438","phone":"79087964781","price":"0.80","status":"0"},
],
 "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=1234&to=79087964781&from=FLASHCALL&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"/>
</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=1234&to=79087964781&from=FLASHCALL&apikey=XYZ

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

SUCCESS=SMS SENT 1.00/1677.20
182246325,79087964781,0.50,0

ошибка

ERROR=215: INVALID PHONE LENGTH

V

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

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

182246387

ошибка

Phone in black list

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

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

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

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

6.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 - сервисный номер для входящих

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

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

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 - просмотрено/не просмотрено

В обычном режиме отправленные 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)

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

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

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

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

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 - список разрешенных имен отправителя (через запятую)

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

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

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

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

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

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

1.11 (2024-03-14)
+ FlashCall

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