SMSPILOT.RU API v2.6 HTTP/JSON/XML

SMSPILOT.RU-API-2.6.pdf

2024-08-13

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

1. Общение с сервисом осуществляется при помощи отправки JSON или XML запросов в кодировке UTF-8 на заданный адрес по протоколу HTTP/HTTPS методом POST.

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

-- пример JSON-запроса

POST https://smspilot.ru/api2.php
Content-Type: application/json; charset=utf-8

{
    "apikey":"XXXXXXXXXXXXYYYYYYYYYYYYZZZZZZZZXXXXXXXXXXXXYYYYYYYYYYYYZZZZZZZZ",
    "send": [
        {"to":"79087964781","text":"проверка"}
    ]
}

-- ответ

{
    "server_packet_id": "123456",
    "balance": 20006.97,
    "cost": 2.96,
    "send": [
        {"id": 0, "server_id": "10000", "from": "INFORM", "to": "79087964781", "text": "проверка", "parts": 1,  "status": 0, "error": 0, "send_datetime": "", "country": "RU", "operator": "TELE2", "price": 2.96}
    ]
}

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

3. В версии 2.3 появилась возможность авторизации по логину и паролю от личного кабинета smspilot.ru, однако этот способ не рекомендуется т.к. пароль от ЛК довольно часто меняется.

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

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

Оглавление

1. Отправка SMS
   1.1. На один номер
   1.2. Пакетная отправка, персональные сообщения
   1.3. Рассчитать стоимость
2. Статусы
   2.1. Получение статусов в реальном времени (рекомендуется)
   2.2. По списку серверных кодов сообщений
   2.3. По серверному коду всего пакета
3. Проверка номеров
   3.1. HLR
   3.2. PING
   3.3. HLRVIP
4. Голосовые уведомления (звонки)
5. Входящие сообщения
   5.1. Получение входящих сообщений в реальном времени (рекомендуется)
   5.2. Получение списка входящих по запросу
6. Двухсторонний обмен SMS
7. Рефералы (партнёрская программа)
8. Баланс
9. Информация о пользователе
10. Отладка и коды ошибок
11. Изменения

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

JSON:

{
  "apikey":"XYZ",
  "send": [
    {"to": "79087964781", "text":"проверка"}
  ]
}

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

{
  "server_packet_id": "1234",
  "balance": 10000.00,
  "cost": 1.29,
  "send": [
    {
      "id": "0",
      "server_id": "10005",
      "from": "INFORM",
      "to": "79087964781",
      "text": "проверка",
      "parts": 1,
      "price": 1.29,
      "status": 0,
      "error": 0,
      "send_datetime": "0000-00-00 00:00:00",
      "country": "RU",
      "operator": "TELE2",
      "ttl": 0
    }
}

ошибка

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

XML

<send apikey="XYZ">
  <sms to="79131437355">проверка</sms>
</send>

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

<?xml version="1.0" encoding="utf-8"?>
<send server_packet_id="1234" balance="10000" cost="1.29">
    <sms id="0" server_id="10005" from="INFORM" to="79087964781" parts="1" price="1.29" status="0" error="0" send_datetime="" country="RU" operator="TELE2">проверка</sms>
</send>

ошибка

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

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

1.2. Пакетная отправка, персональные сообщения

В одном пакете можно отправить несколько сообщений одного типа, можно указать общие параметры рассылки или указать параметры каждого сообщения. Параметры, которые можно применить к пакету: text, from, send_datetime, callback, callback_method, ttl, test, cost

JSON

{
  "apikey":"XYZ",
  "from":"Ozon",
  "send": [
    {"id":1,"to":"79087964781","text":"Уважаемый Сергей, ваша персональная скидка теперь 10%"},
    {"id":2,"to":"79835271808","text":"Уважаемая Анна, ваша персональная скидка теперь 15%"},
    {"id":3,"to":"79999999999","text":"проверка","ttl":20}
  ]
}

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

{
  "server_packet_id": "1234",
  "balance": 10000.00,
  "cost": 3.79,
  "send": [
    {
      "id": "1",
      "server_id": "10005",
      "from": "Ozon",
      "to": "79087964781",
      "text": "Уважаемый Сергей, ваша персональная скидка теперь 10%",
      "parts": 1,
      "price": 1.29,
      "status": 0,
      "error": 0,
      "send_datetime": "0000-00-00 00:00:00",
      "country": "RU",
      "operator": "TELE2",
      "ttl": 0
    },
    {
      "id": "2",
      "server_id": "10006",
      "from": "Ozon",
      "to": "79835271808",
      "text": "Уважаемая Анна, ваша персональная скидка теперь 15%",
      "parts": 1,
      "price": 2.50,
      "status": 0,
      "error": 0,
      "send_datetime": "0000-00-00 00:00:00",
      "country": "RU",
      "operator": "MTS",
      "ttl": 0,
    },
    {
      "id":"3",
      "server_id":"0",
      "from":"Ozon",
      "to":"79999999999",
      "text":"проверка",
      "parts": 1,
      "price": 0,
      "status":-2,
      "error": 212,
      "error_en":"Phone in black list",
      "error_ru":"Телефон в черном списке",
      "send_datetime": "0000-00-00 00:00:00",
      "country": "RU",
      "operator": "YOTA",
      "ttl": 0      
    }
  ]
}

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

{
  "error": {
	"code": 223,
	"description": "Spam protection",
	"description_ru": "Защита от спама (подкл. как бизнес-клиент или исп. шаблоны или добавьте контакт в белый список)",
	"ip": "11.222.222.1"
  }
}

XML

<?xml version="1.0" encoding="utf-8"?>
<send apikey="XYZ" from="Ozon" ttl="10">
    <sms id="1" to="79087964781">Уважаемый Сергей, ваша персональная скидка теперь 10%</sms>
    <sms id="2" to="79835271808">Уважаемая Анна, ваша персональная скидка теперь 15%</sms>
    <sms id="3" to="79999999999" ttl="20">проверка</sms>
</send>

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

<?xml version="1.0" encoding="utf-8"?>
<send server_packet_id="1234" balance="10000.00" cost="3.79">
    <sms id="1" server_id="10005" from="Ozon" to="79087964781" parts="1" price="1.29" status="0" error="0" send_datetime="" country="RU" operator="TELE2">Уважаемый Сергей, ваша персональная скидка теперь 10%</sms>
    <sms id="2" server_id="10006" from="Ozon" to="79835271808" price="2.50" parts="1" status="3" error="0" send_datetime="" country="RU" operator="MTS" ttl="0">Не забываем htmlspecialchars!</sms>
    <sms id="3" server_id="0" from="INFORM" to="79999999999" price="0" parts="0" status="-2" error="212" "error_en"="Phone in black list" "error_ru"="Телефон в черном списке" send_datetime="" country="RU" operator="TELE2" ttl="0">Не забываем &qoot;htmlspecialchars&quot;!</sms>
</send>

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

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

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

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

JSON

{
  "apikey":"XYZ",
  "cost": 1,
  "send": [
    {"to":"79087964781","text":"Рассчет стоимости рассылки"}
  ]
}

{"cost": "2.96"}

XML

<send apikey="XYZ" cost="1">
    <sms to="79087964781">Рассчет стоимости рассылки</sms>
</send>

<cost>2.96</cost>

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 секунд, поэтому не выполняйте тяжёлых задач

JSON

{
    "apikey":"XXXXXXXXXXXXYYYYYYYYYYYYZZZZZZZZXXXXXXXXXXXXYYYYYYYYYYYYZZZZZZZZ",
    "callback":"https://example.com/sms-status.php",
    "send": [
        {"to":"79087964781","text":"проверка"}
    ]
}

XML

<send apikey="XYZ" callback="https://example.com/sms-status.php">
  <sms to="79087964781">проверка</sms>
</send>

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

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

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

успешный ответ

{
    "check": [
        {"id": "0", "server_id" : "10005", "phone":"79087964781", "status": 1,"created": "2020-10-09 14:35:00" "modified": "2020-10-09 14:35:01"},
        {"id": "0", "server_id" : "10006", "phone":"79087964782", "status": 2, "created": "2020-10-09 14:35:00" "modified": "2020-10-09 14:35:08"},
        {"id": "0", "server_id": "10005", "phone": "79087964781", "status": -1, "error": 601, "error_en": "Undeliverable", "error_ru": "Невозможно доставить", "created": "2021-10-09 08:57:00", "modified": "2021-10-09 08:57:00"}
    ]
}

ошибка

{
  "error": {
	"code": 14,
	"description": "Unknown COMMAND",
	"description_ru": "Неизвестная команда",
	"ip": "11.222.222.1"
  }
}

XML

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

успешный ответ

<?xml version="1.0" encoding="utf-8"?>
<check apikey="XYZ">
<sms id="0" server_id="10005" phone="79087964781" status=1 created="2020-10-09 14:35:00" modified="2020-10-09 14:35:01" />
<sms id="0" server_id="10006" phone="79087964782" status=2 created="2020-10-09 14:35:00" modified="2020-10-09 14:35:08" />
<sms id="0" server_id="10005" phone="79087964781" status=-1 error=601 error_en="Undeliverable" error_ru="Невозможно доставить" created="2021-10-09 08:57:00" modified="2021-10-09 08:57:00" />
</check>

ошибка

<?xml version="1.0" encoding="utf-8"?>
<error>
    <code>14</code>
    <description>Unknown COMMAND</description>
    <description_ru>Неизвестная команда</description_ru>
</error>

1. Сообщений со статусом 0 (принято) или 1 (передано оператору) нужно проверить ещё раз позже, например, через 5 минут.
2. Через сутки после отправки устанавливается финальный статус, даже если что-то пошло не так.
3. Если ваш сервер не отвечает, будут предприняты ещё 3 попытки достучаться с интервалом 20 секунд.
4. Максимум 1000 записей

Бан за флуд

1. Не отправляйте пустой список server_id или список из неправильных или пустых значений server_id
2. Не проверяйте статус слишком часто, минимум через 2 минуты, лучше через 5
3. Не запрашивайте статусы для старых сообщений (больше 70 суток), они удаляются в архив.

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

JSON

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

XML

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

1. server_packet_id - код пакета назначенный сервером
2. формат ответа аналогичен проверке по списку серверных кодов сообщений
3. Возвращается максимум 1000 записей, используйте limit и offset для больших пакетов

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

3.1. HLR

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

JSON

{
  "apikey": "XYZ",
  "text": "HLR"
  "send": [
    {"to":"79087964781"},
    {"to":"79620488646"}
  ]
}

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

{
  "server_packet_id": "181547174",
  "balance": 1796.76,
  "cost": 0.3,
  "send": [
	{
	  "id": 0,
	  "server_id": "181547174",
	  "from": "HLR",
	  "to": "79087964781",
	  "text": "HLR",
	  "parts": 1,
	  "status": 0,
	  "error": 0,
	  "send_datetime": "",
	  "country": "RU",
	  "operator": "TELE2",
	  "price": 0.15,
	  "ttl": 0
	},
	{
	  "id": 0,
	  "server_id": "181547175",
	  "from": "HLR",
	  "to": "79620488646",
	  "text": "HLR",
	  "parts": 1,
	  "status": 0,
	  "error": 0,
	  "send_datetime": "",
	  "country": "RU",
	  "operator": "BEELINE",
	  "price": 0.15,
	  "ttl": 0
	}
  ]
}

XML

<send text="HLR" apikey="XYZ">
  <sms to="79087964781" />
  <sms to="79620488646" />
</send>

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

<send server_packet_id="181547119" balance="1797.06" cost="0.3">
  <sms id="0" server_id="181547119" from="HLR" to="79087964781" parts="1" status="0" error="0" send_datetime=""
    country="RU" operator="TELE2" price="0.15" ttl="0">HLR</sms>
  <sms id="0" server_id="181547120" from="HLR" to="79087964782" parts="1" status="0" error="0" send_datetime=""
    country="RU" operator="BEELINE" price="0.15" ttl="0">HLR</sms>
</send>

Статусы
Рекомендуем получать статусы HLR в реальном времени, но также можно запросить статусы по списку кодов или по коду пакета через несколько минут.

3.2. PING

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

JSON

{
  "apikey": "XYZ",
  "text": "PING"
  "send": [
    {"to":"79087964781"},
    {"to":"79620488646"}
  ]
}

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

{
  "server_packet_id": "181550398",
  "balance": 1783.23,
  "cost": 5.76,
  "send": [
	{
	  "id": 0,
	  "server_id": "181550398",
	  "from": "PING",
	  "to": "79087964781",
	  "text": "PING",
	  "parts": 1,
	  "status": 0,
	  "error": 0,
	  "send_datetime": "",
	  "country": "RU",
	  "operator": "TELE2",
	  "price": 2.85,
	  "ttl": 0
	},
	{
	  "id": 0,
	  "server_id": "181550399",
	  "from": "PING",
	  "to": "79620488646",
	  "text": "PING",
	  "parts": 1,
	  "status": 0,
	  "error": 0,
	  "send_datetime": "",
	  "country": "RU",
	  "operator": "BEELINE",
	  "price": 2.91,
	  "ttl": 0
	}
  ]
}

XML

<send text="PING" apikey="XYZ">
  <sms to="79087964781" />
  <sms to="79620488646" />
</send>

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

<send server_packet_id="181551561" balance="1769.88" cost="5.76">
	<sms id="0" server_id="181551561" from="PING" to="79087964781" parts="1" status="0" error="0" send_datetime=""
	     country="RU" operator="TELE2" price="2.85" ttl="0">PING</sms>
	<sms id="0" server_id="181551562" from="PING" to="79620488646" parts="1" status="0" error="0" send_datetime=""
	     country="RU" operator="BEELINE" price="2.91" ttl="0">PING</sms>
</send>

Статусы
Рекомендуем получать статусы PING в реальном времени, но также можно запросить статусы по списку кодов или по коду пакета через несколько минут.

3.3. HLRVIP

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

JSON

{
  "apikey":"XYZ",
  "text":"HLRVIP",
  "send": [
    { "to":"79087964781" },
    { "to":"79620488646" }
   ]
}

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

{
  "server_packet_id": "181548656",
  "balance": 1792.65,
  "cost": 3.21,
  "send": [
	{
	  "id": 0,
	  "server_id": "181548656",
	  "from": "HLRVIP",
	  "to": "79087964781",
	  "text": "HLRVIP",
	  "parts": 1,
	  "status": 0,
	  "error": 0,
	  "send_datetime": "",
	  "country": "RU",
	  "operator": "TELE2",
	  "price": 0.30,
	  "ttl": 0
	},
	{
	  "id": 0,
	  "server_id": "181548657",
	  "from": "HLRVIP",
	  "to": "79620488646",
	  "text": "HLRVIP",
	  "parts": 1,
	  "status": 0,
	  "error": 0,
	  "send_datetime": "",
	  "country": "RU",
	  "operator": "BEELINE",
	  "price": 2.91,
	  "ttl": 0
	}
  ]
}

XML

<send text="HLRVIP" apikey="XYZ">
  <sms to="79087964781" />
  <sms to="79620488646" />
</send>

ответ

<send server_packet_id="181550161" balance="1788.99" cost="3.21">
	<sms id="0" server_id="181550161" from="HLRVIP" to="79087964781" parts="1" status="0" error="0" send_datetime=""
	     country="RU" operator="TELE2" price="0.30" ttl="0">HLRVIP</sms>
	<sms id="0" server_id="181550162" from="HLRVIP" to="79620488646" parts="1" status="0" error="0" send_datetime=""
	     country="RU" operator="BEELINE" price="2.91" ttl="0">HLRVIP</sms>
</send>

Статусы Рекомендуем получать статусы HLR в реальном времени, но также можно запросить статусы по списку кодов или по коду пакета через несколько минут.

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

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

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

JSON

{
  "apikey":"XYZ",
  "from":"GOLOS",
  "text":"Ждём вас на собрании гаражного кооператива сегодня в 18:00",
  "ttl":60,
  "send": [
    {"id":1,"to":"79087964781"},
    {"id":2,"to":"79835271808"},
    {"id":3,"to":"79999999999"}
  ]
}

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

{
  "server_packet_id": "1234",
  "balance": 10000.00,
  "cost": 3.79,
  "send": [
    {
      "id": "1",
      "server_id": "10005",
      "from": "GOLOS",
      "to": "79087964781",
      "text": "Ждём вас на собрании гаражного кооператива сегодня в 18:00",
      "parts": 1,
      "price": 1.29,
      "status": 0,
      "error": 0,
      "send_datetime": "0000-00-00 00:00:00",
      "country": "RU",
      "operator": "TELE2",
      "ttl": 60
    },
    {
      "id": "2",
      "server_id": "10006",
      "from": "GOLOS",
      "to": "79835271808",
      "text": "Ждём вас на собрании гаражного кооператива сегодня в 18:00",
      "parts": 1,
      "price": 2.50,
      "status": 0,
      "error": 0,
      "send_datetime": "0000-00-00 00:00:00",
      "country": "RU",
      "operator": "MTS",
      "ttl": 60,
    },
    {
      "id":"3",
      "server_id":"0",
      "from":"GOLOS",
      "to":"79999999999",
      "text":"Ждём вас на собрании гаражного кооператива сегодня в 18:00",
      "parts": 1,
      "price": 0,
      "status":-2,
      "error": 212,
      "error_en":"Phone in black list",
      "error_ru":"Телефон в черном списке",
      "send_datetime": "0000-00-00 00:00:00",
      "country": "RU",
      "operator": "YOTA",
      "ttl": 60      
    }
  ]
}

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

{
  "error": {
	"code": 223,
	"description": "Spam protection",
	"description_ru": "Защита от спама (подкл. как бизнес-клиент или исп. шаблоны или добавьте контакт в белый список)",
	"ip": "11.222.222.1"
  }
}

XML

<?xml version="1.0" encoding="utf-8"?>
<send apikey="XYZ" from="GOLOS" text="Ждём вас на собрание гаражного кооператива сегодня в 18:00" ttl="60">
    <sms id="1" to="79087964781" />
    <sms id="2" to="79835271808" />
    <sms id="3" to="79999999999" />
</send>

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

<?xml version="1.0" encoding="utf-8"?>
<send server_packet_id="1234" balance="10000.00" cost="3.79">
    <sms id="1" server_id="10005" from="GOLOS" to="79087964781" parts="1" price="1.29" status="0" error="0" send_datetime="" country="RU" operator="TELE2" ttl="60">Ждём вас на собрание гаражного кооператива сегодня в 18:00</sms>
    <sms id="2" server_id="10006" from="GOLOS" to="79835271808" price="2.50" parts="1" status="3" error="0" send_datetime="" country="RU" operator="MTS" ttl="60">Ждём вас на собрание гаражного кооператива сегодня в 18:00</sms>
    <sms id="3" server_id="0" from="GOLOS" to="79999999999" price="0" parts="0" status="-2" error="212" "error_en"="Phone in black list" "error_ru"="Телефон в черном списке" send_datetime="" country="RU" operator="TELE2" ttl="60">Ждём вас на собрание гаражного кооператива сегодня в 18:00</sms>
</send>

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

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

Статус голосового сообщения можно получить в реальном времени или запросить через 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 или ограничить список только новыми сообщениями.
since – дата/время в формате YYYY-MM-DD HH:II:SS или unixstamp с которого начинается выборка, рекомендуем указать значение new, чтобы выбрать ещё не прочитанные сообщения, у которых флаг seen = 0

JSON

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

или

{
    "apikey": "XYZ",
    "inbound": true,
    "since": "new"
}

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

{"inbound": [
  {"id": "12345", "phone" : "79087964781", "num" : "79021121075", "text" : "Ура работает!", "created" : "2011-09-20 20:15", "seen ": "0"},
  {"id": "12346", "phone" : "79087964782", "num" : "79021121075", "text" : "Дима Билан!", "created" : "2011-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.122.211.111"
  }
}

XML

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

или

<?xml version="1.0" encoding="utf-8"?>
<inbound apikey="XYZ" since="new" />

ответ

<?xml version="1.0" encoding="utf-8"?>
<inbound>
	<sms id="273500" phone="79835271808" num="79581000255" created="2021-10-14 10:14:06" seen="1">321</sms>
	<sms id="273499" phone="79087964781" num="79533984570" created="2021-10-14 10:12:15" seen="1">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.122.211.111</ip>
</error>

1. id - код входящего сообщения
2. phone - номер телефона абонента
3. num - сервисный номер для входящих
4. created - дата/время получения сообщения (UTC)
5. text или содержание тега sms - текст входящего сообщения
6. seen - просмотрено/не просмотрено

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

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

JSON

{
  "apikey": "XYZ",
  "from": "2WAY",
  "text": "SMSPILOT.RU исследование: поставьте оценку от 0 до 10 в ответном SMS",
  "send": [
    {"to":"79087964781"},
    {"to":"79087964782"}
  ]
}

Формат ответа такой же как при пакетной отправке SMS

XML

<send text="SMSPILOT.RU исследование: поставьте оценку от 0 до 10 в ответном SMS" from="2WAY" apikey="XYZ">
<sms to="79087964781" />
<sms to="79087964782" />
</send>

Формат ответа такой же как при пакетной отправке SMS

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

Возвращает текущий баланс пользователя в рублях (rur) и в примерном кол-ве SMS (sms)

JSON

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

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

{
  "balance": 1790.51
}

ошибка

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

XML

<?xml version="1.0" encoding="utf-8"?>
<balance apikey="XYZ" return="rur" />

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

<?xml version="1.0" encoding="utf-8"?>
<balance>405.60</balance>

ошибка

<?xml version="1.0" encoding="utf-8"?>
<error>
	<code>106</code>
	<description>User is blocked</description>
	<description_ru>Пользователь блокирован за спам/ошибки</description_ru>
	<status>-2</status>
	<status_ru>Отключен за низкий баланс</status_ru>
	<ip>11.111.211.1</ip>
</error>

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

JSON

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

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

{
  "info": {
	"id": "5",
	"tariff_id": "1",
	"email": "test@smspilot.ru",
	"name": "Букин Геннадий",
	"phone": "79087964781",
	"balance": "20006.97",
	"created": "2019-05-17 04:37:14",
	"default_sender": "INFORM",
	"any_text": "2",
	"senders": "2WAY,GOLOS,HLR,HLRVIP,INFORM,PING"
  }
}

ошибка

{
  "error": {
	"code": 400,
	"description": "User not found",
	"description_ru": "Пользователь не найден",
	"ip": "11.121.211.1"
  }
}

XML

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

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

<?xml version="1.0" encoding="utf-8"?>
<info>
	<id>5</id>
	<tariff_id>1</tariff_id>
	<email>test@smspilot.ru</email>
	<name>Букин Геннадий</name>
	<phone>79087964781</phone>
	<balance>20006.97</balance>
	<created>2019-05-17 04:37:14</created>
	<default_sender>INFORM</default_sender>
	<any_text>2</any_text>
	<senders>2WAY,4geo,GOLOS,HLR,HLRVIP,INFORM,PING</senders>
</info>

ошибка

<?xml version="1.0" encoding="utf-8"?>
<error>
	<code>400</code>
	<description>User not found</description>
	<description_ru>Пользователь не найден</description_ru>
	<ip>11.111.211.1</ip>
</error>

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

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

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

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

Для тестирования используйте:

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

XXXXXXXXXXXXYYYYYYYYYYYYZZZZZZZZXXXXXXXXXXXXYYYYYYYYYYYYZZZZZZZZ

{
  "apikey":"XXXXXXXXXXXXYYYYYYYYYYYYZZZZZZZZXXXXXXXXXXXXYYYYYYYYYYYYZZZZZZZZ",
  "send": [
    { "to":"79999999999","text":"проверка"}
   ]
}

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

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

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

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

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

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

{
  "error": {
	"code": 14,
	"description": "Unknown COMMAND",
	"description_ru": "Неизвестная команда",
	"ip": "11.111.211.1"
  }
}

XML

<?xml version="1.0" encoding="utf-8"?>
<error>
	<code>12</code>
	<description>XML structure is invalid XML error: Space required at line 1</description>
	<description_ru>Ошибка XML XML error: Space required at line 1</description_ru>
	<xmlerror>XML error: Space required at line 1</xmlerror>
	<ip>11.111.222.11</ip>
</error>

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

Коды ошибок

Актуальная таблица со всеми возможными ошибками, которые может вернуть шлюз опубликован здесь:
https://smspilot.ru/apikey.php#err

2.5
* обновлена документация, улучшена работа с пакетами  
+ Описаны методы пакетной отправки HLR,PING и голосовых сообщений

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

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

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

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

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

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

2.4.10
* в связи с переходом на рубли, баланс и цены на SMS возвращаются в рублях
+ отправка: появились атрибуты price – цена в рублях, operator – оператор
- отправка: удалены атрибуты zone и credits
* текст ошибки 241 You don't have enough credits заменен на You don't have enough money

2.3.3
+ параметр `since` для более точной выборки входящих

2.3.2
+ ?debug=info@smspilot.ru – поможет в отладке HTTP запросов, параметр можно добавлять к любому запросу API
+ ?r=51 – укажите номер договора партнера для записи пользователя в список
    рефералов, также можно добавить к любому запросу к API
+ send_datetime – поддерживается дата/время в UNIXSTAMP формате

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

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

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

2.1.2
- 243 Rate limit

2.1.1
+ 243 Rate limit

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