API для отправки SMS сообщений

В данном форуме описаны все API, поддерживаемые нашими услугами.

API для отправки SMS сообщений

Сообщение sd » 20 сен 2010, 14:47

Обращение к API происходит по протоколу HTTP(S) (методы POST или GET) по адресу:

Код: Выделить всё
http://api.comtube.ru/scripts/api/sms.php

В дополнение к адресу необходимо передавать следующие параметры:

  • action - Действие. Возможны следующие варианты:

    • send – отправить SMS,
    • terminate – отменить отправку (пока не поддерживается),
    • resume – возобновить рассылку, если она была прервана пользователем с помощью terminate или автоматически сервером приложений,
    • start – запустить выполнение черновика,
    • state – получить статус отправки SMS,
    • statistics – получить статистику по отправленным SMS,
    • getsmses – получить список SMS (входящих и исходящих),
    • mark – пометить входящее сообщение прочитанным или не прочитанным,
    • listsenderids – получить список разрешенных номеров отправителей (она же: SenderID?, подпись),
    • getlimits – получить лимиты по рассылкам SMS,
    • listsenttasks – получить список отправленных рассылок (можно использовать совместно с параметрами fromdttm, untildttm, count),
    • listplannedtasks – получить список запланированных рассылок,
    • listsenderids - получить список разрешенных SenderIDs.
    • listdrafts – получить список черновиков,
    • delete – удалить задание на рассылку (удалить можно только выполненные, прекращенные задания или черновики)
  • uid - идентификатор сообщения. Используется при проверке статуса, удалении, остановке, запуске, получении статистики
  • number - номер телефона получателя. Разрешается указывать несколько номеров, разделенных ";" или ","
  • numfile - файл с номерами телефонов или с номерами телефонов и текстом сообщений. Этот параметр не должен участвовать в формировании подписи.
  • when - Указывает дату/время начала отправки SMS(-ов). Формат параметра следующий: YYYY-MM-DD HH:MM:SS. Пример: 2012–12–31 12:00:00. Если параметр не указан, то SMS отправляется сразу. Для action = send
  • upto - Указывает дату/время завершения отправки SMS(-ов). Формат параметра следующий: YYYY-MM-DD HH:MM:SS. Пример: 2011–11–11 11:11:11. Если параметр не указан, то верхнего лимита времени по отправке SMS не существует. Желательно использовать в тех случаях, когда нужно отправлять очень много SMS. Если до указанного времени SMS отправить не удалось, то он никогда не отправится. Для action = send
  • starttime - Время суток, когда разрешается начало отправки SMS. Формат параметра следующий: HH:MM:SS. Использовать тогда, когда указаны when и upto. Для action = send
  • stoptime - Время суток, когда отправка SMS заканчивается. Формат параметра следующий: HH:MM:SS. Использовать тогда, когда указаны when и upto. Для action = send
  • days - Тип дней недели, когда необходимо выполнять отправку SMS: 0 – все дни (по умолчанию), 1 – рабочие дни, 2 – выходные и праздничные дни. Для action = send
  • senderid - Номер телефона (длиной не более 20 цифр) или текст (не более 11 символов), который будет виден принимающей стороне. По умолчанию, 'Comtube.com'. Для action = send
  • name - Название задания на отправку SMS. Если параметр не указан, то используется стандартное название “New sms task”. Допустимая длина параметра от 1 до 64 символов. Для action = send.
  • message - Текстовое сообщение для отправки. Может быть пустым. В этом случае, текст сообщения будет браться из файла с номерами телефонов. Для action = send. В тексте сообщения разрешается использовать следующие переменные:

    • %CT_N% – имя получателя из адресной книги пользователя,
    • %CT_F% – фамилия получателя,
    • %CT_M% – отчество получателя,
    • %CT_FN% – отображаемое имя получателя,
    • %CT_COL_N% – номер колонки в текстовом файле, где N – номер от 1 (на данный момент еще не поддерживается).
  • who - Для action = getsmses указывает номер телефона, для которого нужно получить статистику
  • fromdttm - Для action = getsmses указывает дату и время, после которой необходимо получить список SMS
  • untildttm - Для action = getsmses указывает дату и время, до которой необходимо получить список SMS
  • incl - Для action = getsmses указывает включать или нет дату и время для параметров fromdttm и untildttm (то есть, использовать “<"/">" или "<="/">=")
  • what - Для action = getsmses указывает, какие SMS требуется получить:

    • 0 – все (входящие и исходящие),
    • 1 – входящие прочитанные,
    • 2 – входящие не прочитанные,
    • 3 – все входящие,
    • 4 – исходящие
  • count - Для action = getsmses указывает количество SMS, которые нужно получить
  • charset - кодировка, в которой передается параметр message (koi8-r, utf-8). Не обязательный параметр.
  • username – логин пользователя. Обязательный параметр.
  • type – тип возвращаемого результата: xml (по умолчанию), html, csv, json. Необязательный параметр.
  • signature – подпись запроса. Обязательный параметр. Как создать подпись смотрите раздел "Создание подписи (signature)"
  • isread - Указывает, пометить ли сообщение как прочитанное: 1 - да, 0 - не прочитанное. Для действия action = mark
  • report_to - Адрес электронной почты, куда следует отправлять отчет о выполнении задания.
  • group - Название группы контактов адресной книги, которым необходимо отправить SMS сообщения. У контакта адресной книги берется контакт с типом "Мобильный телефон". Если его нет, то сообщение ему не будет отправлено. Если их несколько, то сообщение отправляется на первый указанный мобильный телефон.
  • asdraft - Указывает, что вместо отправки сообщения(-ий) следует создать черновик (=1), который можно будет запустить отдельно. Для action = send

Обработка результата запроса

После обработки запроса API вернет согласно запрашиваемому действию те или иные данные. Ниже приведен пример ответа при отправке одиночного SMS сообщения:

Код: Выделить всё
<?xml version="1.0" encoding="utf-8"?>
<result>
<id>99221559</id>
<uid>2c51сa5e-b7bd-45ad-a119-6dadca63e131</uid>
<count>1</count>
<code>200</code>
<desc>OK</desc>
</result>


При проверке статуса ответ будет таким:

Код: Выделить всё
<?xml version="1.0" encoding="utf-8"?>
<result>
<numbers>
<item>
<id>99221559</id>
<sent_at>2012-06-28 11:12:00</sent_at>
<number>79261112233</number>
<parts_cnt>1</parts_cnt>
<parts_sent>1</parts_sent>
<status>12</status>
<desc>No error</desc>
</item>
</numbers>
<code>200</code>
<desc>OK</desc>
</result>


Поле code указывает код выполнения операции:

  • 200 – OK – Операция прошла успешно. В случаях, когда запрашивается статистика в формате csv, html и операция прошла успешно, код ошибки не возвращается.
  • 204 – No Content – возвращается в случаях, когда запрашиваемая информация не найдена. Например, если при запросе статистики по указанному фильтру ничего не найдено, то вернется именно этот код
  • 400 – Bad Request – указывает, что один или несколько параметров указаны не верно или отсутствуют. В поле desc, как правило, возвращается название параметра, который указан не правильно
  • 401 – Authorization Failed – Неправильно указан логин/пароль или неправильно сформирована подпись signature
  • 402 – Not enough money OR Payment required – Указывает, что для совершения операции недостаточно денег. Требуется пополнить счет
  • 403 – Account Blocked OR User Blocked – Указывает, что учетная запись пользователя заблокирована по тем или иным причинам
  • 500 – Internal Server Error – Возникла внутренняя ошибка.
  • 501 – Not Implemented – Указывает, что запрашиваемая функциональность еще не реализована.
  • 503 – Service Unavailable – Указывает, что не удалось подключится к серверу приложения для выполнения операции. Однако операция может быть выполнена чуть позже.

Поле status при проверке статуса сообщения означает следующее:

  • 10 - Отправлено
  • 12 - Доставлено
  • 20 - В очереди на отправку
  • 0 - Не удалось отправить/доставить

Обновлено: 28 Июня 2012

Внимание: Старое API больше не поддерживается, однако будет продолжать работать еще некоторое время. Поэтому прошу не сильно медлить при переходе на новое API.
Аватара пользователя
sd
 
Сообщения: 5184
Зарегистрирован: 31 июл 2009, 13:11

Re: API для отправки SMS сообщений

Сообщение maxz_alcoplus_ru » 11 фев 2011, 15:49

Есть примеры для отправки из 1С 8 ?
Интересует следующее:
1. Пример отправки и подтверждения что доставка выполнена / не выполнена...
maxz_alcoplus_ru
 
Сообщения: 1
Зарегистрирован: 25 ноя 2009, 21:45

Re: API для отправки SMS сообщений

Сообщение sd » 11 фев 2011, 16:15

К сожалению, для 1С примеров нет.
API для запроса подтверждения доставки/недоставки тоже пока что нет.

Наколько я знаю, из 1С можно отправлять email'ы. Можно воспользоваться услугой email2sms (читайте внизу), где в теме письма надо указать логин, а в приложенном файле номера телефонов с текстом сообщений для каждого номера отдельно.

Что касается использования API из 1C, то мы посмотрим, может и выложим...
Аватара пользователя
sd
 
Сообщения: 5184
Зарегистрирован: 31 июл 2009, 13:11

Re: API для отправки SMS сообщений

Сообщение inilus » 12 фев 2011, 11:59

from – идентификатор отправителя.

Можно ли указывать номер телефона от которого должно прийти? Разумеется, только из зарегистрированных на аккаунт.
inilus
 
Сообщения: 5
Зарегистрирован: 03 фев 2011, 21:24

Re: API для отправки SMS сообщений

Сообщение sd » 12 фев 2011, 12:52

Да, можете указывать.
Аватара пользователя
sd
 
Сообщения: 5184
Зарегистрирован: 31 июл 2009, 13:11

Re: API для отправки SMS сообщений

Сообщение af » 28 фев 2011, 06:49

Можно ли предать параметры для планирования отправки на дату и время?
af
 
Сообщения: 7
Зарегистрирован: 26 фев 2011, 01:03

Re: API для отправки SMS сообщений

Сообщение sd » 28 фев 2011, 10:15

На данный момент нельзя, но в течение недели добавим и такую возможность.
Аватара пользователя
sd
 
Сообщения: 5184
Зарегистрирован: 31 июл 2009, 13:11

Re: API для отправки SMS сообщений

Сообщение af » 28 фев 2011, 20:14

sd писал(а):На данный момент нельзя, но в течение недели добавим и такую возможность.

Будем ждать. Сервис отличный. А то у нас интернет-магазин и прикручиваем этот сервис к системам оплаты и поставкам. Они идут круглосуточно. Нужно, чтоб клиент не вздрагивал в 3 часа ночи от СМСки, что товар поступил на склад ;)

А как узнаем о реализации этой возможности? В данной ветке будет публикация?
af
 
Сообщения: 7
Зарегистрирован: 26 фев 2011, 01:03

Re: API для отправки SMS сообщений

Сообщение sd » 28 фев 2011, 21:13

Да, будет публикация в данной теме. Так что рекомендую подписаться на данную ветку.
Аватара пользователя
sd
 
Сообщения: 5184
Зарегистрирован: 31 июл 2009, 13:11

Re: API для отправки SMS сообщений

Сообщение sd » 01 мар 2011, 19:31

Добавилась возможность указывать время отправки SMS сообщений:

when – дата и время отправки сообщения (формат ГГГГ-ММ-ДД ЧЧ:ММ:СС) в часовом поясе, который указан в личном кабинете. Значение по умолчанию now. Необязательный параметр.

Если у вас в личном кабинете указан часовой пояс, например Екатеринбурга, и вы укажите время 2011-03-03 08:00:00, то сообщение отправится в указанное время по Ектаринбургскому времени.

Описание поправлено.
Аватара пользователя
sd
 
Сообщения: 5184
Зарегистрирован: 31 июл 2009, 13:11

След.

Вернуться в API

Просмотр страницы «Кто сейчас на форуме COMTUBE»

Сейчас этот форум просматривают: нет зарегистрированных пользователей и гости: 5