API конфигурации 3CX

Для чего нужен API конфигурации?

API конфигурации 3CX (XAPI) в 3CX V20 предлагает REST-интерфейс, обеспечивающий программный контроль практически над каждым элементом конфигурации в системе 3CX. API дублирует возможности, обычно доступные через консоль администратора. API основан на стандартах OData и спецификациях OpenAPI, и позволяет разработчикам эффективно интегрировать, автоматизировать и настраивать 3CX.

Ключевые особенности API конфигурации

  • Комплексное управление: Благодаря управлению конечными точками, отделами, пользователями, маршрутизацией вызовов, системными номерами и другими параметрами, API позволяет выполнять практически все административные действия программно. От проверки существования отдела до настройки общих парковочных слотов - каждый элемент 3CX можно контролировать в коде.
  • Автоматизация: API позволяет автоматизировать общие административные задачи, такие как создание отделов, назначение ролей пользователям и управление добавочными номерами. Это сокращает ручное вмешательство, экономя время и минимизируя вероятность ошибок.
  • Интеграция: API обеспечивает бесшовную интеграцию 3CX с другими бизнес-приложениями. Доступна синхронизация пользовательских данных, управление отделами и настройка маршрутизации вызовов. Обеспечивается взаимодействие между 3CX и внешними сервисами. Интеграция 3CX в рабочие процессы бизнеса повышает связность и производительность - без ручной синхронизации.
  • Масштабируемость: Разработанный с учетом масштабируемости API обеспечивает эффективное управление конфигурацией по мере роста организации. Легко расширяйте количество пользователей, отделов и других объектов без дополнительных расходов.

Настройка интеграции по API

В консоли администратора веб-клиента 3CX перейдите в раздел Integrations > API:

  1. Нажмите кнопку Add, чтобы создать новое клиентское приложение.
  2. Укажите Client ID (номер для доступа к точке маршрутизации, который также необходим для авторизации).
  3. При использовании области конфигурации установите флажок 3CX Configuration API Access for this application.
  4. Укажите отдел и роль Service Principal для соответствующего уровня доступа к API.
  5. После успешного создания нового экземпляра API появится ключ API для сторонних приложений. Этот ключ будет показан только один раз, поэтому обязательно сохраните его для дальнейшего использования.

Вы успешно завершили настройку API!

Обратите внимание! Для использования 3CX Configuration API у вас должна быть лицензия 3CX AI 8ОВ+.

Как работает API

RESTful API

API конфигурации 3CX - это RESTful веб-API, основанный на протоколе OData, предлагающий безопасные и универсальные конечные точки для управления и настройки практически всех аспектов системы. API отражает функциональность, доступную в консоли администратора 3CX и обеспечивает программный контроль над пользователями, настройкой отделов, маршрутизацией вызовов, системными добавочными номерами и другими параметрами. Все конечные точки разработаны безопасными и надежными, и не будут мешать основным функциям АТС или влиять на стабильность системы.

Подробнее в документе 3CX Configuration API Endpoint Specification.

Токены аутентификации

API конфигурации поддерживает два типа токенов для безопасного доступа:

  • Токены администратора в мультитенантном режиме: Обеспечивают полный доступ для управления всеми отделами и объектами в 3CX. Подходят для администраторов в средах с несколькими компаниями.
  • Пользовательские токены: Предоставляют доступ, ограниченный назначенными пользователю ролями и разрешениями отдела. Обеспечивают контролируемый доступ к определенным задачам конфигурации.

JSON и OpenAPI

Благодаря спецификации OpenAPI, API 3CX совместим с различными инструментами разработки, включая Postman. API принимает запросы и ответы в формате JSON, упрощая автоматизацию настройки системы.

Аутентификация

API конфигурации 3CX поддерживает безопасный доступ через два типа токенов аутентификации: токены администратора в режиме мультикомпании и токены пользователя. Каждый тип токена предоставляет разные уровни доступа. API обеспечивает гибкость управления разрешениями для различных ролей и отделов 3CX.

Токены

  • Укажите Отдел и Роль в настройках Service Principal. Установка роли "System Owner" или "System Admin" предоставит права на всю систему. Другие роли будут иметь соответствующие права.
  • Как получить:
  • Вызовите конечную точку /connect/token с помощью POST-запроса с типом MIME application/x-www-form-urlencoded.

Тело запроса должно содержать:

client_id=[client_id_of_your_service_principal]

client_secret=[api_key_of_of_your_service_principal]

grant_type=client_credentials

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

  • Срок действия токена: Токен действителен в течение 60 минут, после чего его необходимо обновить или получить заново.

Использование токенов доступа

После получения токена включите его в заголовок Authorization ваших запросов API как токен Bearer:

Authorization: Bearer ACCESS_TOKEN

Тест аутентификации токена

Чтобы убедиться, что ваш токен действителен и соединение по API установлено, используйте конечную точку "Quick Test":

  • Endpoint: GET /xapi/v1/Defs?$select=Id
  • Response: Ответ 200 OK подтверждает действительную аутентификацию, а заголовки будут содержать версию системы 3CX.

Важные замечания

  • Срок действия токена: Все токены доступа истекают через час. Приложения должны обрабатывать истечение срока действия токена либо путем повторной аутентификации, либо путем обновления токена, чтобы поддерживать непрерывное соединение.
  • Безопасность: Всегда обращайтесь с токенами безопасно и избегайте их раскрытия в коде на стороне клиента или в незащищенных местах хранения.

Пример приложения XAPI

Подробные шаги по настройке приложения XAPI с помощью API конфигурации см. в репозитории XAPI Tutorial Github. Пример охватывает основные функции и вызовы API.

Дополнительная информация

Версия документа

Последнее обновление документа 17 февраля 2026

https://www.3cx.ru/docs/configuration-rest-api/