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

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

Все запросы выполняются по протоколу HTTPS.

Соглашения, используемые в описании:

Домен и АТС — это одно и то же: выделенная виртуальная АТС.
Обязательные поля помечаются символом * в имени.
Модели всех объектов содержат числовое поле ID.
В примерах используются переменные вида {{ Переменная }}.

Используемые переменные:

Переменная	Описание
v2_host	Адрес личного кабинета платформы
username	Логин пользователя
password	Пароль пользователя
auth_token	Ключ, полученный в результате выполнения Авторизация

Пользователи операторского типа могут работать с объектами и методами клиентов. При этом в запросах необходимо передавать domain_id.

Пример получения списка номеров домена, если авторизация выполнена учётной записью оператора платформы:

POST http://{{v2_host}}/api/
Content-Type: application/json
Authorization: Bearer {{auth_token}}

{
  "action": "list",
  "obj": "DomainUser",
  "action_id": "123",
  "params": {
    "domain_id": 3
  }
}

Как правило, для всех объектов доступен следующий набор методов:

Действие	Описание
list	Получение списка объектов.
get	Получение объекта.
append	Добавление объекта.
update	Обновление объекта.
delete	Удаление объекта.

Дополнительно доступны действия select (выбор объектов по фильтру), list_with_detail и select_with_detail (то же, но с детализацией), get_column_uniq_values (уникальные значения столбца).

Для объекта User доступны также auth, logout, check_auth и 2fa. При работе через WebSocket — subscribe, unsubscribe, stop, pong, set_domain.

При выполнении запросов к API выполняется проверка на наличие токена, наличие прав на работу с объектом, корректность заполненных данных и связанность объектов.

Коды ошибок:

msg_id	Описание
100	Нетипизированная ошибка, описание в поле text.
10000	Не найдено поле domain_id для поиска домена. Возникает только в объектах Домена.
10001	Не удалось найти домен по его id.
10002	Не удалось найти объект по указанным параметрам. Параметры в поле filter.
10003	Ошибка проверки уникальности. fields и values содержат значения для проверки.
10004	Запрашиваемое действие не доступно для объекта.
10005	Ошибка в значении поля. Коды ошибок.
10006	Ошибка связанности объектов. К примеру запрашивают объект из чужого Домена.
10007	Ошибка связанности объектов на уровне базы данных.
10008	Ошибка конвертации аудиофайла.
10009	Ошибка выполнения действия над объектом, связанная с его содержимым.
10010	Параметры запроса конфликтуют с другими данными.
10011	Ошибка действий над выключенным объектом.
10012	Ошибка ограничения количества объектов.
10013	Ошибка параметров элементов диалплана.
10014	Ошибка данных, передаваемых в диалплане.
10015	Ошибка, связанная с тарифными ограничениями.
10016	Ошибка, связанная с ограничениями лицензии на платформу.
10017	Нельзя понизить тариф: домен использует возможности более высокого уровня.
10018	Ошибка тестирования интеграций
10019	Подключение тарифной опции (расширения), которой нет в текущем тарифе.
10020	Запрещено изменение домена (например, name или secret_token активного домена).
10021	Нет прав на выполнение действия.
10022	Требуется хотя бы один объект.
10023	Пользователь не состоит в участниках объекта.
10024	Объект заблокирован (например, диалог закрыт).
10025	Пароль не соответствует политике безопасности.
10026	Превышен допустимый размер файла.
10027	Действие выполнено вне разрешённого расписания.
10028	Действие запрещено.
10029	Действие временно заблокировано, повторите позже.
10030	Тест не пройден.
10031	Ошибка запроса к внешнему сервису.
10032	(зарезервировано, не используется)
10033	Объект заблокирован, действие невозможно.
10034	Администраторы не могут быть участниками объекта.
10035	Некорректный номер экстренной службы.
10036	Повторяющийся идентификатор поля (field_id).
10037	Требуется двухфакторная аутентификация.
10038	Неверный код двухфакторной аутентификации.
10039	Не указан получатель кода двухфакторной аутентификации.
10040	PBX-хост не готов к работе.
10041	Ошибка поднятия FIP на PBX-хосте.
10042	Запрос к несуществующей таблице базы данных.
10043	Нельзя удалить объект: на него ссылаются другие объекты.

Справочник кодов ошибок 10005:

msg_id	Описание
1	Значение должно быть из списка разрешенных.
2	Поле обязательное для заполнения.
3	Значение поля должно быть в формате UUID.
4	Слишком длинное значение строки.
5	Слишком короткое значение строки.
6	Строка не соответствует формату.
7	Формат данных не соответствует UTF-8.
8	Значение должно быть больше или равно установленного значения.
9	Значение должно быть меньше или равно установленного значения.
10	Некорректное значение хеша.
11	Значение не может быть хешем.
12	Не могу распарсить значение.
13	Данные не соответствуют формату URL.
14	Данные не соответствуют формату email.
15	Значение не является числом.
16	Необходимо более одного значения.
17	Не могу распарсить значение как список.
18	Поле нельзя изменить.
19	Значение не является строкой.
20	Значение не является логическим (boolean).
21	Значение не является словарём (dict).

Типы данных:

Тип	Описание
StringType	Строка произвольной длины.
IntType	Целое число.
DictType	Json формат вида {«Ключ»: «Значение», ….}.
ListType	Json формат вида [1, 2, 4, …].
EmailType	Строка соответствующая RFC 5322.
ModelType	Json формат, включающий модель объекта.
IPv4Type	Строка, содержащая IP-адрес RFC1918.
BooleanType	Логическое значение (true/false).
FloatType	Число с плавающей точкой.
DecimalType	Точное десятичное число.
UUIDType	Строка в формате UUID.
TimestampType	Метка времени (Unix timestamp).
PolyModelType	Один из нескольких типов моделей.
BaseType	Значение произвольного типа.

Статусы объектов:

ID	Описание
1	Объект включен.
0	Объект выключен.