SMS HTTP API

SMS HTTP API

Обмен SMS-данными с системой„Traffic”

SMS Модули (скрипты) для CMS:

OpenCart

OCStore

Prestashop

1С-Битрикс

WordPress WooCommerce

R-Keeper (UCS)

Примеры для разработчиков:

PHP класс и скрипт для HTTP API

Приступая к работе с API подключением, нам потребуется информация, чтобы активировать ваш счет и доступ к протоколу HTTP.

Необходимые данные для создания подключения:

  1. IP-адрес вашего сервера (их может быть несколько) — это адрес с которого будут поступать запросы на отправку, как правило ip вашего сайта или базы данных.
  2. Адрес, на который будут подаваться отчеты о доставке, в соответствии с предоставленным описанием в конце спецификации. Если отчеты о доставке не требуются, то адрес можно пропустить.
  3. Буквенное имя отправителя, с которого будут уходить SMS к оператору.

Получив эту информацию, для вас будет сформирован API- ключ, который может быть использован для верификации подключения.

Примечание —  для каждой среды (если у вас их несколько), из которой вы хотите отправить SMS, например, среда разработки/ тестирования и среда продукции, понадобится отдельный API — счет и отдельный API- ключ.

Общая SMS-информация

Стандартная длина 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-сообщений.

API-спецификация

Адрес сервиса: 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 не должно быть вообще.

Чтобы начать использовать наши услуги
Зарегистрируйтесь