SMS Пилот HTTP/CSV v1.8.7
2011-12-23
Быстрый старт
Отправка: http://smspilot.ru/api.php?send=hello&to=79087964781,79087964782&from=smspilot&apikey=XYZ
Статус: http://smspilot.ru/api.php?check=23091,23092&apikey=XYZ
Баланс: http://smspilot.ru/api.php?balance=sms&apikey=XYZ
Получить API-ключ: http://www.smspilot.ru/apikey.php

1.	Отправка SMS
2.	Проверка статусов SMS
3.	Баланс
4.	Cведения о ключе
1. Отправка SMS
Для отправки SMS нужно сделать HTTP GET/POST запрос с заданными параметрами

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

http:// – может принимать значения http:// или https:// (безопасный)

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

Примечания:
•	Кодировка по умолчанию UTF-8
•	Отправитель from может содержать:
•	текст латиницей, цифры, символы "-" и "." длиной 3-11 символов (например "MYSHOP.RU", "Taxi-12.Ru")
•	номер длиной 10-16 цифр в международном формате, без знака "+", например 79087964781 Не забудьте применить urlencode для текста и отправителя
•	Длина одного SMS сообщения составляет 70 символов кириллицей либо 160 символов латиницей. Если количество символов превышает максимально допустимое, то SMS разбивается на кусочки по 67 символов для сообщения кириллицей и по 153 символа для сообщения латиницей
•	GET запрос в большинстве случаев имеет ограничение на длину 1024 символа, используйте POST запрос, если получателей больше 300.
1.1	Успешный результат
В случае успешной отправки возвращается сервисное сообщение SUCCESS=SMS SENT и статусы SMS в формате CSV (id,phone,zone,status), перенос строки \n.

SUCCESS=SMS SENT N1/N2
id1,phone1,zone1,status1
id2,phone2,zone2,status2
id3,phone3,zone3,status3
…

N1 – стоимость отправки (в кредитах)
N2 – баланс (в кредитах)
id1 – код сообщения
phone1 – номер телефона
zone1 – зона (например 1 = Россия)
status1 – текущий статус SMS (см. ниже)
1.2 Пример:
http://smspilot.ru/api.php?send=Hello&to=79087964781,79161231212&from=test&apikey=XYZ

SUCCESS=SMS SENT 2/12000
4566,79087964782,1,0
4568,79161231212,1,0

1.3 Коды ошибок
ERROR=100: EMPTY APIKEY	Не указан параметр apikey	
ERROR=101: WRONG APIKEY	Неправильный apikey	
ERROR=102: APIKEY NOT FOUND	Такой ключ не найден	

		
ERROR=106: APIKEY BLOCKED (SPAM)	Подозрение в рассылке спама. Свяжитесь со службой поддержки.	
ERROR=107: EMPTY MESSAGE	Пустое значение параметра send	
ERROR=108: EMPTY PHONE	Пустое значение параметра to	
ERROR=109: WRONG PHONE	Неправильный номер телефона	
ERROR=110: SYSTEM ERROR	Непредвиденная ошибка системы, возможно неверный адрес отправителя	
ERROR=111: EMPTY PHONELIST	Пустой список получателей, после автоматического удаления "плохих" номеров	
ERROR=112: SMS LIMIT	Попытка отправить много смс при низком балансе	
ERROR=113: IP RESTRICTION	Попытка доступа с чужого сервера (при включенном ограничении по IP). Свяжитесь со службой поддержки для включения данной опции.	
ERROR=114: CHECK ERROR	Ошибка проверки статуса	
ERROR=115: SENDER	Ошибка значения отправителя (from): должен быть номер (6..14 цифр), или название 3-11 символов(A-Za-z0-9.-)	
ERROR=116: DEPRICATED SENDER	Запрещенное значение отправителя (from)	
ERROR=117: ACCOUNT RESTRICTION	Ограничение тест-аккаунта, возможно больше 2-х номеров в пакете	

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

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

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

http:// – может принимать значения http:// или https:// (безопасный)
1)	check – со значением ID отправленной SMS или нескольких ID(s) разделённых запятыми, специальное значением "recent" вернёт список SMS за последние 24 часа;
2)	apikey – купленный буквенно-цифровой ключ (http://www.smspilot.ru/apikey.php).

2.1 Результат
Возвращает список SMS в формате CSV (id,phone,zone,status), например:

4566,79087964782,1,-1
4567,79131231212,1,2
2.2 Коды статуса SMS
-2	не принято, неправильный номер, ID не найден	
-1	сообщение не доставлено (телефон абонента выключен, оператор не поддерживается)	
0	новое сообщение, подготовка к отправке	
1	в очереди у оператора	
2	сообщение успешно доставлено	
2.3 Пример

http://smspilot.ru/api.php?check=94,95,96&apikey=XYZ
94,79087964782,1,-1
95,79131231212,1,1
96,79131231212,1,2

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

http://smspilot.ru/api.php?balance=sms&apikey=XYZ

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

3.1 Результат
Возвращает количество оставшихся SMS (по зоне 1 – Россия), например:
20456
3.2 Пример
http://smspilot.ru/api.php?balance=sms&apikey=XYZ
20455

4. Получение сведений о ключе

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

http://smspilot.ru/api.php?apikey=XYZ
4.1 Результат
SUCCESS=APIKEY INFO
apikey = здесь будет значение ключа
email = здесь будет email владельца
sms_total = оплачено смс
sms_sent = отправлено смс
status = -1 – заблокирован за нарушения, 0 – ограниченный доступ, 1 – полный доступ
amount = сумма последнего платежа
currency = валюта последнего платежа
date = дата/время создания
date_paid = дата/время оплаты
date_access = дата/время последнего запроса
last_ip = последний IP адрес 
history = история в виде строк разделённых символом |
allow_ip = список разрешенных IP адресов
balance = текущий баланс (в кредитах)

+ Другие свойства

Изменения 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