3CX 配置 API 端点规范

授权

端点：获取访问令牌

描述:
此端点实现身份验证，并为适当的角色授予access_token。

端点 URL:
POST https://{{PBX_FQDN}}/connect/token

HTTP方法:
POST

需要身份验证:
是的，基本身份验证

请求参数

请求主体: URL编码参数 application/x-www-form-urlencoded

client_id （必填，字符串）：固定值， server_principal_id.
client_secret （必填，字符串）：固定值，设置服务主体后授予的sercret_key。
grant_type （必填，字符串）：固定值，client_credentials.

响应

成功响应:

状态代码: 200 OK
内容格式: application/json
响应主体示例:

{
  "token_type": "Bearer",
  "expires_in": 60,
  "access_token": "ACCESS_TOKEN",
  "refresh_token": null
}

错误响应:

401 未经授权
内容格式: application/json
由于凭据无效，身份验证失败。
响应主体示例:

{
  "error": "unauthorized",
  "error_description": "The request requires valid user authentication."
}

提示

access_token的有效期为60分钟；到期后需要重新进行身份验证。

部门

端点：检查部门是否存在

描述:
该端点检查3CX系统中是否存在指定名称的部门。这对于在创建新部门之前验证唯一性很有用。

端点 URL:
GET https://{{PBX_FQDN}}/xapi/v1/Groups?$filter=Name eq '3CX Test'

HTTP方法:
GET

需要身份验证:
是的

请求参数

查询参数:

$filter（必需，字符串）：过滤结果以检查特定部门名称（例如， Name eq '3CX Test'）。

响应

成功响应 - 未找到部门:

状态代码: 200 OK
内容格式: application/json; charset=utf-8
响应主体示例：

{
    "@odata.context": "https://PBX_FQDN/xapi/v1/$metadata#Groups",
    "value": []
}

成功响应 - 已找到部门:

状态代码: 200 OK
内容格式: application/json; charset=utf-8
响应主体示例:

{
    "@odata.context": "https://PBX_FQDN/xapi/v1/$metadata#Groups",
    "value": [
        {
            "Name": "DEFAULT",
            "IsDefault": true,
            "HasMembers": true,
            "Number": "GRP0000",
            "Id": 28
        }
    ]
}

错误响应

404 未找到
指定名称的部门不存在。

提示
在尝试在 3CX 系统中创建新部门之前，使用此端点可确保部门名称是唯一的。

端点：创建部门

描述:
在 3CX 系统中创建一个具有指定配置的新部门，例如语言、时区以及用于管理呼叫服务选项的各种属性。

端点 URL:
POST https://{{PBX_FQDN}}/xapi/v1/Groups

HTTP方法:
POST

需要身份验证:
是的

请求参数

请求主体：带有部门配置的 JSON 对象。

{
    "AllowCallService": true,
    "Id": 0,
    "Language": "EN",
    "Name": "3CX Test",
    "PromptSet": "1e6ed594-af95-4bb4-af56-b957ac87d6d7",
    "Props": {
        "LiveChatMaxCount": 20,
        "PersonalContactsMaxCount": 500,
        "PromptsMaxCount": 10,
        "SystemNumberFrom": "300",
        "SystemNumberTo": "319",
        "TrunkNumberFrom": "340",
        "TrunkNumberTo": "345",
        "UserNumberFrom": "320",
        "UserNumberTo": "339"
    },
    "TimeZoneId": "51",
    "DisableCustomPrompt": true
}

响应

成功响应:

状态代码： 201 创建成功
内容格式: application/json; charset=utf-8
Location Header: ：提供新创建的部门的 URL。
响应主体示例:

{
    "@odata.context": "https://PBX_FQDN/xapi/v1/$metadata#Groups/$entity",
    "Name": "3CX Test",
    "Id": 35,
    "Language": "EN",
    "Props": {
        "LiveChatMaxCount": 20,
        "PersonalContactsMaxCount": 500,
        "PromptsMaxCount": 10
    },
    "TimeZoneId": "51"
}

错误响应

400 错误请求
内容格式: application/json
如果已存在同名部门。
响应示例:

{
    "error": {
        "message": "Name:\nWARNINGS.XAPI.DUPLICATE",
        "details": [
            {
                "target": "Name",
                "message": "WARNINGS.XAPI.DUPLICATE"
            }
        ]
    }
}

提示

使用此端点之前，请确保部门名称是唯一的。如果存在同名部门，请求将失败并返回 400 状态代码。

端点：检查 3CX 实时聊天 URL 是否存在

描述:
该端点检查 3CX 系统中是否存在指定的 3CX 实时聊天 URL（链接），确保每个部门的聊天设置使用唯一的 URL。

端点 URL:
GET https://{{PBX_FQDN}}/xapi/v1/WebsiteLinks?$filter=Link eq 'LiveChat123456'

HTTP方法:
GET

需要身份验证:
是的

请求参数

查询参数:

$filter（必需，字符串）：指定要检查的实时聊天 URL（例如，Link eq 'LiveChat123456'）。

响应

成功响应 - URL 存在:

状态代码: 200 OK
内容格式: application/json; charset=utf-8
响应主体示例:

{
    "@odata.context": "https://PBX_FQDN/xapi/v1/$metadata#WebsiteLinks",
    "value": [
        {
            "Id": 1,
            "Link": "LiveChat123456",
            "ChatEnabled": true,
            "CallsEnabled": true,
            "General": {
                "Greeting": "DesktopAndMobile",
                "Authentication": "Both"
            },
            "Advanced": {
                "EnableDirectCall": true,
                "CommunicationOptions": "PhoneAndChat"
            }
        }
    ]
}

成功响应 - 未找到 URL:

状态代码: 200 OK
内容格式: application/json; charset=utf-8
响应主体示例:

{
    "@odata.context": "https://PBX_FQDN/xapi/v1/$metadata#WebsiteLinks",
    "value": [ ]
}

错误响应

404 未找到
指示指定的实时聊天 URL 不存在。

提示
此端点可用于验证实时聊天 URL 是否已在使用中，从而防止重复并确保整个系统中的 URL 唯一。

端点：为部门创建 3CX 实时聊天 URL

描述:
此端点创建与特定部门关联的新 3CX 实时聊天 URL，允许配置聊天和呼叫选项、外观和交互设置。

端点 URL:
POST https://{{PBX_FQDN}}/xapi/v1/WebsiteLinks

HTTP方法:
POST

需要身份验证:
是的

请求参数

请求主体：包含聊天配置详细信息的 JSON 对象

{
    "Advanced": {
        "CallTitle": "",
        "CommunicationOptions": "PhoneAndChat",
        "EnableDirectCall": true,
        "IgnoreQueueOwnership": false
    },
    "CallsEnabled": true,
    "ChatEnabled": true,
    "DefaultRecord": true,
    "DN": {
        "Id": 28,
        "Name": "DEFAULT",
        "Number": "GRP0000",
        "Type": "Group"
    },
    "General": {
        "AllowSoundNotifications": true,
        "Authentication": "None",
        "DisableOfflineMessages": false,
        "Greeting": "DesktopAndMobile"
    },
    "Group": "GRP0000",
    "Link": "3cxtest",
    "Name": "",
    "Styling": {
        "Animation": "NoAnimation",
        "Minimized": true
    },
    "Translations": {
        "GreetingMessage": "",
        "StartChatButtonText": "",
        "UnavailableMessage": ""
    },
    "Website": ["https://my.website.com"]
}

响应

成功响应

状态代码： 201 创建成功
内容格式: application/json; charset=utf-8
Location Header:提供新创建的实时聊天的 URL。
响应主体示例:

{
    "@odata.context": "https://PBX_FQDN/xapi/v1/$metadata#WebsiteLinks/$entity",
    "Id": 2,
    "Group": "GRP0000",
    "Link": "3cxtest",
    "ChatEnabled": true,
    "CallsEnabled": true,
    "DefaultRecord": true
}

错误响应

400 错误请求
内容格式: application/json
表示指定的实时聊天 URL (关联) 已在使用中。
响应示例:

{
    "error": {
        "message": "Link:\nWARNINGS.XAPI.ALREADY_IN_USE",
        "details": [
            {
                "target": "Link",
                "message": "WARNINGS.XAPI.ALREADY_IN_USE"
            }
        ]
    }
}

提示
该端点允许对部门的实时聊天进行详细定制，包括视觉样式、消息翻译和交互设置。确保关联是唯一的，可以防止重复。

端点：配置部门呼叫路由

描述:
该终端为指定部门配置呼叫路由规则，允许在办公时间、休息时间、节假日和不在办公室期间进行不同的路由行为。

端点 URL:
PATCH https://{{PBX_FQDN}}/xapi/v1/Groups(123)

HTTP方法:
PATCH

需要身份验证:
是的

请求参数

请求主体：具有呼叫路由配置的 JSON 对象。

{
    "Id": 123,
    "BreakRoute": {
        "IsPromptEnabled": false,
        "Route": {
            "External": "",
            "Number": "101",
            "To": "VoiceMail"
        }
    },
    "OfficeRoute": {
        "IsPromptEnabled": false,
        "Route": {
            "External": "",
            "Number": "101",
            "To": "Extension"
        }
    },
    "OutOfOfficeRoute": {
        "IsPromptEnabled": false,
        "Route": {
            "External": "",
            "Number": "101",
            "To": "VoiceMail"
        }
    },
    "HolidaysRoute": {
        "IsPromptEnabled": false,
        "Route": {
            "External": "",
            "Number": "101",
            "To": "VoiceMail"
        }
    }
}

响应

成功响应

状态代码：204 无内容
内容格式： None

错误响应

404 未找到
表示未找到指定ID的部门。

响应示例:

{
    "error": "Department not found"
}

提示

通过该端点，可以根据指定部门的办公时间、节假日等不同场景，动态调整呼叫处理。确保部门ID正确，避免 404 未找到错误。

端点：删除部门

描述:
该终端通过部门ID将指定部门从3CX系统中删除。

端点 URL:
POST https://{{PBX_FQDN}}/xapi/v1/Groups/Pbx.DeleteCompanyById

HTTP方法:
POST

需要身份验证:
是的

请求参数

请求主体：带有要删除的部门 ID 的 JSON 对象。

{
    "id": 123
}

响应

成功响应

状态代码：204 无内容
内容格式： None

错误响应

404 未找到
表示指定ID的部门不存在。

响应示例:

{
    "error": "Department not found"
}

提示

在尝试删除之前，请确保部门 ID 正确，因为此操作一旦完成就无法撤消。

端点：部门更新

描述:
该端点允许更新现有部门的详细信息和属性，包括实时聊天、提示、系统号码、中继号码和用户号码的限制。

端点 URL:
PATCH https://{{PBX_FQDN}}/xapi/v1/Groups(123)

HTTP方法:
PATCH

需要身份验证:
是的

请求参数

请求主体：具有更新的部门属性的 JSON 对象。

{
    "Id": 123,
    "Name": "3CX Test1",
    "Props": {
        "LiveChatMaxCount": 20,
        "PersonalContactsMaxCount": 500,
        "PromptsMaxCount": 10,
        "SbcMaxCount": 20,
        "SystemNumberFrom": "300",
        "SystemNumberTo": "319",
        "TrunkNumberFrom": "340",
        "TrunkNumberTo": "345",
        "UserNumberFrom": "320",
        "UserNumberTo": "339"
    }
}

响应

成功响应

状态代码：204 无内容
内容格式： None

错误响应

404 未找到
表示指定ID的部门不存在。

响应示例:

{
    "error": "Department not found"
}

提示

使用此端点更新特定部门配置。确保部门ID正确，避免 404 未找到错误。

用户

端点：获取用户列表

描述:
此端点检索用户列表，包括其 ID、姓名、号码、电子邮件地址和组成员身份等详细信息。

端点 URL:
GET https://{{PBX_FQDN}}/xapi/v1/Users

HTTP方法:
GET

需要身份验证:
是的

请求参数

查询参数:

$top：限制返回的用户数量（默认设置为 100）。
$skip：指定分页时要跳过的记录数（默认设置为 0）。
$orderby：指定记录返回的顺序（在本例中按数字排序）。
$select：指定要检索的字段。这里的选项包括 ID, 名, 姓, 号码，和电子邮件地址。
$expand：扩展相关实体。在这里，展开了组以及他们相关的权利。

响应

成功响应

状态代码: 200 OK
内容格式: application/json
响应主体示例:

{
    "@odata.context": "https://PBX_FQDN/xapi/v1/$metadata#Users(Id,FirstName,LastName,Number,EmailAddress,Groups(Rights()))",
    "value": [
        {
            "FirstName": "FirstName12345",
            "LastName": "LastName",
            "EmailAddress": "[email protected]",
            "Number": "100",
            "Id": 29,
            "Groups": [
                {
                    "GroupId": 28,
                    "Number": "100",
                    "MemberName": "LastName, FirstName12345",
                    "Name": "DEFAULT",
                    "Type": "Extension",
                    "CanDelete": true,
                    "Id": 6,
                    "Rights": {
                        "RoleName": "system_owners"
                    }
                }
            ]
        },
        {
            "FirstName": "sysadmin",
            "LastName": "",
            "EmailAddress": "",
            "Number": "101",
            "Id": 32,
            "Groups": [
                {
                    "GroupId": 28,
                    "Number": "101",
                    "MemberName": "sysadmin",
                    "Name": "DEFAULT",
                    "Type": "Extension",
                    "CanDelete": true,
                    "Id": 12,
                    "Rights": {
                        "RoleName": "users"
                    }
                }
            ]
        }
    ]
}

错误响应

401 未经授权
内容格式： application/json
该请求需要有效的用户身份验证。

提示
此端点提供用户详细信息以及组成员资格和访问权限。确保根据需要处理大型列表的分页（$top和$skip）。

端点：检查 PBX 上是否存在具有相同电子邮件的用户

描述:
该端点检查 PBX 系统上是否存在具有指定电子邮件地址的现有用户。如果找到匹配项，它将检索基本的用户详细信息。

端点 URL:
GET https://{{PBX_FQDN}}/xapi/v1/Users

HTTP方法:
GET

需要身份验证:
是的

请求参数

查询参数:

$top=1：将搜索结果限制为第一个匹配项，确保找到时只返回一个结果。
$filter：按小写电子邮件地址过滤，例如， tolower(电子邮件地址) eq '[email protected]'。
$orderby：指定记录返回的顺序（按数字这里）。
$select：指定要检索的字段。这里的选项包括 ID, 名, 姓, 号码，和电子邮件地址。
$expand：扩展相关实体。在这里，展开了组以及他们相关的权利。

响应

成功响应

用户找到

状态代码: 200 OK
内容格式: application/json
响应主体示例:

{
    "@odata.context": "https://PBX_FQDN/xapi/v1/$metadata#Users(Id,FirstName,LastName,Number,EmailAddress,Groups(Rights()))",
    "value": [
        {
            "FirstName": "FirstName12345",
            "LastName": "LastName",
            "EmailAddress": "[email protected]",
            "Number": "100",
            "Id": 29,
            "Groups": [
                {
                    "GroupId": 28,
                    "Number": "100",
                    "MemberName": "LastName, FirstName12345",
                    "Name": "DEFAULT",
                    "Type": "Extension",
                    "CanDelete": true,
                    "Id": 6,
                    "Rights": {
                        "RoleName": "system_owners"
                    }
                }
            ]
        }
    ]
}

未找到用户

状态代码: 200 OK
内容格式: application/json
响应主体示例:

{
    "@odata.context": "https://PBX_FQDN/xapi/v1/$metadata#Users(Id,FirstName,LastName,Number,EmailAddress,Groups(Rights()))",
    "value": []
}

错误响应

401 未经授权
内容格式： application/json
该请求需要有效的用户身份验证。

提示
使用此端点验证 PBX 上是否已存在具有特定电子邮件的用户。确保电子邮件以小写形式提供，以便过滤器正常工作。

端点：创建用户

描述:
此端点允许在 PBX 系统上创建新用户，指定关键信息，例如姓名、电子邮件、密码和各种设置。

端点 URL:
POST https://{{PBX_FQDN}}/xapi/v1/Users

HTTP方法:
POST

需要身份验证:
是的

请求参数

主体参数（JSON）：

AccessPassword：用户的访问密码（例如， “QrzxYQwa5！”）。
EmailAddress：用户的电子邮件地址（例如， “[email protected]”）。
FirstName：用户的名字（例如“TestFirstName”）。
ID：用户ID，通常为新用户设置为0。
Language：首选语言（例如“EN”）。
LastName：用户的姓氏（例如“TestLastName”）。
Number：分机号或用户号码（例如， “211”）。
PromptSet：用户提示集的标识符，如 PBX 上所定义（例如， “1e6ed594-af95-4bb4-af56-b957ac87d6d7”）。
SendEmailMissedCalls：设定布尔值来确定是否通过电子邮件发送未接来电通知（例如，true）。
VMEmailOptions：指定语音邮件电子邮件通知，例如 "Notification"。
Require2FA：设定布尔值来要求双因素身份验证（例如，true）。

响应

成功回应

用户已创建

状态代码： 201 已创建
位置标题：包含新创建的用户资源的位置，例如， “https://PBX_FQDN:5001/xapi/v1/Users(38)”
响应主体示例:

{
    "@odata.context": "https://PBX_FQDN/xapi/v1/$metadata#Users/$entity",
    "Enable2FA": false,
    "Require2FA": true,
    "FirstName": "TestFirstName",
    "LastName": "TestLastName",
    "EmailAddress": "[email protected]",
    "Number": "211",
    "Id": 38,
    "Language": "EN",
    "SendEmailMissedCalls": true,
    "VMEmailOptions": "Notification",
    "PromptSet": "1e6ed594-af95-4bb4-af56-b957ac87d6d7"
}

错误响应

已使用号码

状态代码: 400 错误请求
内容格式: application/json
响应主体示例:

{
    "error": {
        "code": "",
        "message": "Number:\nWARNINGS.XAPI.ALREADY_IN_USE",
        "details": [
            {
                "code": "",
                "target": "Number",
                "message": "WARNINGS.XAPI.ALREADY_IN_USE"
            }
        ]
    }
}

提示

如果用户具有指定的分机号已经存在，请求将返回 400 错误请求错误表明该号码已被使用。

端点：为部门中的用户分配角色

描述:
此端点允许通过更新用户的组设置来为部门内的用户分配指定的角色。可以为部门内的角色设置不同的权限。

端点 URL:
PATCH https://{{PBX_FQDN}}/xapi/v1/Users({{UserId}})

HTTP方法:
PATCH

需要身份验证:
是的

请求参数

路径参数:

UserId：用户的唯一标识符（例如， 120）。

主体参数（JSON）：

团体：一组对象的数组，其中每个对象包含：

GroupId：用户被分配到的部门（组）ID（例如， 95）。
Rights：指定分配给该部门内用户的角色。 RoleName 的有效值包括：

“system_owners”
“system_admins”
“group_owners”
“managers”
“group_admins”
“receptionists”
“users”

Id：正在更新的用户的Id（应与URL中的 UserId 匹配）。

请求正文示例:

{
    "Groups": [
        {
            "GroupId": 95,
            "Rights": {
                "RoleName": "system_owners"
            }
        }
    ],
    "Id": 120
}

响应

成功回应

角色分配成功

状态代码：204 无内容
响应体：None（表示角色分配成功）

错误响应

常见的 HTTP 错误，例如 404 未找到如果指定的用户或部门不存在或 400 错误请求无效的角色分配或缺少参数。

提示

每个部门/组一次只能为每个用户分配一个角色。
确保路径中的 UserId 和正文中的 Id 匹配。

端点：创建用户友好的 URL（更新用户）

描述:
此端点更新用户的设置以启用聊天功能并设置用户友好的 URL（Click-to-Call ID）和 Web 会议友好名称。

端点 URL:
PATCH https://{{PBX_FQDN}}/xapi/v1/Users({{UserId}})

HTTP方法:
PATCH

需要身份验证:
是的

请求参数

路径参数:

UserId：用户的唯一标识符（例如， 123）。

主体参数（JSON）：

CallUsEnableChat：布尔值，用于为用户启用（true）或禁用（false）聊天。
ClickToCallId：Click-to-Call的用户友好标识符，通常用用户名格式化（例如“firstnamelastname2”）。
ID：用户的唯一 ID（必须与 URL中的 UserId 匹配）。
WebMeetingFriendlyName：Web会议的用户友好名称，通常与ClickToCallId匹配（例如“firstnamelastname2”）。

请求正文示例:

{
    "CallUsEnableChat": true,
    "ClickToCallId": "firstnamelastname2",
    "Id": 123,
    "WebMeetingFriendlyName": "firstnamelastname2"
}

响应

成功回应

更新成功

状态代码：204 无内容
响应体：None（表示更新成功）

错误响应

未找到用户

状态代码：404 未找到
响应体： None
描述：如果系统中不存在指定的用户ID，则返回。

提示

确保路径中的 UserId 和请求正文中的 Id 相同，以便正确处理请求。
此操作只允许更新特定字段；试图包含其他字段可能会导致错误。

端点：创建用户友好的 URL - 验证请求

描述:
此端点用于在分配用户友好 URL（友好名称）之前验证其可用性。它检查所选名称和关联的电话分机（配对）在 PBX 系统中是否可用且有效。

端点 URL:
POST https://{{PBX_FQDN}}/xapi/v1/WebsiteLinks/Pbx.ValidateLink

HTTP方法:
POST

需要身份验证:
是的

请求参数

主体参数（JSON）：

model：包含 URL 验证的详细信息。

FriendlyName：要验证的所需用户友好 URL 名称（例如， “test”）。
Pair：关联的分机号码（例如， “100”）。

请求正文示例:

{
    "model": {
        "FriendlyName": "test",
        "Pair": "100"
    }
}

响应

成功回应

验证成功

状态代码：204 无内容
响应体：None（表示该名称可用且有效）

错误响应

名称已在使用或配对无效

状态代码：根据故障原因，可能会出现各种错误代码。
响应体： None
描述：友好名称或与分机号码的配对可能已被使用或无效。

提示

此端点不会创建 URL，而仅检查其可用性。
验证成功（204 响应）后，您可以在后续步骤中继续创建 URL。

端点：批量删除用户

描述:
该端点用于通过在批量请求中指定用户ID来从PBX系统中删除多个用户。

端点 URL:
POST https://{{PBX_FQDN}}/xapi/v1/Users/Pbx.BatchDelete

HTTP方法:
POST

需要身份验证:
是的

请求参数

主体参数（JSON）：

Ids：要删除的用户 ID 数组。

例子： {“ID”：[37, 38]}

请求正文示例:

{
    "Ids": [
        37,
        38
    ]
}

响应

成功回应

用户已删除

状态代码: 200 OK
响应体：确认删除或任何遇到的错误的 JSON 对象。
响应示例:

{
    "@odata.context": "https://PBX_FQDN/xapi/v1/$metadata#Collection(Pbx.UserDeleteError)",
    "value": []
}

错误响应

未找到用户或其他错误

状态代码：取决于错误上下文
响应体：删除过程中遇到的任何问题的错误信息。

提示

如果没有遇到问题，响应中的值字段将是一个空数组，确认用户已成功删除。
如果有错误，将在值数组中列出，每个错误都指定了无法删除用户的详细信息。

系统扩展

端点：列出组成员

描述:
该端点检索指定组的详细信息，包括其成员。

端点 URL:
GET https://{{PBX_FQDN}}/xapi/v1/Groups({GroupId})?$expand=成员

HTTP方法:
GET

需要身份验证:
是的

路径参数

GroupId：要检索其成员详细信息的组的 ID。

查询参数

$expand=Members：扩展结果以包含成员详细信息。

示例请求 URL

https://{{PBX_FQDN}}/xapi/v1/Groups(95)?$expand=Members

响应

成功响应

状态代码: 200 OK
响应体：包含群组详细信息的 JSON 对象，包括成员信息。
响应示例:

{
    "@odata.context": "https://PBX_FQDN/xapi/v1/$metadata#Groups(Members())/$entity",
    "Name": "DEFAULT",
    "IsDefault": true,
    "HasMembers": true,
    "Members": [
        {
            "GroupId": 95,
            "Number": "101",
            "MemberName": "sysadmin",
            "Name": "DEFAULT",
            "Type": "Extension",
            "CanDelete": true,
            "Id": 56
        },
        {
            "GroupId": 95,
            "Number": "SP0",
            "MemberName": "Shared parking",
            "Name": "DEFAULT",
            "Type": "Parking",
            "CanDelete": true,
            "Id": 40
        }
    ]
}

提示

此端点展开组数据以显示成员列表，详细说明每个成员的ID、编号、类型和名称。
响应中还可能包含其他信息，如组路由配置和设置（例如，OfficeRoute、BreakRoute、OutOfOfficeRoute、HolidaysRoute）。

端点：获取默认组属性

描述:
此端点检索名为“DEFAULT”的组的属性，允许您查看该组的特定配置详细信息。

端点 URL:
GET https://{{PBX_FQDN}}/xapi/v1/Groups?$filter=Name eq 'DEFAULT'

HTTP方法:
GET

需要身份验证:
是的

查询参数

$filter=Name eq 'DEFAULT'：过滤结果以仅检索名称为“DEFAULT”的组。

示例请求 URL

https://{{PBX_FQDN}}/xapi/v1/Groups?$filter=Name eq 'DEFAULT'

响应

成功响应

状态代码: 200 OK
响应体：具有“DEFAULT”组属性的 JSON 对象。
响应示例:

{
    "@odata.context": "https://PBX_FQDN/xapi/v1/$metadata#Groups",
    "value": [
        {
            "Name": "DEFAULT",
            "IsDefault": true,
            "HasMembers": true,
            "AnswerAfter": 0,
            "AllowCallService": true,
            "PromptSet": "",
            "GloballyVisible": false,
            "Number": "GRP0000",
            "Id": 95,
            "Props": {
                "StartupLicense": "Pro",
                "LiveChatMaxCount": -1,
                "DectMaxCount": -1,
                "SbcMaxCount": -1,
                "PersonalContactsMaxCount": -1,
                "PromptsMaxCount": -1
            },
            "OfficeRoute": {
                "Prompt": "",
                "Route": {
                    "Number": "101",
                    "To": "Extension",
                    "Name": "sysadmin"
                }
            },
            "OutOfOfficeRoute": {
                "Prompt": "",
                "Route": {
                    "Number": "101",
                    "To": "VoiceMail",
                    "Name": "sysadmin"
                }
            },
            "BreakRoute": {
                "Prompt": "",
                "Route": {
                    "Number": "101",
                    "To": "VoiceMail",
                    "Name": "sysadmin"
                }
            },
            "HolidaysRoute": {
                "Prompt": "",
                "Route": {
                    "Number": "101",
                    "To": "VoiceMail",
                    "Name": "sysadmin"
                }
            }
        }
    ]
}

提示

响应包括各种呼叫路由的设置（例如，OfficeRoute、BreakRoute、OutOfOfficeRoute、HolidaysRoute）。
您可以在Props中查看限制和许可证详细信息，包括 LiveChatMaxCount 和 PromptsMaxCount 等功能的计数。

端点：创建共享停泊

描述:
此端点允许您创建共享停泊分机，并将其与多个组关联。

端点 URL:
POST https://{{PBX_FQDN}}/xapi/v1/Parkings

HTTP方法:
POST

需要身份验证:
是的

请求主体

Groups：指定停泊应关联的组的数组。每个条目包括：

GroupId：组的 ID（例如，“122”表示自定义组，“95”表示默认组）。

ID：设置为 0 以创建新的停泊入口。

请求正文示例

{
    "Groups": [
        {
            "GroupId": 122
        },
        {
            "GroupId": 95
        }
    ],
    "Id": 0
}

成功响应

状态代码： 201 已创建
响应体：确认共享停车入口已创建的 JSON 对象。
响应示例:

{
    "@odata.context": "https://PBX_FQDN/xapi/v1/$metadata#Parkings/$entity",
    "Number": "SP11",
    "Id": 126
}

提示

Location Header：包含访问新共享停泊对象的 URL。
共享停泊号码（例如“SP11”）和 ID 创建成功后提供。

端点：列出组成员（以检索共享停泊分机）

描述:
此端点检索指定组的成员，例如“DEFAULT”，包括组内的任何共享停车扩展。

端点 URL:
GET https://{{PBX_FQDN}}/xapi/v1/Groups(95)?$expand=Members

HTTP方法:
GET

需要身份验证:
是的

查询参数

$expand：设置为“成员”以在响应中包括组的成员。

请求示例

GET https://{{PBX_FQDN}}/xapi/v1/Groups(95)?$expand=Members

成功响应

状态代码: 200 OK
响应体：列出指定组的所有成员的 JSON 对象，包括共享停车扩展和其他成员的详细信息。

响应示例:

{
    "@odata.context": "https://PBX_FQDN/xapi/v1/$metadata#Groups(Members())/$entity",
    "Name": "DEFAULT",
    "Id": 95,
    "Members": [
        {
            "GroupId": 95,
            "Number": "SP11",
            "MemberName": "Shared parking",
            "Type": "Parking",
            "CanDelete": true,
            "Id": 59
        },
        {
            "GroupId": 95,
            "Number": "SP0",
            "MemberName": "Shared parking",
            "Type": "Parking",
            "CanDelete": true,
            "Id": 40
        },
        {
            "GroupId": 95,
            "Number": "101",
            "MemberName": "sysadmin",
            "Type": "Extension",
            "CanDelete": true,
            "Id": 56
        }
    ]
}

提示

使用此端点识别需要从组中删除的共享停泊 ID（例如“SP11”）。
每个共享停泊分机都包含属性“CanDelete”：true，表示如果需要，可以将其删除。

端点：通过号码获取停泊详细信息

描述:
此端点通过编号（如“SP11”）检索特定停泊的详细信息。此数据可用于在删除之前确认停泊 ID 和相关详细信息。

端点 URL:
GET https://{{PBX_FQDN}}/xapi/v1/Parkings/Pbx.GetByNumber(number='SP11')

HTTP方法:
GET

需要身份验证:
是的

请求示例

[multcode]

GET https://{{PBX_FQDN}}/xapi/v1/Parkings/Pbx.GetByNumber(number='SP11')

成功响应

状态代码: 200 OK
响应体：包含停车详细信息的 JSON 对象，包括停车号码和 ID。

响应示例:

{
    "@odata.context": "https://PBX_FQDN/xapi/v1/$metadata#Parkings/$entity",
    "Number": "SP11",
    "Id": 126
}

提示

此端点提供停泊的“Id”，这对于后续步骤中的删除至关重要。
确保在请求中使用正确的停泊号码，以避免意外删除。

端点：按 ID 删除共享停泊

描述:
该端点用于通过其唯一 ID 删除 3CX 系统中特定的共享停泊，例如 “126”。

端点 URL:
DELETE https://{{PBX_FQDN}}/xapi/v1/Parkings(126)

HTTP方法:
DELETE

需要身份验证:
是的

请求示例

DELETE https://{{PBX_FQDN}}/xapi/v1/Parkings(126)

预期回应

删除成功

状态代码：204 无内容
响应体： None

删除失败（找不到停泊号码）

状态代码：404 未找到
响应体：None
解释：该状态表示系统中不存在指定的停泊 ID 。

示例场景:

删除成功
指定停车ID， 126，存在且删除成功。
失败（未找到）
如果指定停泊 ID ，如 123，不存在，会返回404响应，表示未找到停车号码。

提示

删除前请验证停泊 ID ，以免发生错误。
删除是永久性的；在继续之前，确保不存在对共享停泊的主动依赖性。

端点：获取 3CX 版本

描述:
该端点主要用于验证身份验证是否成功以及通过查询基本端点来检索 3CX 版本。

端点 URL:
GET https://{{PBX_FQDN}}/xapi/v1/Defs?$select=Id

HTTP方法:
GET

需要身份验证:
是的

请求示例

GET https://{{PBX_FQDN}}/xapi/v1/Defs?$select=Id

预期响应

成功的身份验证和版本检索

状态代码: 200 OK
响应头:

X-3CX-Version：包含3CX系统的版本，例如， “20.0.3.6”

响应体:

{
  "@odata.context": "https://PBX_FQDN/xapi/v1/$metadata#Defs(Id)",
  "Id": 0
}

响应标头示例

X-3CX-Version：20.0.3.6 — 此标头指示当前使用的 3CX 版本。

示例场景:

成功回应
端点确认身份验证并在身份验证成功时检索版本信息。

提示

这 X-3CX-Version header 是直接从响应标头确认 3CX 版本的便捷方法。
该端点通常用作快速连接测试，验证对 3CX API 的成功访问。

最后更新

本文档最后更新于 2024 年 11 月 6 日

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

3CX 配置 API 端点规范

授权

端点：获取访问令牌

部门

端点：检查部门是否存在

端点：创建部门

端点：检查 3CX 实时聊天 URL 是否存在

端点：为部门创建 3CX 实时聊天 URL

端点：配置部门呼叫路由

端点：删除部门

端点：部门更新

用户

端点：获取用户列表

端点：检查 PBX 上是否存在具有相同电子邮件的用户

端点：创建用户

端点：为部门中的用户分配角色

端点：创建用户友好的 URL（更新用户）

端点：创建用户友好的 URL - 验证请求

端点：批量删除用户

系统扩展

端点：列出组成员

端点：获取默认组属性

端点：创建共享停泊

端点：列出组成员（以检索共享停泊分机）

端点：通过号码获取停泊详细信息

端点：按 ID 删除共享停泊

端点：获取 3CX 版本

开始您的30天免费试用

即将开放!

简介

解决方案

常用链接

更多信息