1. 简介 YDMP 开放API向第三方开发者提供安全使用设备管理服务的入口。通过YDMP APIs，开发者可以使用 YDMP的设备管理，账号管理，配置管理等功能。 YDMP API是基于HTTP的类REST风格API（REST-like API）。类REST风格表示使用URI标记资源并且允许通过HTTP协议访问API。API依赖于HTTP的语义和方法。 为了保证使用YDMP API的安全性，传输协议统一使用HTTPS并且全部请求都需要进行身份认证。如果使用YDMP API时，没有携带正确的身份凭证信息，那么请求将直接被拒绝。更多关于YDMP身份认证的信息，将在身份认证中详细说明。 YDMP平台对API的调用频率进行限制，保证系统的稳定性。大多数端点的速率限制为每秒50个请求。这个速率限制是企业级别，对于每个支持YDMP API的企业，我们允许每秒50个请求。更多关于速率限制的信息，将在调用速率限制中详细说明。 2. 使用YDMP APIs YDMP APIs允许开发者访问和操作YDMP下的资源，包括但不限于：设备管理、账号管理、配置管理等操作。本章将叙述如何正确的调用YDMP API。 2.1 YDMP API Protocols：HTTPS Host：api.ydmp.yealink.com prefix：open/api Accepts：application/json Responds With：application/json 说明 Host 将根据YDMP服务部署而定，上述值仅为示例。 2.2 请求地址 所有的 API 请求都必须通过 HTTPS 发出。请求的基础 URL 格式为：{{Protocols}}://{{Host}}/{{prefix}} + 具体API请求地址。例如，查询设备详情API的请求地址为： https://api.ydmp.yealink.com/open/api/v2/dm/devices/{deviceId} 3. 身份认证 对YDMP API发出的每个HTTP请求都必须经过身份认证。此操作是为了保证访问服务的客户端是否为系统已登记的用户。在身份认证的过程中，使用OAuth2.0协议。 在调用API之前，您需要从YDMP平台中获得Client ID与Client Secret，用于申请访问token。一个企业只能申请一组Client ID 与Client Secret。 3.1 流程说明 用户申请访问token和发起请求的流程如下： 第三方应用服务器向YDMP API服务器发起申请访问 token 请求并且携带Client ID和Client Secret。 YDMP API服务器验证Client ID和Client Secret信息是否正确。 验证成功后返回访问token。 第三方应用服务器发起业务请求，并且携带访问token。 Yealink API服务器验证是否存在访问token，然后验证访问token的有效性。 转发请求给Yealink业务服务器。 Yealink业务服务器将处理后的结果返回给Yealink API服务器。 YDMP API服务器将响应结果透传给第三方应用服务器。 说明 如果访问token失效，还需要提供相应的代码重新向服务器获取token。 3.2 申请访问token 请求方法 POST 请求地址 /v2/token 请求参数 参数 参数类型 数据类型 是否必须 描述 Authorization Header String 是 Basic base64Encode(client_id:client_secret)， 以冒号连接Client ID和Client Secret，然后进行 Base64编码。 timestamp Header String 是 时间戳，从1970年1月1日0点0分0秒开始到现在的毫秒数。 nonce Header String 是 随机数，最大长度32位。 grant_type Body String 是 client_credentials。 HTTP状态码 返回值 描述 200 操作成功，详见下方响应参数。 400 客户端传参异常，详见下方异常响应参数。 401 鉴权失败，详见下方异常响应参数。 500 服务端异常，详见下方异常响应参数。 响应参数 参数 数据类型 描述 access_token String 访问令牌。 token_type String bearer。 expires_in Long 访问令牌有效时间，单位为秒。 异常响应参数 参数 数据类型 描述 error String 根据OAuth2协议定义提供。表示一个错误代码字符串，可以用于对错误 进行分类，并对错误进行处理。 code String 服务端定义的错误码，用于快速定位问题。 requestId String 服务端生成的请求ID，用于在服务端跟踪请求执行情况。能够帮助开发 人员快速定位问题。 message String 简单明了的错误描述，能够被终端用户所理解。 请求消息示例 POST /v2/token HTTP/1.1 Content-Type: application/json Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW ​ { "grant_type": "client_credentials" } 响应参数示例 HTTP/1.1 200 OK Content-Type: application/json;charset=UTF-8 Cache-Control: no-store Pragma: no-cache ​ { "access_token": "[JWT TOKEN]", "token_type": "bearer", "expires_in": 86400 } 异常响应参数 HTTP/1.1 400 Bad Request Content-Type: application/json;charset=UTF-8 Cache-Control: no-store Pragma: no-cache ​ { "error": "invalid_request", "code": "70011", "requestId": "255d1aef", "message": "The provided value for the input parameter 'grant_type' is not valid." } 3.3 发起业务请求 所有的API请求都必须通过HTTPS发出。请求的基础URL是 https://api.ydmp.yealink.com/open/api 。完整的URL 根据操作的资源不同而定。每次请求API时，均需提供 3 个 HTTP Request Header，具体如下： 名称 数据类型 描述 Authorization String 鉴权信息，格式为： Bearer \[ACCESS TOKEN\]。 timestamp String 时间戳，从1970年1月1日0点0分0秒开始到现在的毫秒数。 nonce String 随机数，最大长度32位。 HTTP请求头部示例 Authorization: Bearer \[ACCESS TOKEN\] timestamp: 1568693976264 nonce: 097e0ac619ba41f68f16f1955787feb9 4. 错误定义 Yealink API使用HTTP状态码来反映请求操作成功或失败。2XX状态码表示操作成功，4XX或5XX状态码表示操作错误。如果收到错误的状态码，可以根据响应报文体中错误码和错误信息了解错误原因。 状态码 描述 场景举例 2XX 操作成功 / 400 请求数据错误。 无效的或不完整的请求数据。 401 身份认证错误。 请求没有携带访问token。 403 不允许访问某些资源。 鉴权不通过。 404 没有找到和请求相匹配的数据。 没有找到数据。 429 请求次数超过频率限制。 请求太频繁。 500 服务器错误。 服务器内部异常。 4.1 错误对象定义 错误（Error）对象 名称 数据类型 描述 code String 服务端定义的错误码，用于快速定位问题。 requestId String 服务端生成的请求ID，用于在服务端跟踪请求执行情况。能够帮助开发人员快速定位问题。 message String 简单明了的错误描述，能够被终端用户所理解。 details ErrorDetail[] 导致错误的详细信息列表，可能为空。 错误明细（ErrorDetail）对象 名称 数据类型 描述 field String 出现错误的请求参数名称。 message String 简单明了的错误描述，能够被终端用户所理解。 错误响应示例 { "code": "{errorCode}", "requestId": "{requestId}", "message": "Validation Failed", "details": [ { "field": "email", "message": "Invalid field" }, { "field": "type", "message": "Invalid field" } ] } 业务码 说明 英文说明 900200 操作成功。 Operate Successfully. 900400 请求参数不正确。 Request parameters are incorrect. 900401 用户未登录或登录已失效，请重新登录。 User is not logged in or the account has expired, please log in again. 900403 该请求被禁止。 This request is forbidden. 900404 请求的资源无法找到。 Requested resource is not found. 900408 请求超时，请稍候重试。 Time out, please try again. 900409 请求冲突。 Request conflict. 900412 并发编辑错误。 Concurrent editing error. 900429 请求过多。 Too Many Requests. 900440 会话过期。 Login Time-out. 900500 服务器繁忙，请稍候重试。 The server is busy, please try again later. 900501 不支持该操作。 Not Implemented. 900502 作为网关或者代理工作的服务器尝试执行请 求时，从上游服务器接收到无效的响应。 Bad Gateway. 900503 服务不可用。 Service Unavailable. 900504 上游服务器无响应。 Gateway Timeout. 900511 服务器内部错误。 Server Internal Error. 900599 未知错误。 unknown mistake. 900400 参数不能为空。 Cannot be null. 900400 参数不能为空。 Can not be empty. 900400 参数长度不正确。 Incorrect length. 900400 ID不能为空。 ID cannot be empty. 900400 资源不存在。 The resource does not exist or has been deleted. 800001 Mac不合法。 Invalid MAC. 800002 SN不合法。 SN is invalid. 800003 资源已存在。 Resource already exists. 800004 设备被其他企业添加。 MAC has been added by another enterprise/organization. 800005 设备类型非法。 Device Type is invalid. 800006 批量添加的设备数量超过限制。 The number of added devices exceeds the limit. 800007 参数不合法。 Incorrect parameter format. 800008 数据超过限制。 Data exceeds limit. 800130 账号已经存在。 Account already exists. 800200 鉴权用户名和密码必须成对出现。 Username and password must appear in pairs. 5. 调用速率限制 为了保持YDMP API平台的可靠性，我们的API有以下速率限制。除非有另外说明，否则普通API的速率限制为50个请求/秒。请控制好您的应用程序调用频率，不要超过访问速率的限制，否则将收到429的状态响应。YDMP API的调用方应使用指数退避算法重试 429 错误，并且以最少 30 秒的延迟重试。