请求结构

发起 API 请求的 URL 由不同参数拼凑而成，包括主机 URL、API 版本、访问 token、API 接口和请求参数。本文介绍了 API 请求的结构，包括请求方式和请求地址格式。

请求示例

重要：需注意，每个发送到 Yeastar P 系列软件版 API 的请求，其头域 (Headers) 中都需要携带 User Agent (UA) 信息，以便 PBX 能够识别你的应用并响应请求。例如：

User-Agent:
                OpenAPI

。

以下为编辑分机的请求示例。

POST /openapi/v1.0/extension/update?access_token=5SwyByhbSfsNlpI1v4GtHxEDmKsZwzjQ HTTP/1.1
Host: 192.168.5.150:8088
Content-Type: application/json
User-Agent: OpenAPI
{
    "id": 60,
    "presence_status":"off_work"
}

POST 表示请求方式。
openapi/v1.0 即 API 路径，表示 API 版本。
extension/update 表示要调用的编辑分机的 API 接口。
access_token=5SwyByhbSfsNlpI1v4GtHxEDmKsZwzjQ 为用于验证请求合法性的访问 token。
HTTP/1.1 为超文本传输协议。
Host 表示 Yeastar P 系列软件版的 IP 地址或域名。
Content-Type:application/json 表示请求内容格式。
id 和 presence_status 为编辑分机 API 接口的请求参数。

请求方式

Yeastar P 系列软件版 API 支持以下 HTTP 请求方式：

GET - 查询信息或执行删除操作。
POST - 添加对象或执行特定操作。

请求地址格式

API 请求地址统一格式如下所示：

{base_url}/{api_path}/{endpoint}?access_token={access_token}

注：获取访问令牌和刷新访问令牌无需带访问 token。

{base_url}

本文档中所有请求地址都带有以下基本地址：

https://{pbx_ip}:{https_port}

根据 PBX 的网页访问协议设置，填写 API 请求的 Base URL。

如果 PBX 网页访问协议为 HTTP，Base URL 的格式如下：
```
http://{pbx_ip}:{http_port}
```
如果 PBX 网页访问协议为 HTTPS，Base URL 的格式如下：
```
https://{pbx_ip}:{https_port}
```
如果你使用 Yeastar FQDN 进行远程 API 访问，Base URL 的格式如下：
```
https://{pbx_fqdn_domain}
```
注：要使用 Yeastar FQDN 进行远程 API 访问，你需要配置 API 远程访问功能。更多信息，请参见通过 Yeastar FQDN 远程访问 API。

{api_path}: API 的路径格式为 openapi/{version}；其中，{version} 为 API 版本号。; 在本文档中，使用的 API 版本为 v1.0，所有的 API 接口的路径都是 openapi/v1.0。

{endpoint}

Endpoint，也称作 “路径”，表示 API 请求地址的具体地址。

具体的 API 接口，请参见 API 接口 & 事件概览。

{access_token}

访问 token 为 API 接口的调用凭证。第三方应用在调用 PBX 的 API 接口之前，必须先获取访问令牌。之后所有的 API 请求，都需在 API URL 中带上访问 token，否则 API 接口调用会失败。

详细的 API 认证说明，请参见授权规则。