SMS HTTP API

Стандартная длина SMS составляет 160 символов из алфавита GSM

(http://en.wikipedia.org/wiki/GSM_03.38). Более длинные SMS можно отправлять по отдельным частям, которые в конце для получателя будут объединены в одно SMS, но каждая из этих частей будет показана в счете как отдельное SMS. Однако, отправляя несколько SMS-пакетов, каждая отдельная часть немного короче, чем одно SMS — одна часть может содержать до 153 символов, например, 160-символьное SMS может быть отправлено как SMS, состоящее из одной части, а 170-символьное SMS будет отправлено в двух пакетах – в первом 153 символа, во втором – 17.

Так как алфавит GSM содержит только небольшую часть всех возможных символов, то SMS можно отправить в Юникоде, где возможны все символы, доступные в кодировании UCS-2, но в этом случае длина SMS уменьшится — SMS в юникоде может быть до 70 SMS в длину, или, если отправляется SMS-пакет, то каждая часть SMS может содержать до 67 символов.

Примечание —  в алфавите GSM целый ряд символов, которые могут занимать место двух символов, например, символ евро, квадратные скобки ([]) и др.

Теоретически возможно отправлять отдельные SMS-пакеты, состоящие даже из 255 частей, но из-за разной совместимости операторов, SMS-каналов и телефонных аппаратов максимально допустимая длина SMS-пакетов составляет 3 части SMS.

В зависимости от заключенного соглашения между вами и SMSTitan, для вашей учетной записи может быть предоставлена либо ежемесячная квота для отправки SMS (для договоров с последующей оплатой), либо лимит SMS (для договоров предоплаты) в зависимости от оплаченного объема. Величина ежемесячной квоты устанавливается по взаимному согласию и предусмотрена, в первую очередь, из соображений безопасности, чтобы в результате случайных (или намеренных) действий не отправлялось чрезмерное количество SMS-сообщений.

Адрес сервиса: http://traffic.smstitan.ru/API:0.9/

Все данные следует предоставлять в рамках запросов HTTP POST.

Для каждого запроса существуют обязательные параметры (названия case-sensitive):

• APIKey: присвоенный API- ключ
• Command: название команды

Другие параметры зависят от конкретной команды.

Выдаваемые из команд данные сериализуются с JSON.

Если полученный запрос ошибочен, то в ответ выдается параметр Error с кодом ошибки.

Общие коды ошибок, относящиеся на все команды:

• InvalidAPIVersion: в адресе указана ошибочная версия API (версия должна быть 0.9)
• NoAPIKey: не указан API-ключ
• InvalidAPIKey: ошибочный или несуществующий API-ключ
• UnauthorizedIP: IP-адрес клиента не авторизован
• CommandNotSpecified: не указана исполняемая команда (параметр Command пустой)
• CommandNotImplemented: указанная команда не существует или не доступна
• SystemError: ошибка системы
• В этой версии возможны команды
• SendBatch: отправляет одно новое SMS с заданными параметрами. Номер будут добавлен командой AddBatchRecipients
• AddBatchRecipients: добавляет номер к созданному командой SendBatch отправлению
• SendOne: отправляет одно SMS с заданными параметрами
• GetSenders: выдает список со всеми доступными именами отправителей (словесными номерами)

Желательно использовать SendBatch / AddBatchRecipients, кроме случаев, когда действительно необходимо отправить по одному отдельному SMS.

Описание команд:

SendBatch

Входящие параметры:

• Sender: текст адреса отправителя (буквенный номер), например, AlfaBank, MVideo, и т.д.
• Content: содержание SMS в кодировке UTF-8 (как для обычных, так и для Unicode SMS)
• SendTime: время отправки (когда начинает отправку), в формате Unix timestamp. Не обязателен, если не указан, тогда отправка начинается сразу.
• CC: код страны по умолчанию, который используется для номеров, в которых он не указан. Не обязателен, по умолчанию 7. Если номер содержит код страны, то не используется.
• Concatenated: 0/1 – если будет 0, а содержание слишком длинным, то выдается ошибка. Если 1, то будет отправлено как SMS-пакет, если это необходимо.
• Unicode: 0/1 – если будет 0, а в содержании символы не из алфавита GSM, то выдается ошибка. Если будет 1, то будет отправлено как Unicode SMS, если это необходимо.

По содержанию автоматически определяется, либо следует отправлять в Юникоде и/или как отдельный SMS-пакет.

Выдаваемые в ответе параметры:

• BatchID: ID отправки, который следует использовать подавая номера получателей с AddBatchRecipients.
• Error: код ошибки, если есть проблема с вызовом команд в целом. Если ошибки нет, то этого параметра не будет.

Возможные ошибки:

• InvalidSender: такой адрес отправителя не существует, не доступен или ошибочен
• NoContent: не указано содержание
• InvalidCC: ошибочный или несоответствующий код страны (если код указан)
• ContentTooLong: содержание слишком длинное– или содержание слишком длинное вообще, или, если Concatenated = 0, содержание длиннее одной части  SMS
• ContentContainsInvalidCharacters: если Unicode=0,и в содержании символы не из алфавита GSM, выдается эта ошибка
• MonthlyQuotaExceeded: превышен месячный лимит

AddBatchRecipients

Входящие параметры:

• BatchID: ID отправления, который выдается от SendBatch.
• Recipients: JSON-массив с номерами получателей, например,  «[79687241125,

79167156549, …]»

Выдаваемые в ответе параметры:

• MSSID: ассоциативный массив, где названием поля является номер телефона, а значения — ID SMS. В случае если проблема с получателем, то вместо ID SMS будут код ошибки, имеющей отрицательное значение.
• Error: код ошибки, если есть проблемы с вызовом команд в целом. Если ошибки нет, то этого параметра не будет.

Если среди получателей какой-то номер повторяется несколько раз, то в параметре выдаваемых данных MSSID он отобразится только один раз с одним ID SMS, и отправлено будет только одно SMS.

Возможные ошибки:

Как значения MSSID:

• -1: любая ошибка;
• -2: ошибочный номер – номер составлен неверно;
• -3: ошибочный номер — номер составлен верно, но в действительности не существует.
• -4: превышен месячный лимит

В параметре Error:

• InvalidBatchID: такой ID отправки не существует или не доступен для конкретногоID.
• InvalidRecipients: невозможно прочитать список получателей
• MonthlyQuotaExceeded: превышен месячный лимит. Ошибка выдается тогда, когда превышен лимит, и ни одно SMS не отправлено. Если превышен лимит в среде отправления, то для каждого номера, превышающего лимит, выдается ошибка -4.

SendOne

Входящие параметры:

• Number: номер телефона получателя– перед номером можно указать и код страны, только без 00 или +.
• Sender: текст адреса отправителя (буквенный номер), например, AlfaBank, Sportland, и т.д.
• Content: содержание SMS в кодировке UTF-8 (как для обычных, так и для Unicode SMS)
• SendTime: время отправки (когда начинает отправку), в формате Unix timestamp. Не обязателен, если не указан, тогда отправка начинается сразу.
• CC: код страны по умолчанию, который используется для номеров, в которых он не указан. Не обязателен, по умолчанию 7. Если номер содержит код страны, то не используется.
• Concatenated: 0/1 – если будет 0, а содержание слишком длинным, то выдается ошибка. Если 1, то будет отправлено как отдельные SMS-пакеты, если это необходимо.
• Unicode: 0/1 – если будет 0, а в содержании символы не из алфавита GSM, то выдается ошибка. Если будет 1, то будет отправлено как Unicode SMS, если это необходимо.

По содержанию автоматически определяется, либо следует отправлять в Юникоде и/или в виде отдельных SMS-пакетов.

Выдаваемые в ответе параметры:

• MSSID: ID SMS, который будет использоваться для получения отчетов о доставке (delivery reports).
• Error: код ошибки, если есть проблема с вызовом команд в целом. Если ошибки нет, то этого параметра не будет.

Возможные ошибки:

• InvalidNumber: ошибочный номер получателя
• InvalidSender: такой адрес отправителя не существует, не доступен или ошибочен
• NoContent: не указано содержание
• InvalidCC: ошибочный или несоответствующий код страны (если указан код)
• ContentTooLong: содержание слишком длинное – или содержание слишком длинное вообще, или, если Concatenated = 0, содержание длиннее одной части  SMS
• ContentContainsInvalidCharacters: если Unicode=0,и в содержании символы не из алфавита GSM, выдается эта ошибка
• MonthlyQuotaExceeded: превышен месячный лимит

GetSenders

Входящие параметры: нет

Выдаваемые в ответе параметры:

• Senders: массив со всеми возможными адресами отправителя. Если адреса не указаны, то параметр будет пустым.

Отчеты о доставке

На указанный клиентом адрес для отчетов присылается ссылка в виде HTTP POST с двумя параметрами:

• MSSID: ID SMS, полученный командами SendOne или AddBatchRecipients
• DLR: отчет о доставке, одно из следующих возможный значений:
• Delivered: SMS доставлено
• Sent: SMS отправлено, но не известно получено ли (шлюз не передал DLR)
• Buffered: SMS передано для доставки, но ждет очереди
• Undelivered: не удалось доставить SMS
• Error: ошибка системы или шлюза
• Other: другой, неопознанный отчет о доставке

В нормальных условиях отчетов Error и Other не должно быть вообще.