SMS Пилот API v2.0.2 HTTP/XML/JSON
2011-09-17
Общение с сервисом осуществляется при помощи отправки XML или JSON запросов в кодировке UTF-8 на заданный адрес по протоколу HTTP/HTTPS методом POST.

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

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

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

Наряду с POST/XML и POST/JSON  поддерживается передача документа через  GET/POST переменную (urlencoded):
http://smspilot.ru/api2.php?xml=.....
http://smspilot.ru/api2.php?json=.....

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

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

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

1)	apikey – буквенно-цифровой ключ (http://www.smspilot.ru/my.php)
2)	id – уникальный код сообщения в вашей системе, целое число.
3)	from – подпись отправителя,  по умолчанию задан в настройках или smspilot.ru
4)	to – телефонный номер абонента, целое число

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

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

На полученный запрос сервис возвращает список отправляемых сообщений.
XML
<?xml version="1.0" encoding="utf-8"?>
<send>
    <sms id="12345" server_id="10005" from="SMSPILOT" to="79087964781" zone="1" parts="1" credits="1" status="0" error="0">Ура &quot;SMSPILOT&quot; работает!</sms>
    <sms id="12346" server_id="10006" from="ADVOKAT" to="79087964782" zone="1" parts="1" credits="1" status="0" error="0">Не забываем htmlspecialchars!</sms>
</send>

JSON
{
    "send": [
        {
            "id": "12345",
            "server_id": "10005",
            "from": "SMSPILOT",
            "to": "79087964781",
            "text": "Ура \"SMSPILOT\" работает!",
            "zone": "1",
            "parts": "1",
            "credits": "1",
            "status": "0",
            "error": "0"
        },
        {
            "id": "12346",
            "server_id": "10006",
            "from": "ADVOKAT",
            "to": "79087964782",
            "text": "json_encode в помощь!",
            "zone": "1",
            "parts": "1",
            "credits": "1",
            "status": "0",
            "error": "0"
        }
    ]
}

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

2. Проверка статусов SMS

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

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

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

Возвращает список статусов

XML
<?xml version="1.0" encoding="utf-8"?>
<check>
    <sms id="12345" server_id="10005" status="1" />
    <sms id="12346" server_id="10006" status="2" />
</check>

JSON
{
    "apikey": "XYZ",
    "check": [
        {"id": "12345", "server_id" : "10005", "status": "1", "modified": "2011-08-11 14:35:00"},
        {"id": "12346", "server_id" : "10006", "status": "2", "modified": "2011-08-11 15:12:22"}
    ]
}
2.1 Коды статуса SMS
-2	сервер не получал это сообщение (ID не найден)	
-1	сообщение не доставлено (телефон абонента выключен, оператор не поддерживается)	
0	принято	
1	у оператора	
2	доставлено	

Состояние SMS обновляется каждые 2 минуты.

3. Баланс
XML
<?xml version="1.0" encoding="utf-8"?>
<balance apikey="XYZ" />

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

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

JSON
{"balance": 120981}

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

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

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

Результат
XML
<?xml version="1.0" encoding="utf-8"?>
<info>
    <id>1</id>
    <parent_id> 0</parent_id>
    <tariff_id>1</tariff_id>
    <apikey>XXXXXXXXXXXXYYYYYYYYYYYYZZZZZZZZXXXXXXXXXXXXYYYYYYYYYYYYZZZZZZZZ</apikey>
    <email>info@smspilot.ru</email>
    <name></name>
    <phone> 0</phone>
    <sms_total>1000000</sms_total>
    <sms_sent>264</sms_sent>
    <status>1</status>
    <default_sender></default_sender>
    <balance>999736</balance>
</info>

JSON
{
    "info": {
        "id":"1",
        "parent_id":"0",
        "tariff_id":"1",
        "apikey":"XXXXXXXXXXXXYYYYYYYYYYYYZZZZZZZZXXXXXXXXXXXXYYYYYYYYYYYYZZZZZZZZ",
        "email":"info@smspilot.ru",
        "name":"",
        "phone":"0",
        "sms_total":"1000000",
        "sms_sent":"263",
        "status":"1",
        "balance":999737
    }
}

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

status - статус пользователя
-1 – заблокирован за нарушение правил
0 – новый тестовый аккаунт (нельзя менять подпись и максимум 2 сообщения в пакете)
1 – полный доступ

5. Входящие
XML
<?xml version="1.0" encoding="utf-8"?>
<inbound apikey="XYZ" />

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

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

XML
<?xml version="1.0" encoding="utf-8"?>
<inbound>
    <sms id="12345" phone="79087964781" num="79021121075" created="2011-09-20 20:15" r_message="Сообщение принято" r_status="2">1234 Ура работает!</sms>
    <sms id="12346" phone="79087964782" num="79021121075" created="2011-09-20 21:11" r_message="Ваш голос зачислен" r_status="2">1234 Дима Билан</sms>

</inbound>

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

6. Отладка и коды ошибок
Для отладки используется тестовый ключ:

XXXXXXXXXXXXYYYYYYYYYYYYZZZZZZZZXXXXXXXXXXXXYYYYYYYYYYYYZZZZZZZZ

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

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

JSON
{
    "error": {
        "code": "241",
        "description": "You don't have enough credits"
    }
}
5.1 Коды ошибок
Код	Описание	Решение проблемы	
10	INPUT data is required	Проверьте правильность отправляемого http-запроса	
11	Unknown INPUT format	Формат определяется по первым символам, убедитесь, что тело запроса начинается на <?xml или { без пробела в самом начале	
12	XML structure is invalid	Проверьте структуру XML, возможно не закрыт тег или атрибут	
13	JSON structure is invalid	Проверьте структуру JSON, возможно используются одинарные кавычки	
14	Unknown COMMAND	Проверьте написание названия команды send, check, balance, info	
100	APIKEY is required	Укажите API-ключ как это описано в этом документе	
101	APIKEY is invalid	При копировании выделили не все символы ключа	
106	APIKEY is blocked (spam)	Вы нарушили правила сервиса, напишите объяснительную в службу поддержки	
110	SYSTEM ERROR	Шлюз недоступен, просто подождите и попытайтесь снова.	
113	IP RESTRICTION	Проблемы с ограничением доступа по IP-адресу решаются только через службу поддержки	
201	FROM is invalid	Неправильная подпись, возможно длина больше 11 символов, или недопустимые символы	
202	FROM is depricated	Не используйте эту подпись, она запрещена правилами	
210	TO is required	Возможно, пустой номер телефона или пропущен параметр to	
211	TO is invalid	Внимательно проверьте номера в списке рассылки, возможно, попал городской	
212	TO is depricated	Исключите этот номер из списка рассылки	
213	Unsupported zone	Не поддерживается отправка в эту страну или этому оператору, возможно городской номер	
220	TEXT is required	Введите текст сообщения	
221	TEXT too long	Сделайте текст короче	
230	ID is invalid	Ваш ID сообщения должен быть числом	
231	PACKET_ID is invalid	-	
240	Invalid INPUT list	Нужен список сообщений для отправки	
241	You don't have enough credit	Пополните баланс	
242	SMS count limit (trial)	У вас тестовый доступ, можно только  2 сообщения в списке рассылки, удалите лишние	
300	SMS server_id is required	Укажите server_id в списке проверки статусов	
301	SMS server_id is invalid	server_id должен быть числом	
302	SMS server_id not found	Возможно уже прошло больше 40 дней и сообщение уже удалено с сервера	
303	Invalid SMS check list	Пустой список проверки	
400	User not found	Не найден пользователь, возможно нужен новый API-ключ