2.Описание протоколов управления услугами

Skip to end of metadata
Go to start of metadata

Внешнее управление услугами «UC Centrex» доступно через веб-сервис. Точка привязки веб-сервиса выделяется по запросу.

2.1.Авторизация OSS

Для выполнения действий по управлению услугами, OSS/BSS должна быть авторизована.
Для доступа к точке привязки веб-сервиса необходимо выполнить BASIC HTTP авторизацию.

2.2.Формат информационного обмена

Для вызова веб-сервиса управления услугами используется протокол SOAP поверх транспорта HTTP в демонстрационном режиме и HTTP/SSL в промышленном режиме эксплуатации.

Формальное описание интерфейса на языке описания веб-сервисов WSDL прилагается к настоящему документу и также доступно по имени UCServiceProvision.wsdl в точке привязки веб-сервиса.

Все методы возвращают объект типа opResponse с полями code и text. В поле code содержится код результата операции, в поле text содержится описание результата.

2.3.Регистрация объектов

2.3.1.Регистрация эккаунта

Сигнатура:

Результат:

Код ошибки Текст Описание
200 OK Учетная запись создана
500
Внутренняя ошибка сервера
501 Account exists Учетная запись с таким именем уже существует
502 No such domain Домен не зарегистрирован
503 No service class Нет такого класса обслуживания
504 Invalid preference Неправильное свойство учетной записи
507 password is too simple Пароль аккаунта слишком простой, необходимо указать более сложный пароль
515 Number exists Номер уже зарегистрирован за другим объектом
516 Telnum not found Номер не существует
517 Exhaust accounts limit Исчерпан лимит аккаунтов


Пример:

возвращает в случае успеха:

возвращает в случае неуспеха:

2.3.2.Регистрация домена

Сигнатура:

e164telnums - номера телефонов, которые будут делегированы в домен. Если номера в операторском домене нет, он будет создан и привязан к дефолтному шлюзу.
route - идентификатор маршрута, который надо назначить домену
dialplan - идентификатор дефолтного диалплана для домена
Demo - выставляет домену специальный признак, по которому он исключается из учета.
maxLines - максимальное количество линий, которое доступно домену. Если не задано, количество линий считается неограниченным.
maxLinesIn - максимальное количество входящих линий, которое доступно домену
maxLinesOut - максимальное количество исходящих линий, которое доступно домену
Если задано значение maxLines, то maxLinesIn и maxLinesOut игнорируются.

Результат:

Код ошибки Текст Описание
200 OK Домен создан
500   Внутренняя ошибка сервера
503 No service class Нет такого класса обслуживания
504 Invalid preference Неправильное свойство домена
511 Domain exists Домен с таким именем уже существует
512 Incorrect DNS record “%testline%”; Домен не прошел валидацию DNS. В тексте перечисляются некорректные DNS записи.
515 Number exists Номер уже зарегистрирован за другим доменом
518 Telnum delegate error Ошибка делегации номера

Пример:

возвращает в случае успеха:

возвращает в случае неуспеха:

2.3.3.Проверка возможности создания домена

Сигнатура:

Name – имя домена, которое необходимо проверить на возможность создания.

Результат:

Код ошибки Текст Описание
200 OK Домен свободен
500   Внутренняя ошибка сервера
511 Domain exists Домен с таким именем уже существует
512 Incorrect DNS record “%testline%”; Домен не прошел валидацию DNS. В тексте перечисляются некорректные DNS записи.

Пример:

возвращает в случае успеха:

возвращает в случае неуспеха:

2.3.4.Проверка сложности пароля

Сигнатура:

password – пароль, сложность которого необходимо проверить.
user – пользователь в формате user@domain, для которого необходимо проверить сложность пароля.
Если user не задан, пароль проверяется для passwordchecker@itoolabs.com.
Результат:

Код ошибки Текст Описание
200 OK Допустимый пароль
500   Внутренняя ошибка сервера
507 password too simple Пароль слишком простой
508 incorrect password Пароль содержит недопустимые символы

Пример:

возвращает в случае успеха:

возвращает в случае неуспеха:

2.4.Временная блокировка объектов

2.4.1.Временная блокировка объекта

Сигнатура:

Результат:

Код ошибки Текст Описание
200 OK Учетная запись заблокирована
404 Not found Нет объекта с таким именем
500   Внутренняя ошибка сервера
505 Already frozen Объект уже заблокирован

Пример:

возвращает в случае успеха:

возвращает в случае неуспеха:

2.4.2.Разблокировка объекта

Сигнатура:

Результат:

Код ошибки Текст Описание
200 OK Учетная запись заблокирована
404 Not found Нет объекта с таким именем
500   Внутренняя ошибка сервера
506 Already thawed Объект уже разблокирован

Пример:

возвращает в случае успеха:

возвращает в случае неуспеха:

2.4.3. Проверка блокировки объекта

Сигнатура:

Результат:

Код ошибки Текст Frozen Описание
200   true Объект заблокирован
200   false Объект разблокирован
404 Not found   Нет объекта с таким именем
500     Внутренняя ошибка сервера

Пример:

возвращает для заблокированного объекта:

возвращает для разблокированного объекта:

2.5.Удаление объектов

Внимание, удалять можно только заблокированный объект.

2.5.1.Удаление эккаунтов

Сигнатура:

Результат:

Код ошибки Текст Описание
200 OK Учетная запись удалена
404 Not found Нет объекта с таким именем
500   Внутренняя ошибка сервера
506 Account is active Объект не был заблокирован, удаление невозможно

Пример:

возвращает в случае успеха:

возвращает в случае неуспеха:

Телефонный номера, привязанный пользователю, будет высвобожден немедленно.

2.5.2.Удаление домена

Сигнатура:

Удаление домена возможно только, если он был предварительно переведён в неактивное состояние. При этом если в домене находятся пользователи, то удаление не произойдёт. Чтобы удалить домен вместе с пользователями, нужно передать параметр force равный true.

Код ошибки Текст Описание
200 OK Учетная запись удалена
500   Внутренняя ошибка сервера
404 Not found Нет объекта с таким именем
506 Domain is active Объект не был заблокирован, удаление невозможно

Пример:

возвращает в случае успеха:

возвращает в случае неуспеха:

Телефонные номера, выделенные пользователям домена, будут высвобождены немедленно.

2.6.Изменение свойств объектов

2.6.1.Изменение данных пользователя

Сигнатура:

Результат:

Код ошибки Текст Описание
200 OK Аккаунт изменен
404 Not found Нет объекта с таким именем
500   Внутренняя ошибка сервера
503 No service class Нет такого класса обслуживания
504 Invalid preference Неправильное свойство учетной записи
507 password is too simple Пароль аккаунта слишком простой, необходимо указать более сложный пароль

Пример:

установит пароль для пользователя test@mtt.cport.ru в NewPassword.

вызов вернет в случае успеха:

или вернет в случае неуспеха:

2.6.2.Изменение настройки учётной записи

Сигнатура:

Результат:

Код ошибки Текст Описание
200 OK Учетная запись создана
404 Not found Нет объекта с таким именем
500   Внутренняя ошибка сервера
504 Invalid preference Неправильное свойство учетной записи

Пример:

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

вызов вернет в случае неуспеха:

2.6.3.Назначение телефонного номера учетной записи

Сигнатура:

Результат:

Код ошибки Текст Описание
200 OK Учетная запись создана
404 Not found Нет объекта с таким именем
500   Внутренняя ошибка сервера
515 Number exists Номер уже зарегистрирован за другим объектом
516 Number not found Номер не зарегистрирован за этим объектом, либо нет присваемого номера

Пример:

вызов вернет в случае неуспеха:

2.6.4.Назначение короткого номера учетной записи

Сигнатура:

Результат:

Код ошибки Текст Описание
200 OK Учетная запись создана
404 Not found Нет объекта с таким именем
500   Внутренняя ошибка сервера
515 Number exists Номер уже зарегистрирован за другим объектом
516 Number not found Номер не зарегистрирован за этим объектом, либо нет присваемого номера

Пример:

вызов вернет в случае неуспеха:

2.6.5.Изменение домена

Сигнатура:

maxLines - максимальное количество линий, которое доступно домену. Если не задано, количество линий считается неограниченным.
maxLinesIn - максимальное количество входящих линий, которое доступно домену
maxLinesOut - максимальное количество исходящих линий, которое доступно домену
Если задано значение maxLines, то maxLinesIn и maxLinesOut игнорируются.

Результат:

Код ошибки Текст Описание
200 OK Домен обновлен
404 Not found Нет объекта с таким именем
500   Внутренняя ошибка сервера
504 Invalid preference Неправильное свойство домена

Пример:

вызов вернет в случае успеха:

Для сброса класса обслуживания домена и удаления списка доступных сервисов, необходимо передать в serviceClass пустую строку:

2.6.6.Получение списка пользовательских номеров

Сигнатура:

name — имя пользовотеля в формате user@domain

Результат:

Код ошибки Текст Описание
200 phone Объект или массив объектов с параметрами:
uid – идентификатор,
name – название телефона,
number – номер телефона,
type – тип,
delay – задержка,
description – описание,
smsOnPayment – получать SMS-уведомления
о необходимости пополнения счета,
smsOnNeedFunds – получать SMS-уведомления
о зачислении средств на счет,
disabled – заблокирован
201 empty list Пустой список телефонов
404 unknown user account,
unknown secondary domain name
Нет пользователя с таким именем,
некорректное имя домена
500   Внутренняя ошибка сервера
504 Invalid preference Неправильный параметр запроса

Пример:

вызов вернет в случае неуспеха:

вызов вернет в случае успеха:

2.6.7.Изменение пользовательских номеров

Сигнатура:

name — имя пользовотеля в формате user@domain,
phone — массив объектов класса OwnPhone, содержащего следующие поля:
String uid – идентификатор,
String name – название телефона,
String number – номер телефона,
String type – тип,
int delay – задержка,
String description – описание,
boolean smsOnPayment – получать SMS-уведомления о необходимости пополнения счета,
boolean smsOnNeedFunds – получать SMS-уведомления о зачислении средств на счет,
boolean disabled – заблокирован

Результат:

Код ошибки Текст Описание
200 OK Номера успешно обновлены
404 unknown user account,
unknown secondary domain name
Нет пользователя с таким именем,
Некорректное имя домена
500   Внутренняя ошибка сервера
504 Invalid preference Неправильный параметр запроса
504 can't modify telnum Нельзя изменить telnum

Пример:

для удаления номера из списка необходимо отправить запрос, содержащий идентификатор номера uid и пустое значение number:

вызов вернет в случае неуспеха:

если номер с таким идентификатором uid уже есть в списке пользовательских номеров, то его параметры будут изменены. При этом остальные номера в списке останутся без изменений.

вызов вернет в случае успеха:

2.6.8.Изменение настройки домена

Сигнатура:

Результат:

Код ошибки Текст Описание
200 OK Домен обновлен
404 Not found Нет объекта с таким именем
500   Внутренняя ошибка сервера
504 Invalid preference Неправильное свойство учетной записи
517 Exhaust accounts limit Количество аккаунтов, созданных в домене, превышает задаваемый лимит

Пример:

вызов вернет в случае успеха:

2.6.9.Назначение телефонного номера домена

Сигнатура:

Результат:

Код ошибки Текст Описание
200 OK Учетная запись создана
404 Not found Нет объекта с таким именем
500   Внутренняя ошибка сервера
504 Invalid preference Неправильное свойство
515 Number exists Номер уже зарегистрирован за другим объектом
516 Number not found Номер не зарегистрирован за этим объектом, либо присваемого номера не существует

Пример:

вызов вернет в случае неуспеха:

2.6.10.Получение списка провайдеров

Вызов:

Результат:

Где gateway структура состоящая из id — идентификатор провайдера, direction — строка, которая характеризует возможность совершать входящие и исходящие звонки (in, out, both).

Пример:

Результат

2.6.11.Получение настроек учетной записи

Сигнатура:

name — имя пользователя в формате user@domain,

preference — массив имен настроек, которые необходимо получить.

Результат:

Код ошибки Текст Описание
200 preferences Массив объектов preference с параметрами:
name – имя настройки,
value – значение настройки
404 unknown user account,
unknown secondary domain name,
not found
Нет пользователя с таким именем,
некорректное имя домена,
объект не найден
500   Внутренняя ошибка сервера
504 Invalid preference Неправильное свойство учетной записи

Пример:

вызов вернет в случае хотя бы одного некорректного имени настройки:

вызов вернет в случае успеха:

2.6.12.Получение списка пользовательских голосовых правил Gravitsappa:

Сигнатура:

name — имя пользовотеля в формате user@domain

Результат:

Код ошибки Текст Описание
200 voicerules Массив объектов voicerule с параметрами:
uid – идентификатор,
delay – задержка,
idPhone – uid телефона, на который назначена переадресация,
days – объект или массив дней недели: Mon, Tue, Wed, Thu, Fri, Sat, Sun или always,
timeStart – время начала,
timeEnd – время окончания,
active – активно/неактивно
201 empty list Пустой список голосовых правил
404 unknown user account,
unknown secondary domain name
Нет пользователя с таким именем,
некорректное имя домена
500   Внутренняя ошибка сервера
504 Invalid preference Неправильный параметр запроса

Пример:

вызов вернет в случае неуспеха:

вызов вернет в случае успеха:

2.6.13.Изменение пользовательских голосовых правил Gravitsappa

Сигнатура:

name — имя пользователя в формате user@domain,
voicerule — массив объектов класса VoiceRule, содержащего следующие поля:
String uid – уникальный id правила,
int delay – время задержки перед срабатыванием правила, секунд,
String idPhone – uid телефона из MyPhones, на который назначена переадресация,
String[] days – массив дней недели, в которые должно срабатывать правило Mon, Tue, Wed, Thu, Fri, Sat, Sun, always - правило действует во все дни недели,
String timeStart – время начала действия правила ("10:00"),
String timeEnd – время окончания действия правила ("19:00"),
если не заданы, правило действует круглые сутки,
boolean active – активно/неактивно

Результат:

Код ошибки Текст Описание
200 OK Голосовые правила успешно обновлены
404 unknown user account,
unknown secondary domain name
Нет пользователя с таким именем,
Некорректное имя домена
500   Внутренняя ошибка сервера
504 Invalid preference Неправильный параметр запроса

Пример:

для удаления голосового правила из списка необходимо отправить запрос, содержащий идентификатор правила uid и пустое значение idPhone:

вызов вернет в случае неуспеха:

если правило с таким идентификатором uid уже есть в списке пользовательских голосовых правил, то его параметры будут изменены. При этом остальные правила в списке останутся без изменений.

вызов вернет в случае успеха:

для включения/отключения голосового правила необходимо отправить запрос, содержащий только идентификатор правила uid, идентификатор телефона idPhone и состояние правила active:

При этом будет обновлено только состояние правила, а также идентификатор телефона. Остальные параметры останутся без изменений. Вызов вернет аналогичный предыдущим вариантам XML-ответ.

2.6.14.Получение списка классов обслуживания в административном домене

Сигнатура:

Результат:

Код ошибки Текст Описание
200 serviceclass Один или несколько объектов с параметрами:
name – название класса обслуживания,
service – объект или массив сервисов
201 empty list Пустой список сервисов
404 Not found Домен не найден
500   Внутренняя ошибка сервера
504 Invalid preference Неправильный параметр запроса

Пример:

вызов вернет в случае успеха:

2.6.15.Изменение класса обслуживания в административном домене

Сигнатура:

name — название класса обслуживания,
services — массив сервисов

Результат:

Код ошибки Текст Описание
200 OK Класс обслуживания сохранен
404 Not found Класс обслуживания не найден
500   Внутренняя ошибка сервера
504 Invalid preference Неправильный параметр запроса

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

вызов вернет в случае успеха:

Для удаления класса обслуживания, необходимо передать в запросе только его название:

2.6.16.Получение списка доменов

Сигнатура:

Результат:

Код ошибки Текст Описание
200 domain Один или несколько доменов
201 empty list Пустой список доменов
404 Not found Домен не найден
500   Внутренняя ошибка сервера
504 Invalid preference Неправильный параметр запроса

Пример:

вызов вернет в случае успеха:

2.6.17. Получение состояния доменной записи вызовов

Сигнатура:

domain — имя домена, для которого надо узнать состояние записи.

Результат:

Код ошибки Текст Описание
200 limit Лимит хранения записи в днях (0, 7, 31, 91, 181, 365);
0 - запись выключена
404 Not found Домен не найден
500   Внутренняя ошибка сервера

Пример:

вызов вернет в случае успеха:

2.6.18. Изменение настроек доменной записи вызовов

Сигнатура:

domain — имя домена, для которого надо включить/отключить запись,
limit — лимит хранения записи в днях (0, 7, 31, 91, 181, 365); 0 - отключение записи,
sendLink — email для отправки ссылки на файл (необязательный).

Результат:

Код ошибки Текст Описание
200 OK Настройки записи сохранены
404 Not found Домен
504 Invalid preference Неправильный параметр запроса
500   Внутренняя ошибка сервера

Пример включения доменной записи:

Пример отключения доменной записи:

вызов вернет в случае успеха:

2.7.Управление сессиями

2.7.1.Получение web-сессии для администрирования домена

Сигнатура:

domain — домен, для управления которым необходимо получить web-сессию.

uiname — имя административного интерфейса. Возможные значение: BCP и Admin. По умолчанию используется интерфейс BCP.

ip – адрес клиента, для которого создается сессия. В случае, если в домене выставлена опция Require Fixed Network Address, этот параметр является обязательным. В противном случае выданная сессия будет автоматически сброшена самим CGP.

proxyip - ip прокси, если клиент находится за прокси.

Результат:

Код ошибки Текст Описание
200 URI URI для перехода в административный интерфейс
404 Not found Нет объекта с таким именем
500   Внутренняя ошибка сервера
504 Invalid preference Неправильный параметр запроса

Пример:

вызов вернет в случае неуспеха:

вызов вернет в случае успеха:

2.7.2.Получение web-сессии пользователя

Сигнатура:

user – пользователь в формате user@domain для которого необходимо получить web-сессию,

uiname – имя интерфейса, для которого надо получить сессию. Возможные значения: Admin, BCP, SysAdmin, Webmail. По-умолчанию, используется Webmail.

ip – адрес клиента, для которого создается сессия. В случае, если в домене выставлена опция Require Fixed Network Address, этот параметр является обязательным. В противном случае выданная сессия будет автоматически сброшена самим CGP.

proxyip – ip прокси, если клиент находится за прокси.

Результат:

Код ошибки Текст Описание
200 Session info объект с параметрами:
sessionURI - URI для перехода в веб-интерфейс,
userRole – роль, назначенная пользователю в системе,
billingID – ID пользователя или домена во внешней биллинговой системе
404 Not found Нет объекта с таким именем
500   Внутренняя ошибка сервера
504 Invalid preference Неправильный параметр запроса
519 Unknown user account На сервере нет такого пользователя

Пример:

вызов вернет в случае неуспеха:

вызов вернет в случае успеха:

2.7.3.Авторизация пользователя

Сигнатура:

user — пользователь в формате user@domain для которого необходимо получить web-сессию,

password – пароль пользователя,

ip – адрес клиента, для которого создается сессия. В случае, если в домене выставлена опция Require Fixed Network Address, этот параметр является обязательным. В противном случае выданная сессия будет автоматически сброшена самим CGP.

proxyip - ip прокси, если клиент находится за прокси.

Результат:

Код ошибки Текст Описание
200 Session info объект с параметрами:
sessionURI - URI для перехода в веб-интерфейс,
userRole – роль, назначенная пользователю в системе,
billingID – ID пользователя или домена во внешней биллинговой системе
401 Unauthorized Не удалось авторизовать пользователя
404 Not found Нет объекта с таким именем
500   Внутренняя ошибка сервера
504 Invalid preference Неправильный параметр запроса
519 Unknown user account На сервере нет такого пользователя

Пример:

вызов вернет в случае неуспеха:

вызов вернет в случае успеха:

2.8.Получение информации об объектах

2.8.1.Получение информации об использованных ресурсах

Сигнатура:

name — имя домен или пользователя в формате user@domain.

Результат:

Код ошибки Текст Описание
200 Statistics объект с параметрами:
accounts – число аккаунтов в домене (только для домена),
maxAccounts – максимально разрешенное число аккаунтов в домене (только для домена),
mailUsed – объем дискового пространства, использованный для почты,
filesUsed – объем дискового пространства, использованный для файлов
404 Not found Нет объекта с таким именем
500   Внутренняя ошибка сервера
504 Invalid preference Неправильный параметр запроса

Пример:

вызов вернет в случае неуспеха:

вызов вернет в случае успеха:

2.8.2.Получение информации о записях голосовой почты

Сигнатура:

name — имя домен или пользователя в формате user@domain.

Результат:

Код ошибки Текст Описание
200 Files массив объектов с параметрами:
uid (необязательный) – oid сообщения,
isnew (необязательный) – непрочитанное/прочитанное сообщение,
name – имя файла,
uri – uri для доступа к файлу
201 empty list Пустой список сообщений
404 Not found Нет объекта с таким именем
500   Внутренняя ошибка сервера
504 Invalid preference Неправильный параметр запроса

Пример:

вызов вернет в случае неуспеха:

вызов вернет в случае успеха:

2.8.3.Получение информации о записях разговоров

Сигнатура:

name — имя домен или пользователя в формате user@domain.

Результат:

Код ошибки Текст Описание
200 Files массив объектов с параметрами:
uid (необязательный) – oid сообщения,
isnew (необязательный) – непрочитанное/прочитанное сообщение,
name – имя файла,
uri – uri для доступа к файлу
201 empty list Пустой список сообщений
404 Not found Нет объекта с таким именем
500   Внутренняя ошибка сервера
504 Invalid preference Неправильный параметр запроса

Пример:

вызов вернет в случае неуспеха:

вызов вернет в случае успеха:

2.8.4.Изменение статуса сообщения голосовой почты

Сигнатура:

name — имя пользовотеля в формате user@domain,
uid — oid сообщения,
isnew — непрочитанное/прочитанное сообщение,
rem (необязательный) — включение/отключение удаления сообщения

Результат:

Код ошибки Текст Описание
200 OK Номера успешно обновлены
404 unknown user account,
unknown secondary domain name, NOT_FOUND
Нет пользователя с таким именем,
Некорректное имя домена,
Сообщение не найдено
500   Внутренняя ошибка сервера
504 Invalid preference Неправильный параметр запроса

Пример:

для удаления сообщения из списка необходимо отправить запрос, содержащий идентификатор номера uid и значение rem равное true:

вызов вернет в случае неуспеха:

2.8.5.Изменение статуса записи разговора

Сигнатура:

name — имя пользовотеля в формате user@domain,
uid — oid сообщения,
isnew — непрочитанное/прочитанное сообщение,
rem (необязательный) — включение/отключение удаления сообщения

Результат:

Код ошибки Текст Описание
200 OK Номера успешно обновлены
404 unknown user account,
unknown secondary domain name, NOT_FOUND
Нет пользователя с таким именем,
Некорректное имя домена,
Сообщение не найдено
500   Внутренняя ошибка сервера
504 Invalid preference Неправильный параметр запроса

Пример:

для удаления записи из списка необходимо отправить запрос, содержащий идентификатор номера uid и значение rem равное true:

вызов вернет в случае неуспеха:

Labels:
None
Enter labels to add to this page:
Please wait 
Looking for a label? Just start typing.