HLR и SMS HTTP API

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

Запросы к API выполняются по протоколу HTTP. Входные и выходные структуры данных передаются в теле запроса и ответа в формате JSON.

Авторизация

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

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

Например заголовком:
POST /apps/activate HTTP/1.1
Host: api.unibell.ru
X-Authorization: AccessKey d8ac9959r12b43545da9034
или
Authorization: Basic d8ac9959r12b43545da9034

либо параметром:
POST api.unibell.ru/apps/activate?X-Authorization=AccessKey d8ac9959r12b43545da9034

Формат ответов

JSON схема любого ответа содержит параметр status типа string со следующими значениями:

Значение status	Описание
ok	Без ошибок
invalidAccessKeyError	Неверный AccessKey
requiredJsonError	В теле запроса требуется JSON
invalidSchemeError	Неверная схема JSON
invalidDataError	Ошибочные входные данные
prohibitedForAppError	Запрещено для данного приложения
prohibitedForServiceError	Запрещено для данной услуги
rpcError	Коммуникационная ошибка

Например:

    {
        …
        “status”: “ok”
        ....
    }

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

Запрос:

POST api.unibell.ru/hlr

    {
        "reference": "123456789",
        "msisdn": "7XXXXXXXXXX",
    }

Параметр	Тип	Описание
reference	string	Пользовательский параметр с которым будет вызван callback по результатам выполнения приложения
msisdn	string	Исходящий номер

Ответ

    {
        “id”: “XXXXX”,
        “href”: “XXXXX”,
        “msisdn”: “XXXXX”,
        “reference”: “XXXXX”,
        “details”: {},
        “status”: “sent”,
        “createdDateTime”: “XXXX-XX-XX XX:XX:XX”,
        “statusDateTime”: “XXXX-XX-XX XX:XX:XX”,
    }

Параметр	Тип	Описание
id	string	Уникальный идентификатор
msisdn	string	Исходящий номер
reference	string	Пользовательский параметр с которым будет вызван callback по результатам выполнения приложения
details	string
status	string	Статус HLR сообщения, для вновь созданного — sent
createdDateTime	string	Дата/время создания
statusDateTime	string	Дата/время получения статуса

Для получения результатов выполнения запроса может быть настроен callback по протоколу HTTP/HTTPS методом POST. Параметры передаются Content-Type: application/x-www-form-urlencoded.

Параметр	Тип	Описание
id	string	Уникальный идентификатор
msisdn	string	Исходящий номер
reference	string	Пользовательский параметр с которым будет вызван callback по результатам выполнения приложения
details	string
status	string	Статус HLR сообщения: ^{sent — отправлено, active — номер активен, absent — не активен, failed — ошибка отправки, unknown — неизвестно}
networkErrCode	string	Ошибки SS7, см. ниже
imsi		IMSI абонента
vlr		VLR абонента
hlr		HLR абонента
mcc		MCC сети
mnc		MNC сети
ported		Является ли абонент портированным в другую сеть
createdDateTime	string	Дата/время создания
statusDateTime	string	Дата/время получения статуса

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

Запрос:

POST/GET https://api.unibell.tech/sms_new?X-Authorization=AccessKey d8ac9959r12b43545XXXXX&destAddr=7917XXXXXXX&sourceAddr=XXXXX&short Message=Привет, как дела?

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

Ответ:

{
“reference”: “5b922bba6be053cd6a2ecebb1a31438a”,
“status”: “ok”,
}

Параметр	Тип	Описание
status	string	Статус запроса смотрите выше
reference	string	Уникальный идентификатор сообщения

Для получения результатов выполнения запроса может быть настроен callback (обратный вызов) по протоколу HTTP/HTTPS с помощью метода POST. Передаются параметры Content-Type: application/x-www-form-urlencoded.

Параметр	Тип	Описание
reference	string	Уникальный идентификатор сообщения
sourceAddr	string	Имя отправителя
destAddr	string	Номер телефона, на который отправляется SMS-сообщение в формате e.164 для Российской Федерации 7XXXXXXXXXX
status	string	Статус SMS-сообщения _{DELIVERED — доставлено UNDELIVERABLE — не доставлено (уточнение в коде сетевой ошибки) REJECTED — отклонено с ошибкой (уточнение в коде сетевой ошибки)}
networkErrCode	string	Ошибки SS7, смотрите ниже
imsi	string	IMSI абонента
vlr	string	VLR абонента
hlr	string	HLR абонента
createdDateTime	string	Дата/время создания
statusDateTime	string	Дата/время получения статуса

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

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

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

Код	Название	Описание
0	Нет ошибки	Абонент существует и доступен
1	Абонент не существует	Указанный номер телефона не существует
6	Абонент не в сети	Телефон абонента отключен или находится вне зоны действия сети
11	Нет услуги SMS	Означает, что абонент не может принять SMS-сообщение. Например, услуга не подключена, или абонент находится в роуминге, где не активирован прием сообщений, или у оператора абонента не налажен обмен SMS с текущим роуминговым оператором. Также это может быть городской номер без приема сообщений
12	Ошибка в телефоне абонента	Не удается доставить сообщение абоненту из-за ошибки в телефонном аппарате или SIM-карте
13	Абонент заблокирован	Возникает, например, если на счету абонента нулевой или отрицательный баланс, и он находится в роуминге, или заблокирован оператором за продолжительную неуплату либо добровольно самим абонентом. Также данная ошибка может возвращаться при повреждении SIM-карты либо неправильном вводе PIN и PUK-кодов SIM-карты
21	Нет поддержки сервиса	Нет поддержки сервиса

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