3CX 配置 API

什么是配置 API？

3CX 版本20中引入的 3CX 配置 API（XAPI）提供了一个基于REST的接口，能够通过编程方式控制3CX电话系统中的几乎每一个配置方面，从而复制通常通过管理控制台访问的功能。该API基于OData标准和OpenAPI规范构建，使开发人员能够高效地集成、自动化和自定义3CX环境。

配置 API 的主要功能

  • 综合管理： 通过用于管理部门、用户、呼叫路由、系统分机和其他配置的端点，该 API 使用户能够以编程方式执行几乎所有管理操作。从检查部门是否存在到配置共享停泊，3CX 的几乎每个元素都可以通过代码进行管理。
  • 自动化： API 允许常见管理任务的自动化，例如创建部门、分配用户角色和管理分机。这减少了在管理控制台中手动干预的需要，从而节省了时间并最大限度地减少了出错的可能性。
  • 一体化： 该 API 有助于 3CX 电话系统与其他业务应用程序的无缝集成。您可以使用它来同步用户数据、管理部门以及配置呼叫路由，以确保3CX与外部服务之间的流畅互通。将 3CX 集成到更广泛的工作流程中可以增强沟通和生产力，而无需手动同步。
  • 可扩展性： 该 API 的设计考虑到了可扩展性，可随着组织的发展对配置进行高效管理，从而轻松扩展用户、部门和其他实体，而不会产生过多的管理开销。

配置 API 集成

从 3CX 网页客户端的管理控制台，转至 集成 > API:

  1. 按 添加 按钮创建新的客户端应用程序。
  2. 指定 客户ID （用于访问路由点的DN，授权时也需要该DN）。
  3. 如果使用配置范围，请检查 3CX 配置 API 访问 此应用程序的复选框。
  4. 指定服务主体的部门和角色，以获得适当的 API 访问级别。
  5. 成功创建新的 API 实例后，您将收到第三方应用程序的 API 密钥。该密钥只会显示一次，因此请务必保存以供将来使用。

就是这样！您已成功完成 PBX 配置。

请注意： 您必须拥有 3CX 企业版许可证才能使用 3CX 配置 API。

它是如何运作的

RESTful API

这 3CX配置API 是一个基于 OData 协议构建的 RESTful Web API，提供安全且多功能的端点来管理和配置 3CX 系统的几乎每个方面。该 API 反映了 3CX 管理控制台中可用的功能，支持对用户管理、部门设置、呼叫路由、系统分机等进行编程控制。所有端点均设计安全可靠，确保它们不会干扰核心 PBX 功能或损害系统稳定性。

有关更多详细信息，请参阅 3CX 配置 API 端点规范。

身份验证令牌

配置 API 支持两种类型的令牌以进行安全访问：

  • 多公司管理令牌： 启用完全访问权限来管理 3CX 系统中的所有部门和实体，适合多公司环境中的管理员。
  • 用户令牌： 授予仅限于用户分配的角色和部门权限的访问权限，提供对特定配置任务的受控访问。

JSON 和 OpenAPI

凭借其 OpenAPI 规范，3CX 配置 API 与各种开发工具（包括 Postman）兼容，可实现直接集成。该 API 接受 JSON 格式的请求和响应，使开发人员可以轻松处理和自动化配置任务。

认证流程

3CX 配置 API 支持通过两种类型的身份验证令牌进行安全访问： 多公司管理令牌 和 用户令牌。每种类型的令牌都提供不同的访问级别，从而可以灵活地管理 3CX 环境中不同角色和部门的权限。

令牌

  • 请在您的服务主体设置中指定部门和角色。将角色设置为“系统所有者“ 或者 ”系统管理员”将授予系统范围的权限。其他角色将拥有相应的权限。
  • 获取方式：
  • 使用 POST 请求调用 /connect/token 端点，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 分钟，之后需要刷新或重新获取。

使用访问令牌

获得访问令牌后，将其包含在 授权 作为不记名令牌的 API 请求标头：

Authorization: Bearer ACCESS_TOKEN

快速测试 - 验证令牌身份验证

要快速验证您的令牌是否有效以及 API 连接是否已正确建立，请使用“快速测试”端点：

  • 端点： GET /xapi/v1/Defs?$select=Id
  • 回复： 200 OK 响应确认有效身份验证，标头将包含 3CX 系统版本。

重要提示

  • 令牌过期： 所有访问令牌都会在一小时后过期。应用程序必须通过重新验证或刷新令牌来处理令牌过期，以保持连续连接。
  • 安全： 始终安全地处理令牌，并避免将它们暴露在客户端代码或不安全的存储位置中。

XAPI 应用示例

有关使用 PBX 配置 API 设置 XAPI 应用的详细步骤，请参阅 XAPI 教程 GitHub 仓库。该示例涵盖了基本功能和 API 调用的演示。

另请参阅

最后更新

本文档最后更新日期为 2024 年 11 月 11 日

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