SMS API

Авторизация

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

Для этого каждый запрос должен содержать заголовок, либо аргумент X-Authorization с токеном соединения в формате AccessKey token.

Например заголовком:

POST /apps/activate HTTP/1.1
Host: app.sptele.ru
X-Authorization: AccessKey d8ac9959r12b43545XXXXX

X-Authorization передается в зависимости от настроек HTTP-подключения:

AccessKey d8ac9959r12b43545XXXXX — по умолчанию

Basic d8ac9959r12b43545XXXXX (или Basic base64encoded(username:password))

Bearer d8ac9959r12b43545XXXXX

либо параметром:

POST https://app.sptele.ru/api/apps/activate?X-Authorization=AccessKey d8ac9959r12b43545XXXXX

Отправка SMS-сообщений

Запрос:

Параметры можно передавать в заголовке запроса:

POST/GET https://app.sptele.ru/api/v2/sms?X-Authorization=AccessKey d8ac9959r12b43545XXXXX&destAddr=7XXXXXXXXXX&sourceAddr=MySender&shortMessage=Текст сообщения

А также в теле запроса:

{
    "sourceAddr": "MySender",
    "destAddr": "7XXXXXXXXXX",
    "shortMessage": "Текст сообщения"
}

Пример запроса с использованием CURL:

curl --location --request POST 'https://app.sptele.ru/api/v2/sms?X-Authorization=AccessKey%20d8ac9959r12b43545XXXXX&destAddr=7XXXXXXXXXX&sourceAddr=MySender&shortMessage=Текст сообщения'

curl --location 'https://app.sptele.ru/api/v2/sms?=' \
--header 'X-Authorization: AccessKey d8ac9959r12b43545XXXXX' \
--header 'Content-Type: application/json' \
--data '{
    "sourceAddr": "MySender",
    "destAddr": "7XXXXXXXXXX",
    "shortMessage": "Текст сообщения"
}'

Параметр	Тип	Описание
sourceAddr	string	Имя отправителя (только латиница или номер телефона) *Поле не должно содержать кириллицы*
destAddr	string	Номер телефона, на который отправляется SMS-сообщение в формате e.164, например, для Российской Федерации 7XXXXXXXXXX
shortMessage	string	Текст сообщения

Ответ при успешном выполнении запроса:

{
    "status": "Created",
    "requestId": "11273"
}

Ответ в случае отсутствия destAddr:

{
    "status": "Rejected",
    "error": "Missing destAddr param"
}

Параметр	Тип	Описание
status	string	Статус запроса: _{Created — Сообщение в системе создано, но ещё не отправлено Rejected — Сообщение не было принято к отправке, уточнение ошибки в error prohibitedForServiceError — Ключ не принадлежит услуге HLR invalidAccessKeyError — Ошибка в ключе авторизации} _{accountFinanciallyBlocked — Контрагент заблокирован по балансу/Блокировка по IP адресу}
requestId	string	Уникальный идентификатор запроса
error	string	Описание ошибок: _{Missing destAddr param — destAddr отсутствует в запросе Missing sourceAddr param — sourceAddr отсутствует в запросе Missing shortMessage param — shortMessage отсутствует в запросе Field sourceAddr must not contain Cyrillic — в sourceAddr присутствует кириллица}

Массовая отправка SMS-сообщений

Запрос:

POST/GET https://app.sptele.ru/api/v2/sms_bulk?X-Authorization=AccessKey d8ac9959r12b43545XXXXX

Тело запроса:

{
    "sourceAddr": "MySender",
    "destAddrs": [
        "79123213232",
        "2вауц",
        "71233212323"
    ],
    "shortMessage": "Текст сообщения"
}

Пример запроса с использованием CURL:

curl --location 'https://app.sptele.ru/api/v2/sms_bulk' \
--header 'X-Authorization: AccessKey d8ac9959r12b43545XXXXX' \
--header 'Content-Type: application/json' \
--data '{
    "sourceAddr": "MySender",
    "destAddrs": [
        "79123213232",
        "2вауц",
        "71233212323"
    ],
    "shortMessage": "Текст сообщения"
}'

Параметр	Тип	Описание
sourceAddr	string	Имя отправителя *Поле не должно содержать кириллицы*
destAddrs	string	Список телефонных номеров, на которые отправляются SMS-сообщения в формате e.164, например, для Российской Федерации 7XXXXXXXXXX
shortMessage	string	Текст сообщения

Тело ответа при выполнении запроса:

{
    "status": "ok",
    "results": [
        {
            "status": "Created",
            "requestId": "11276",
            "destAddr": "79123213232"
        },
        {
            "status": "Rejected",
            "error": "Not valid destAddr",
            "destAddr": "2вауц"
        },
        {
            "status": "Created",
            "requestId": "11277",
            "destAddr": "71233212323"
        }
    ]
}

Параметр	Тип	Описание
status	string	Статус запроса: _{Created — Сообщение в системе создано, но ещё не отправлено Enroute — Сообщение смаршрутизировано и ожидает отправки Delivered — Сообщение доставлено, получен статус доставки от оператора Expired — Истекло время жизни сообщения Deleted — Сообщение было отменено Undeliverable — Сообщение не доставлено по причине: номер не существует, нет места для новых СМС в телефоне Accepted — Сообщение отправлено, статус доставки от оператора ещё не получен Unknown — Неизвестная ошибка Rejected — Сообщение не было принято к отправке, уточнение ошибки в error NotUnique — Сообщение не было отправлено, потому что дублирует ранее отправленное prohibitedForServiceError — Ключ не принадлежит услуге SMS invalidAccessKeyError — Ошибка в ключе авторизации} _{accountFinanciallyBlocked — Контрагент заблокирован по балансу/Блокировка по IP адресу}
results	string	Результаты по каждому получателю
error	string	Описание ошибки: _{Missing destAddr param — destAddr отсутствует в запросе Missing sourceAddr param — sourceAddr отсутствует в запросе Missing shortMessage param — shortMessage отсутствует в запросе Field sourceAddr must not contain Cyrillic — в sourceAddr присутствует кириллица Not valid destAddr — Неправильно введен destAddr}
requestId	string	Уникальный идентификатор запроса
destAddr	string	Номер телефона, на который отправляется SMS-сообщение в формате e.164, например, для Российской Федерации 7XXXXXXXXXX

Получение статуса

Запрос:

Параметры можно передавать в заголовке запроса:

GET https://app.sptele.ru/api/v2/sms_status?X-Authorization=AccessKey d8ac9959r12b43545XXXXX&requestId=11273

А также в теле запроса:

{
    "requestId": "11273"
}

Пример запросов с использованием CURL:

curl --location 'https://app.sptele.ru/api/v2/sms_status' \
--header 'X-Authorization: AccessKey d8ac9959r12b43545XXXXX' \
--header 'requestId: 11273'

curl --location --request GET 'https://app.sptele.ru/api/v2/sms_status' \
--header 'X-Authorization: AccessKey d8ac9959r12b43545XXXXX' \
--header 'Content-Type: application/json' \
--data '{
    "requestId": "11273"
}'

Тело ответа при успешном выполнении запроса:

{
    "id": 9654,
    "destAddr": "7XXXXXXXXXX",
    "requestId": "11273",
    "status": "Rejected",
    "networkErrCode": 34,
    "mcc": 0,
    "mnc": 0,
    "ported": 0
}

Ответ в случае отсутствия параметра requestId:

{
    "status": "Rejected",
    "error": "Missing requestId param"
}

Параметр	Тип	Описание
id	integer	Уникальный идентификатор SMS-сообщения
destAddr	string	Номер телефона, на который было отправлено SMS-сообщение в формате e.164, например, для Российской Федерации 7XXXXXXXXXX
requestId	string	Уникальный идентификатор запроса
status	string	Статус запроса отправки SMS-сообщения: _{Created — Сообщение в системе создано, но ещё не отправлено Enroute — Сообщение смаршрутизировано и ожидает отправки Delivered — Сообщение доставлено, получен статус доставки от оператора Expired — Истекло время жизни сообщения Deleted — Сообщение было отменено Undeliverable — Сообщение не доставлено по причине: номер не существует, нет места для новых СМС в телефоне Accepted — Сообщение отправлено, статус доставки от оператора ещё не получен Unknown — Неизвестная ошибка Rejected — Мобильная сеть отклонила сообщение, скорее всего из-за фильтра или другого ограничения NotUnique — Сообщение не было отправлено, потому что дублирует ранее отправленное notFound — Если запись не найдена}
networkErrCode	string	Ошибки SS7, смотрите ниже
mcc	integer	Mobile Country Code – код страны
mnc	integer	Mobile Network Code – код мобильного оператора
ported	integer	Информация о том, был ли портирован номер: _{1 — если номер был портирован 0 — если не был портирован}
error	string	Описание ошибок: _{Missing requestId param — отсутсвтует requestId в запросе}

Получение статусов сообщений на Webhook

Источник запросов:

Webhook будут приходить с IP-адресов 185.175.44.211 и 46.148.235.62, которые необходимо включить в ACL на стороне веб-сервера клиента для обеспечения корректного взаимодействия.

Формат взаимодействия:

Обратные вызовы выполняются по протоколу HTTP.

Данные передаются в формате JSON.

Настройка Webhook происходит по запросу в техническую поддержку.

Отправка запроса:

Запрос отправляется в формате JSON, который имеет следующую структуру:

{
  "ported": 0,
  "mnc": 0,
  "requestId": "35714061",
  "destAddr": "7XXXXXXXXXX",
  "id": 639073386,
  "networkErrCode": 0,
  "mcc": 0,
  "status": "Delivered"
}

Параметр	Тип	Описание
ported	integer	Информация о том, был ли портирован номер: _{1 — если номер был портирован 0 — если не был портирован}
mnc	integer	Mobile Network Code – код мобильного оператора
requestId	string	Уникальный идентификатор запроса
destAddr	string	Номер телефона, на который отправляется SMS-сообщение в формате e.164, например, для Российской Федерации 7XXXXXXXXXX
id	integer	Уникальный идентификатор SMS-сообщения
networkErrCode	string	Ошибки SS7, смотрите ниже
mcc	integer	Mobile Country Code – код страны
status	string	Статус запроса отправки SMS-сообщения: _{Created — Сообщение в системе создано, но ещё не отправлено Enroute — Сообщение смаршрутизировано и ожидает отправки Delivered — Сообщение доставлено, получен статус доставки от оператора Expired — Истекло время жизни сообщения Deleted — Сообщение было отменено Undeliverable — Сообщение не доставлено по причине: номер не существует, нет места для новых СМС в телефоне Accepted — Сообщение отправлено, статус доставки от оператора ещё не получен Unknown — Неизвестная ошибка Rejected — Сообщение не было принято к отправке, уточнение ошибки в error NotUnique — Сообщение не было отправлено, потому что дублирует ранее отправленное}

Коды ошибок в статусе

Возможные коды ошибок в статусе SMS (значения networkErrCode).

Все неуказанные коды считаются зависящими от поставщика и не обрабатываются отдельно.

Код	Расшифровка	Описание
1	unknownSubscriber	Неизвестный абонент _{Абонент не зарегистрирован в сети}
5	unidentifiedSubscriber	Неопознанный абонент _{Абонент зарегистрирован, но информация о нем отсутствует или недоступна}
9	illegalSubscriber	Незаконный абонент _{Абоненту отказано в доступе из-за нарушения правил}
11	teleserviceNotProvisioned	Телекоммуникационная услуга не представлена _{Абонент не подключен к запрашиваемой услуге}
13	callBarred	Запрещенный вызов _{Запрет на вызов для данного абонента (например, из-за блокировки или ограничений тарифа)}
21	facilityNotSupported	Услуга не поддерживается _{Запрошенная услуга недоступна для абонента или сети}
27	adsentSubscriber	Адрес отправителя отсутствует _{Сообщение не доставлено из-за отсутствия данных об отправителе}
31	subscriberBusyForMT-SMS	Абонент занят для получения MT-HLR _{Абонент не может принять HLR из-за занятости устройства}
32	sm-DeliverFailure	Ошибка доставки HLR _{Общая ошибка, связанная с передачей HLR}
33	messageWaitingListFull	Список ожидания сообщений переполнен _{В памяти устройства абонента нет места для новых сообщений}
34	systemFailure	Системная ошибка _{Общая ошибка на стороне сети}
35	dataMissing	Отсутствуют данные _{Не хватает информации для выполнения операции}
36	unexpectedDataValue	Неожиданное значение данных _{Переданы некорректные или неожиданные данные}

Коды ошибок SMS

Код	Название	Описание
0	No error	Ошибок нет Абонент существует и доступен
1	Unknown subscriber	Номер телефона абонента не существует, неактивен или более не используется
2	Unknown subscriber – NR Changed	Ошибка переноса номера (Number Portability). Может возникать при многократном переносе номера
5	Unidentified subscriber	MSC не распознает IMSI абонента. Возможные причины: HLR не обновлен или сбой MSC
6	Absent subscriber for SMS	Устройство абонента недоступно для получения SMS (телефон выключен или вне зоны действия сети)
7	Unknown equipment	Сообщение отклонено, так как устройство абонента не идентифицировано
8	Roaming not allowed	Сообщение отклонено из-за ошибки аутентификации или фильтрации при роуминге
9	Illegal subscriber	Сообщение отклонено из-за ошибки аутентификации или фильтрации
10	Bearer Service not provisioned	Подписка абонента не поддерживает SMS
11	Teleservice not provisioned	Абонент не может принимать SMS. Причины: услуга не подключена, абонент в роуминге без активации SMS или оператор не налажал обмен SMS
12	Illegal equipment	Сообщение не доставлено из-за ошибки в телефоне абонента или SIM-карте; устройство или сеть не поддерживают SMS
13	Call barred	Абонент заблокирован: нулевой/отрицательный баланс, блокировка оператором, поврежденная SIM-карта, или неправильный PIN/PUK
21	Facility not supported	Подписка или устройство абонента не поддерживают работу с SMS-сервисом
27	Absent subscriber	Устройство абонента не зарегистрировано в сети (выключено или вне зоны покрытия)
28	Incompatible MS terminal error	Функция SMS не поддерживается мобильным устройством абонента
31	Subscriber busy for SM MT	Устройство абонента временно недоступно для доставки SMS
32	Equipment failure	Принимающее устройство не поддерживает SMS или соответствующую функцию
33	MS memory capacity exceeded	Принимающее устройство не имеет достаточной памяти для получения сообщения
34	GSM system failure	MSC отклонил сообщение из-за сбоя протокола SS7 или сетевой ошибки
35	GSM Data Error – data missing	Отсутствуют данные GSM
36	GSM Data Error	Некорректные данные GSM
45	Subscriber busy	Абонент в данный момент не может выполнять GSM-операции
100	RejectedByIpBlockedException	Блокировка по IP адресу
101	RejectedByFinBlockedException	Финансовая блокировка
102	SmsTemplateRejectedException	Шаблон сообщения не найден
500	Invalid destination address	Некорректный номер получателя
501-506	Routing error	Ошибка маршрутизации
507	SystemFailure	Общий системный сбой
508	ThrottledException	Превышен лимит запросов или сообщений (ограничение скорости/rate limit)
509	Invalid parameter length	Некорректная длина сообщения или параметра
510	Invalid destination address	Некорректный адрес получателя (destination address)
511	Loop detection error	Обнаружена петля маршрутизации (циклическая отправка)
512	Invalid source address	Некорректный адрес отправителя (source address)
513	System error	Внутренняя ошибка системы
999	Unspecified error	Неопределенная ошибка (общий код без уточнения причины)

На этой странице