1. YMCS APIs 1.1 简介 YMCS 开放API向第三方开发者提供安全使用设备管理服务的入口。通过YMCS APIs，开发者可以使用YMCS的设备管理，账号管理，配置管理等功能。 YMCS API是基于HTTP的类REST风格API（REST-like API）。类REST风格表示使用URI标记资源并且允许通过HTTP协议访问API。API依赖于HTTP的语义和方法。 为了保证使用YMCS API的安全性，传输协议统一使用HTTPS并且全部请求都需要进行身份认证。如果使用YMCS API时，没有携带正确的身份凭证信息，那么请求将直接被拒绝。更多关于YMCS身份认证的信息，将在身份认证中详细说明。 YMCS平台对API的调用频率进行限制，保证系统的稳定性。大多数端点的速率限制为每秒50个请求。这个速率限制是企业级别，对于每个支持YMCS API的企业，我们允许每秒50个请求。更多关于速率限制的信息，将在调用速率限制中详细说明。 1.2 使用YMCS APIs YMCS APIs允许开发者访问和操作YMCS 下的资源，包括但不限于：设备管理，账号管理，配置管理等操作。本章将叙述如何正确的调用YMCS API。 YMCS API Version： 1.0.0 Host： api.ymcs.yealink.com Protocols： HTTPS Accepts： application/json Responds With： application/json 身份认证 对YMCS API发出的每个HTTP请求都必须经过身份认证。此操作是为了保证访问服务的客户端是否为系统已登记的用户。在身份认证的过程中，使用OAuth2.0协议。 在调用API之前，您需要从YMCS平台中获得Client ID 与 Client Secret，用于申请访问 token。一个企业只能申请一组Client ID 与Client Secret。 流程说明 用户申请访问 token 和发起请求的流程如下： 第三方应用服务器向YMCS API服务器发起申请访问 token 请求并且携带Client ID和Client Secret YMCS API服务器验证Client ID和Client Secret信息是否正确 验证成功后返回访问 token 第三方应用服务器发起业务请求，并且携带访问 token Yealink API服务器验证是否存在访问token，然后验证访问token的有效性。 转发请求给Yealink业务服务器 Yealink业务服务器将处理后的结果返回给Yealink API服务器 YMCS API服务器将响应结果透传给第三方应用服务器 如果访问 token 失效，还需要提供相应的代码重新向服务器获取 token。 申请访问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 简单明了的错误描述，能够被终端用户所理解 请求消息示例 httpPOST /v2/token HTTP/1.1 Content-Type: application/json Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW { "grant_type": "client_credentials" } 响应参数示例 httpHTTP/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 } 异常响应参数 httpHTTP/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." } 发起业务请求 所有的 API 请求都必须通过 HTTPS 发出。请求的基础 URL 是api.ymcs.ycloud.com。完整的 URL 根据操作的资源不同而定。 每次请求 API 时，均需提供 3 个 HTTP Request Header，具体如下： 名称 数据类型 描述 Authorization String 鉴权信息。格式为：Bearer [ACCESS TOKEN] timestamp String 时间戳，从 1970 年 1 月 1 日 0 点 0 分 0 秒开始到现在的毫秒数 nonce String 随机数，最大长度32位 HTTP请求头部示例 httpAuthorization: Bearer [ACCESS TOKEN] timestamp: 1568693976264 nonce: 097e0ac619ba41f68f16f1955787feb9 1.3 错误定义 Yealink API使用HTTP状态码来反映请求操作成功或失败。2XX状态码表示操作成功，4XX或5XX状态码表示操作错误。如果收到错误的状态码，可以根据响应报文体中错误码和错误信息了解错误原因。 状态码 描述 场景举例 2XX 操作成功 400 请求数据错误 无效的或不完整的请求数据 401 身份认证错误 请求没有携带访问 token 403 不允许访问某些资源 鉴权不通过 404 没有找到和请求相匹配的数据 没有找到数据 429 请求次数超过频率限制 请求太频繁 500 服务器错误 服务器内部异常 错误对象定义 错误（Error）对象 名称 数据类型 描述 code String 服务端定义的错误码，用于快速定位问题 requestId String 服务端生成的请求ID，用于在服务端跟踪请求执行情况。能够帮助开发人员快速定位问题 message String 简单明了的错误描述，能够被终端用户所理解 details ErrorDetail[] 导致错误的详细信息列表，可能为空 错误明细（ErrorDetail）对象 名称 数据类型 描述 field String 出现错误的请求参数名称 message String 简单明了的错误描述，能够被终端用户所理解 错误响应示例 json{ "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 1.4 调用速率限制 为了保持YMCS API平台的可靠性，我们的API有以下速率限制。 除非有另外说明，否则普通API的速率限制为50个请求/秒。请控制好您的应用程序调用频率，不要超过访问速率的限制，否则将收到429的状态响应。 YMCS API的调用方应使用指数退避算法重试 429 错误，并且以最少 30 秒的延迟重试。 2.设备管理 2.1 设备基础信息管理 2.1.1 添加设备 请求方法 POST 请求地址 /v2/dm/devices Body参数 参数 数据类型 是否必需 描述 mac String 是 设备MAC，最小长度12，最大长度17位 sn String 是 SN码，最大长度128 deviceType Integer 是 设备类型 1: Phone Device 3: Room Device modelId String 是 型号ID name String 否 设备名称，最大长度128 siteId String 否 站点ID HTTP状态码 返回值 描述 201 操作成功 400 客户端传参异常 401 鉴权失败 500 服务端异常 响应参数 参数 数据类型 描述 id String 设备id mac String 设备MAC sn String 分组id name String 设备名称 modelId String 型号ID siteId String 站点ID programVersion String 设备固件版本号 请求消息示例 httpPOST /v2/dm/devices HTTP/1.1 Host: api.ymcs.yealink.com Content-Type: application/json { "mac":"001565bbb1a9", "sn":"1106312113402006", "name":"my t54s", "deviceType":1 } 响应消息示例 httpHTTP/1.1 201 Created Content-Type: application/json;charset=UTF-8 { "id": "8d07a56207074d26b61026099625b9e2", "mac":"001565bbb1a9", "sn":"1106312113402006", "name":"my t54s", "modelId":"61e659e4d78d42ebada88ef1eb751b64", "siteId":"a624453e1cbb44ecb9bb6ee31731a856", "programVersion":"70.83.0.68" } 2.1.2 批量添加设备 每次最多100条 请求方法 POST 请求地址 /v2/dm/addDevices Body参数 参数 数据类型 是否必需 描述 mac String 是 设备MAC，最小长度12，最大长度17 sn String 是 SN码，最大长度128 deviceType Integer 是 设备类型 1: Phone Device 3: Room Device modelId String 是 型号ID name String 否 设备名称，最大长度128 siteId String 否 站点ID HTTP状态码 返回值 描述 200 操作成功 400 客户端传参异常 401 鉴权失败 500 服务端异常 响应参数 参数 数据类型 描述 total Integer 批量添加总条数 successCount Integer 成功添加总数量 failureCount Integer 失败总数量 errors AddError[] 错误信息 AddError对象 参数 数据类型 描述 mac String 设备MAC sn String 设备SN errorInfo String 错误信息 请求消息示例 httpPOST /v2/dm/addDevices HTTP/1.1 Host: api.ymcs.yealink.com Content-Type: application/json [{ "mac":"3a1565bbb1a9", "sn":"1106312113402006", "name":"my t54s", "modelId":"61e659e4d78d42ebada88ef1eb751b64", "deviceType":1 }] 响应消息示例 httpHTTP/1.1 200 OK Content-Type: application/json;charset=UTF-8 { "total": 1, "successCount":0, "failureCount":1, "errors":[{ "mac":"3a1565bbb1a9", "sn":"1106312113402006", "errorInfo":"device.mac.invalid" }] } 2.1.3 添加设备不带SN 每次最多100条 请求方法 POST 请求地址 /v2/dm/addDevicesByMac Body参数 参数 参数类型 数据类型 是否必需 描述 mac Body String 是 设备MAC，最小长度12，最大长度17 deviceType Body Integer 是 设备类型 1: Phone Device 3: Room Device modelId Body String 是 型号ID name Body String 否 设备名称，最大长度128 siteId Body String 否 站点ID HTTP状态码 返回值 描述 200 操作成功 400 客户端传参异常 401 鉴权失败 500 服务端异常 响应参数 参数 数据类型 描述 total Integer 批量添加总条数 successCount Integer 成功添加总数量 failureCount Integer 失败总数量 errors AddError[] 错误信息 AddError对象 参数 数据类型 描述 mac String 设备MAC sn String 设备SN errorInfo String 错误信息 请求消息示例 httpPOST /v2/dm/addDevicesByMac HTTP/1.1 Host: api.ymcs.yealink.com Content-Type: application/json [{ "mac":"3a1565bbb1a9", "name":"my t54s", "modelId":"61e659e4d78d42ebada88ef1eb751b64", "deviceType":1 }] 响应消息示例 httpHTTP/1.1 200 OK Content-Type: application/json;charset=UTF-8 { "total": 1, "successCount":0, "failureCount":1, "errors":[{ "mac":"3a1565bbb1a9", "sn":"1106312113402006", "errorInfo":"device.mac.invalid" }] } 2.1.4 删除设备 请求方法 DELETE 请求地址 /v2/dm/devices/{deviceId} PATH参数 参数 数据类型 是否必需 描述 deviceId String 是 设备id HTTP状态码 返回值 描述 204 操作成功 400 客户端传参异常 401 鉴权失败 500 服务端异常 请求消息示例 httpDELETE /v2/dm/devices/e33b8f25247e45de84dd4c74503b241a HTTP/1.1 Host: api.ymcs.yealink.com 响应消息示例 httpHTTP/1.1 204 2.1.5 批量删除设备 请求方法 POST 请求地址 /v2/dm/delDevices Body参数 参数 数据类型 是否必需 描述 deviceType Integer 是 设备类型 1: Phone Device 3：Room Device deviceIdType String 否 表示设备标识的类型，默认id，可选mac、id deviceIds String[] 是 设备标识，最大长度200 HTTP状态码 返回值 描述 200 操作成功 400 客户端传参异常 401 鉴权失败 500 服务端异常 响应参数 参数 数据类型 描述 total Integer 删除总条数 successCount Integer 成功删除总数量 failureCount Integer 失败总数量 errors OpError[] 错误信息 OpError对象 参数 数据类型 描述 field String 错误字段 msg String 错误信息 请求消息示例 httpPOST /v2/dm/delDevices HTTP/1.1 Host: api.ymcs.yealink.com Content-Type: application/json { "deviceType":1, "deviceIds":["001565bbb1a9","001567"], "deviceIdType":"mac" } 响应消息示例 httpHTTP/1.1 200 OK Content-Type: application/json;charset=UTF-8 { "total": 2, "successCount":1, "failureCount":1, "errors":[{ "field":"001567", "msg":"Invalid MAC" }] } 2.1.6 设备列表 请求方法 POST 请求地址 /v2/dm/listDevices Body参数 参数 数据类型 是否必需 描述 skip Long 否 跳过的记录数，默认为0 limit Long 否 获取的最大记录数，默认为10，最大100 autoCount Boolean 否 是否要响应总数量，建议在第一页查询时为true,后续翻页时传false filter Filter 否 搜索参数 Filter对象定义 参数 数据类型 是否必需 描述 mac String 否 设备MAC模糊搜索关键字,最大长度17,支持带:或-,如00:15:65:bb:b1:a9 modelId String 否 型号ID deviceStatus Integer 否 设备状态，1:在线， 0:离线，-1:未上报 accountStatus Integer 否 账号状态, 1: 已注册 2:dnd 3: 未注册 deviceType Integer 否 设备类型状态, 1: Phone Device 3: Room Device ，不填写时为全部 siteId String 否 站点ID HTTP状态码 返回值 描述 200 操作成功 400 客户端传参异常 401 鉴权失败 500 服务端异常 响应参数 参数 数据类型 描述 skip Long 偏移量 limit Long 返回最大数量 total Long 总数量 data Device[] Device信息数组 Device对象定义 参数 数据类型 描述 id String 设备id mac String 设备MAC sn String 设备SN name String 设备名称 modelId String 型号ID siteId String 站点ID programVersion String 设备固件版本号 deviceStatus String 设备状态，online:在线， offline:离线，pending:未上报 请求消息示例 httpPOST /v2/dm/listDevices HTTP/1.1 Host: api.ymcs.yealink.com Content-Type: application/json { "skip": 0, "limit": 20, "autoCount": true, "filter":{ "deviceStatus":1, "siteId":"a624453e1cbb44ecb9bb6ee31731a856" } } 响应消息示例 httpHTTP/1.1 200 Content-Type: application/json;charset=UTF-8 { "skip": 0, "limit": 10, "total": 1, "data":[{ "id": "8d07a56207074d26b61026099625b9e2", "mac":"001565bbb1a9", "sn":"1106312113402006", "name":"my t54s", "modelId":"61e659e4d78d42ebada88ef1eb751b64", "siteId":"a624453e1cbb44ecb9bb6ee31731a856", "programVersion":"70.83.0.68", "deviceStatus":"online" }] } 2.1.7 编辑设备 请求方法 PATCH 请求地址 /v2/dm/devices/{deviceId} Path参数 参数 数据类型 是否必需 描述 deviceId String 是 设备ID Body参数 参数 数据类型 是否必需 描述 name String 否 设备名称，最大长度128 siteId String 否 站点ID HTTP状态码 返回值 描述 204 操作成功 400 客户端传参异常 401 鉴权失败 500 服务端异常 请求消息示例 httpPATCH /v2/dm/devices/8d07a56207074d26b61026099625b9e2 HTTP/1.1 Host: api.ymcs.yealink.com Content-Type: application/json { "name":"my t54s2" } 响应消息示例 httpHTTP/1.1 204 2.1.8 设备详情 请求方法 GET 请求地址 /v2/dm/devices/{deviceId} Path参数 参数 数据类型 是否必需 描述 deviceId String 是 设备id HTTP状态码 返回值 描述 200 操作成功 400 客户端传参异常 401 鉴权失败 500 服务端异常 响应参数 参数 数据类型 描述 id String 设备id mac String 设备MAC sn String 分组id name String 设备名称 modelId String 型号ID modelName String 型号名称 siteId String 站点ID siteName String 站点名称 lanIp String 内网IP deviceStatus String 设备状态，online:在线， offline:离线，pending:未上报 programVersion String 固件版本 lastReportTime long 最后上报时间 accounts ReportAccount[] 上报的账号信息 ReportAccount对象定义 参数 数据类型 描述 accountId String 账号ID lineId Integer 账号线路,从1开始 accountType Integer 账号类型: 0：SIP,1:H323 2:SFB accountServer String 账号服务器地址 registerName String 注册名称 username String 用户名称 status Integer 账号状态:1:已注册 2:dnd 3:未注册4:未知 请求消息示例 httpGET /v2/dm/devices/8d07a56207074d26b61026099625b9e2 HTTP/1.1 Host: api.ymcs.yealink.com 响应消息示例 httpHTTP/1.1 200 Content-Type: application/json;charset=UTF-8 { "id": "8d07a56207074d26b61026099625b9e2", "mac":"001565bbb1a9", "sn":"1106312113402006", "name":"my t54s", "modelId":"61e659e4d78d42ebada88ef1eb751b64", "modelName":"SIP-T54S", "siteId":"a624453e1cbb44ecb9bb6ee31731a856", "siteName":"mysite", "lanIp":"10.50.198.6", "deviceStatus":"online", "programVersion":"70.83.0.68", "lastReportTime":1711093807136, "accounts":[{ "accountId":"604e67944c7c43fe8b66099254ec3439" "lineId":1, "accountType":0, "accountServer":"10.200.108.48", "registerName":"1000", "username":"1000", "status":0 },{ "accountId":"a45a6b4a7e0447b8a6c3f2839d902acd" "lineId":2, "accountType":0, "accountServer":"10.200.108.48", "registerName":"2000", "username":"2000", "status":0 }] } 2.1.9 设备组合配置查询 请求方法 GET 请求地址 /v2/dm/devices/{deviceId}/configs Path参数 参数 数据类型 是否必需 描述 deviceId String 是 设备id HTTP状态码 返回值 描述 200 操作成功 400 客户端传参异常 401 鉴权失败 500 服务端异常 响应参数 参数 数据类型 描述 deviceConfig String 设备MAC配置 siteConfig String 设备站点配置 globalConfig String 企业全局配置 enforceConfig String 站点强制继承配置 请求消息示例 httpGET /v2/dm/devices/8d07a56207074d26b61026099625b9e2/configs HTTP/1.1 Host: api.ymcs.yealink.com 响应消息示例 httpHTTP/1.1 200 Content-Type: application/json;charset=UTF-8 { "deviceConfig": "account.1.auth_name = test1101", "siteConfig":"lang.gui=English", "globalConfig":"auto_provision.server.url=\r\nlang.gui=English", "enforceConfig":"security.user_password=user2" } 2.2 设备分组管理 2.2.1 添加分组 请求方法 POST 请求地址 /v2/dm/deviceGroups Body参数 参数 数据类型 是否必需 描述 name String 是 分组名称，长度64 deviceType Integer 是 设备类型 1: Phone Device 3: Room Device description String 否 分组描述信息,长度256 HTTP状态码 返回值 描述 201 操作成功 400 客户端传参异常 401 鉴权失败 500 服务端异常 响应参数 参数 数据类型 描述 id String 分组id name String 分组名称 deviceType Integer 设备类型 description String 分组描述信息 请求消息示例 httpPOST /v2/dm/deviceGroups HTTP/1.1 Host: api.ymcs.yealink.com Content-Type: application/json { "name":"t54sgroup", "deviceType":1, "description":"test" } 响应消息示例 httpHTTP/1.1 201 Created Content-Type: application/json;charset=UTF-8 { "id": "00884cef841e48f4acd213c084e65f67", "name":"t54sgroup", "deviceType":1, "description":"test" } 2.2.2 编辑分组 请求方法 PATCH 请求地址 /v2/dm/deviceGroups/{deviceGroupId} Path参数 参数 数据类型 是否必需 描述 deviceGroupId String 是 设备分组ID Body参数 参数 数据类型 是否必需 描述 name String 是 分组名称，长度64 deviceType Integer 是 设备类型 1: Phone Device 3: Room Device description String 否 分组描述信息,长度256 HTTP状态码 返回值 描述 204 操作成功 400 客户端传参异常 401 鉴权失败 500 服务端异常 请求消息示例 httpPATCH /v2/dm/deviceGroups/00884cef841e48f4acd213c084e65f67/1.1 Host: api.ymcs.yealink.com Content-Type: application/json { "name":"t54sgroup2", "deviceType":1, "description":"test2" } 响应消息示例 httpHTTP/1.1 204 2.2.3 分组列表 请求方法 POST 请求地址 /v2/dm/listDeviceGroups Body参数 参数 数据类型 是否必需 描述 skip Long 否 跳过的记录数，默认为0 limit Long 否 获取的最大记录数，默认为10，最大500 autoCount Boolean 否 是否要响应总数量，建议在第一页查询时为true,后续翻页时传false filter Filter 否 搜索参数 Filter对象定义 参数 数据类型 是否必需 描述 deviceType Integer 否 设备类型状态, 1: Phone Device 3: Room Device ，不填写时为全部 HTTP状态码 返回值 描述 200 操作成功 400 客户端传参异常 401 鉴权失败 500 服务端异常 响应参数 参数 数据类型 描述 skip Long 偏移量 limit Long 返回最大数量 total Long 总数量 data DeviceGroup[] DeviceGroup信息数组 DeviceGroup对象定义 参数 数据类型 描述 id String 分组ID name String 分组名称，长度64 deviceType Integer 设备类型 1: Phone Device 3: Room Device description String 分组描述信息,长度256 请求消息示例 httpPOST /v2/dm/listDeviceGroups HTTP/1.1 Host: api.ymcs.yealink.com Content-Type: application/json { "skip": 0, "limit": 10, "autoCount": true, "filter":{ "deviceType":1 } } 响应消息示例 httpHTTP/1.1 200 Content-Type: application/json;charset=UTF-8 { "skip": 0, "limit": 10, "total": 1, "data":[{ "id": "00884cef841e48f4acd213c084e65f67", "name":"t54sgroup", "deviceType":1, "description":"test" }] } 2.2.4 删除分组 请求方法 DELETE 请求地址 /v2/dm/deviceGroups/{deviceGroupId} PATH参数 参数 数据类型 是否必需 描述 deviceGroupId String 是 设备分组id HTTP状态码 返回值 描述 204 操作成功 400 客户端传参异常 401 鉴权失败 500 服务端异常 请求消息示例 httpDELETE /v2/dm/deviceGroups/00884cef841e48f4acd213c084e65f67 HTTP/1.1 Host: api.ymcs.yealink.com 响应消息示例 httpHTTP/1.1 204 2.2.5 添加设备到分组 请求方法 POST 请求地址 /v2/dm/deviceGroups/{deviceGroupId}/addDevices PATH参数 参数 数据类型 是否必需 描述 deviceGroupId String 是 设备分组id Body参数 参数 数据类型 是否必需 描述 deviceIds String[] 是 设备ID列表，限制200个 HTTP状态码 返回值 描述 200 操作成功 400 客户端传参异常 401 鉴权失败 500 服务端异常 响应参数 参数 数据类型 描述 total Integer 删除总条数 successCount Integer 成功删除总数量 failureCount Integer 失败总数量 errors OpError[] 错误信息 OpError对象 参数 数据类型 描述 field String 错误字段 msg String 错误信息 请求消息示例 httpPOST /v2/dm/deviceGroups/00884cef841e48f4acd213c084e65f67/addDevices HTTP/1.1 Host: api.ymcs.yealink.com Content-Type: application/json { "deviceIds":["0006572538f74e8683716cf961caa95b","00099642675e4d4bb5e91fd9ae5ce585"] } 响应消息示例 httpHTTP/1.1 200 OK Content-Type: application/json;charset=UTF-8 { "total": 2, "successCount":1, "failureCount":1, "errors":[{ "field":"00099642675e4d4bb5e91fd9ae5ce585", "msg":"The resource does not exist or has been deleted" }] } 2.2.6 从分组中删除设备 请求方法 POST 请求地址 /v2/dm/deviceGroups/{deviceGroupId}/delDevices PATH参数 参数 数据类型 是否必需 描述 deviceGroupId String 是 设备分组id Body参数 参数 数据类型 是否必需 描述 deviceIds String[] 是 设备ID列表,最大长度200 HTTP状态码 返回值 描述 200 操作成功 400 客户端传参异常 401 鉴权失败 500 服务端异常 响应参数 参数 数据类型 描述 total Integer 删除总条数 successCount Integer 成功删除总数量 failureCount Integer 失败总数量 errors OpError[] 错误信息 OpError对象 参数 数据类型 描述 field String 错误字段 msg String 错误信息 请求消息示例 httpPOST /v2/dm/deviceGroups/00884cef841e48f4acd213c084e65f67/delDevices HTTP/1.1 Host: api.ymcs.yealink.com Content-Type: application/json { "deviceIds":["0006572538f74e8683716cf961caa95b","00099642675e4d4bb5e91fd9ae5ce585"] } 响应消息示例 httpHTTP/1.1 200 OK Content-Type: application/json;charset=UTF-8 { "total": 2, "successCount":1, "failureCount":1, "errors":[{ "field":"00099642675e4d4bb5e91fd9ae5ce585", "msg":"The resource does not exist or has been deleted" }] } 2.2.7 查询分组内设备列表 请求方法 POST 请求地址 /v2/dm/deviceGroups/{deviceGroupId}/listDevices PATH参数 参数 数据类型 是否必需 描述 deviceGroupId String 是 设备分组id Body参数 参数 数据类型 是否必需 描述 skip Long 否 跳过的记录数，默认为0 limit Long 否 获取的最大记录数，默认为10，最大500 autoCount Boolean 否 是否要响应总数量，建议在第一页查询时为true,后续翻页时传false filter Filter 否 搜索参数 Filter对象定义 参数 数据类型 是否必需 描述 mac String 否 设备MAC模糊搜索关键字,最大长度17,支持带:或-,如00:15:65:bb:b1:a9 modelId String 否 型号ID deviceStatus Integer 否 设备状态，1:在线， 0:离线，-1:未上报 HTTP状态码 返回值 描述 200 操作成功 400 客户端传参异常 401 鉴权失败 500 服务端异常 响应参数 参数 数据类型 描述 skip Long 偏移量 limit Long 返回最大数量 total Long 总数量 data Device[] Device信息数组 Device对象定义 参数 数据类型 描述 id String 设备id mac String 设备MAC sn String 设备SN name String 设备名称 modelId String 型号ID siteId String 站点ID programVersion String 设备固件版本号 deviceStatus String 设备状态，online:在线， offline:离线，pending:未上报 httpPOST /v2/dm/deviceGroups/00884cef841e48f4acd213c084e65f67/listDevices HTTP/1.1 Host: api.ymcs.yealink.com Content-Type: application/json { "skip": 0, "limit": 10, "autoCount": true } 响应消息示例 httpHTTP/1.1 200 Content-Type: application/json;charset=UTF-8 { "skip": 0, "limit": 10, "total": 1, "data":[{ "id": "8d07a56207074d26b61026099625b9e2", "mac":"001565bbb1a9", "sn":"1106312113402006", "name":"my t54s", "modelId":"61e659e4d78d42ebada88ef1eb751b64", "siteId":"a624453e1cbb44ecb9bb6ee31731a856", "programVersion":"70.83.0.68", "deviceStatus":"online" }] } 2.3 设备控制 2.3.1 设备重启 请求方法 POST 请求地址 /v2/dm/device/reboot Body参数 参数 数据类型 是否必需 描述 deviceIds String[] 是 设备ID列表，最大长度200 deviceType Integer 是 设备类型 1: Phone Device 3:Room Device HTTP状态码 返回值 描述 200 操作成功 400 客户端传参异常 401 鉴权失败 500 服务端异常 响应参数 参数 数据类型 描述 total Integer 重启总设备数 successCount Integer 重启成功数量 failureCount Integer 重启失败数量 errors OpError[] 错误信息 OpError对象 参数 数据类型 描述 field String 错误字段 msg String 错误信息 请求消息示例 httpPOST /v2/dm/device/reboot HTTP/1.1 Host: api.ymcs.yealink.com Content-Type: application/json { "deviceIds":["0006572538f74e8683716cf961caa95b","00099642675e4d4bb5e91fd9ae5ce585"], "deviceType":1 } 响应消息示例 httpHTTP/1.1 200 OK Content-Type: application/json;charset=UTF-8 { "total": 2, "successCount":1, "failureCount":1, "errors":[{ "field":"0006572538f74e8683716cf961caa95b", "msg":"The resource does not exist or has been deleted" }] } 2.3.2 设备恢复出厂 请求方法 POST 请求地址 /v2/dm/device/reset Body参数 参数 数据类型 是否必需 描述 deviceIds String[] 是 设备ID列表 deviceType Integer 是 设备类型 1: Phone Device 3:Room Device HTTP状态码 返回值 描述 204 操作成功 400 客户端传参异常 401 鉴权失败 500 服务端异常 响应参数 参数 数据类型 描述 total Integer 恢复出厂总设备数 successCount Integer 恢复出厂成功数量 failureCount Integer 恢复出厂失败数量 errors OpError[] 错误信息 OpError对象 参数 数据类型 描述 field String 错误字段 msg String 错误信息 请求消息示例 httpPOST /v2/dm/device/reset HTTP/1.1 Host: api.ymcs.yealink.com Content-Type: application/json { "deviceIds":["0006572538f74e8683716cf961caa95b","00099642675e4d4bb5e91fd9ae5ce585"], "deviceType":1 } 响应消息示例 httpHTTP/1.1 200 OK Content-Type: application/json;charset=UTF-8 { "total": 2, "successCount":1, "failureCount":1, "errors":[{ "field":"0006572538f74e8683716cf961caa95b", "msg":"The resource does not exist or has been deleted" }] } 2.4 设备标识管理 2.4.1 获取设备ID 请求方法 POST 请求地址 /v2/dm/deviceId Body参数 参数 数据类型 是否必需 描述 deviceType Integer 是 设备类型 1: Phone Device 3:Room Device deviceIdType String 否 表示设备标识的类型，默认mac，可选mac deviceIds String[] 是 设备标识,限制200个 HTTP状态码 返回值 描述 200 操作成功 400 客户端传参异常 401 鉴权失败 500 服务端异常 响应参数 参数 数据类型 描述 key String 设备标识 deviceId String 设备ID 请求消息示例 httpPOST /v2/dm/deviceId HTTP/1.1 Host: api.ymcs.yealink.com Content-Type: application/json { "deviceType":1, "deviceIds":["001565bbb1a9"], "deviceIdType":"mac" } 响应消息示例 httpHTTP/1.1 200 Content-Type: application/json;charset=UTF-8 [{ "key":"001565bbb1a9", "deviceId":"8d07a56207074d26b61026099625b9e2" }] 2.5 设备配件管理 2.5.1 配件列表 请求方法 POST 请求地址 /v2/dm/devices/{deviceId}/listParts Path参数 参数 数据类型 是否必需 描述 deviceId String 是 设备ID Body参数 参数 数据类型 是否必需 描述 skip Long 否 跳过的记录数，默认为0 limit Long 否 获取的最大记录数，默认为10，最大500 autoCount Boolean 否 是否要响应总数量，建议在第一页查询时为true,后续翻页时传false HTTP状态码 返回值 描述 200 操作成功 400 客户端传参异常 401 鉴权失败 500 服务端异常 响应参数 参数 数据类型 描述 id String 配件id mac String 配件MAC sn String 配件SN modelId String 型号ID connectWay String 配件连接方式，包括USB,BT等 connStatus Integer 状态，1:在线， 0:离线 lanIp String 内网IP programVersion String 固件版本号 lastReportTime Long 最后上报时间 请求消息示例 httpPOST /v2/dm/devices/8d07a56207074d26b61026099625b9e2/listParts HTTP/1.1 Host: api.ymcs.yealink.com Content-Type: application/json { "skip": 0, "limit": 20, "autoCount": true } 响应消息示例 httpHTTP/1.1 200 Content-Type: application/json;charset=UTF-8 { "skip": 0, "limit": 10, "total": 1, "data":[{ "id": "5d6017f6fe004eb7ac1107c80c1c44b7", "mac":"001565bbb1a9", "sn":"1106312113402006", "modelId":"e7c5c0c406cf4a02bd9ed64183d1de05", "modelName": "CP700", "connectWay":"USB", "connStatus":1, "lanIp":"10.60.50.22", "programVersion":"153.433.0.5", "lastReportTime":1709577211630 }] } 2.5.2 配件详情 请求方法 GET 请求地址 /v2/dm/devices/{deviceId}/parts/{partId} Path参数 参数 数据类型 是否必需 描述 deviceId String 是 设备ID partId String 是 配件ID HTTP状态码 返回值 描述 200 操作成功 400 客户端传参异常 401 鉴权失败 500 服务端异常 响应参数 参数 数据类型 描述 id String 配件id mac String 配件MAC sn String 配件SN modelId String 型号ID connectWay String 配件连接方式，包括USB,BT等 connStatus Integer 状态，1:在线， 0:离线 lanIp String 内网IP programVersion String 固件版本号 lastReportTime Long 最后上报时间 extraInfo ExtraInfo 额外信息，与型号有关，当型号为传感器时，响应的内容包括温度，电量等内容 ExtraInfo对象定义 当型号为传感器时，内容如下 参数 数据类型 描述 batteryLevel Integer 电量 humidity Integer 湿度 irradiance Integer 辐照度 temperature Integer 温度 numPeople Integer 人数统计 请求消息示例 httpGET /v2/dm/devices/8d07a56207074d26b61026099625b9e2/parts/104aa43ca9994de0825ec8d32f3a8c60 HTTP/1.1 Host: api.ymcs.yealink.com 响应消息示例 httpHTTP/1.1 200 Content-Type: application/json;charset=UTF-8 { "id": "104aa43ca9994de0825ec8d32f3a8c60", "mac":"84fd27df8045", "sn":"803111D070000358", "modelId":"50b2674518a648968367ea2bb61a5572", "modelName":"RoomSensor", "connectWay":"BT", "connStatus":1, "lanIp":"10.60.50.21", "programVersion":"153.433.0.5", "lastReportTime":1709577211630, "extraInfo":{ "batteryLevel":100, "humidity":55, "irradiance":27, "temperature":31, "numPeople":2 } } 2.5.3 配件重启 请求方法 POST 请求地址 /v2/dm/devices/{deviceId}/parts/reboot Path参数 参数 数据类型 是否必需 描述 deviceId String 是 设备id Body参数 参数 数据类型 是否必需 描述 partIds String[] 否 配件ID列表，最大长度200，不传时表示此设备下的所有配件重启 HTTP状态码 返回值 描述 200 操作成功 400 客户端传参异常 401 鉴权失败 500 服务端异常 响应参数 参数 数据类型 描述 total Integer 重启总设备数 successCount Integer 重启成功数量 failureCount Integer 重启失败数量 errors OpError[] 错误信息 OpError对象 参数 数据类型 描述 field String 错误字段 msg String 错误信息 请求消息示例 httpPOST /v2/dm/device/0006572538f74e8683716cf961caa95b/parts/reboot HTTP/1.1 Host: api.ymcs.yealink.com Content-Type: application/json { "partIds":["00ab7c8da8ff4345af3857feb68aedef","0299d1254f7042068c4ef1c5895b7e5a"] } 响应消息示例 httpHTTP/1.1 200 OK Content-Type: application/json;charset=UTF-8 { "total": 2, "successCount":1, "failureCount":1, "errors":[{ "field":"00ab7c8da8ff4345af3857feb68aedef", "msg":"The resource does not exist or has been deleted" }] } 2.5.4 配件恢复出厂 请求方法 POST 请求地址 /v2/dm/devices/{deviceId}/parts/reset Path参数 参数 数据类型 是否必需 描述 deviceId String 是 设备id Body参数 参数 数据类型 是否必需 描述 partIds String[] 否 配件ID列表，最大长度200个，不传时表示此设备下的所有配件恢复出厂 HTTP状态码 返回值 描述 200 操作成功 400 客户端传参异常 401 鉴权失败 500 服务端异常 响应参数 参数 数据类型 描述 total Integer 恢复出厂总设备数 successCount Integer 恢复出厂成功数量 failureCount Integer 恢复出厂失败数量 errors OpError[] 错误信息 OpError对象 参数 数据类型 描述 field String 错误字段 msg String 错误信息 请求消息示例 httpPOST /v2/dm/device/0006572538f74e8683716cf961caa95b/parts/reset HTTP/1.1 Host: api.ymcs.yealink.com Content-Type: application/json { "partIds":["00ab7c8da8ff4345af3857feb68aedef","0299d1254f7042068c4ef1c5895b7e5a"] } 响应消息示例 httpHTTP/1.1 200 OK Content-Type: application/json;charset=UTF-8 { "total": 2, "successCount":1, "failureCount":1, "errors":[{ "field":"00ab7c8da8ff4345af3857feb68aedef", "msg":"The resource does not exist or has been deleted" }] } 2.6 设备账号管理 2.6.1 设备绑定账号 请求方法 POST 请求地址 /v2/dm/devices/{deviceId}/bindAccounts Path参数 参数 数据类型 是否必需 描述 deviceId String 是 设备id Body参数 参数 数据类型 是否必需 描述 accounts BindAccount[] 是 要绑定的账号信息列表 BindAccount对象定义 参数 数据类型 描述 lineId integer 账号线路,从1开始 accountType Integer 账号类型: 0：SIP,1:H323 2:SFB accountId String 账号ID HTTP状态码 返回值 描述 200 操作成功 400 客户端传参异常 401 鉴权失败 500 服务端异常 响应参数 参数 数据类型 描述 total Integer 绑定总数量 successCount Integer 绑定成功数量 failureCount Integer 绑定失败数量 errors OpError[] 错误信息 OpError对象 参数 数据类型 描述 field String 错误字段 msg String 错误信息 请求消息示例 httpPOST /v2/dm/devices/8d07a56207074d26b61026099625b9e2/bindAccounts HTTP/1.1 Host: api.ymcs.yealink.com Content-Type: application/json [{ "lineId":1, "accountType":0, "accountId":"604e67944c7c43fe8b66099254ec3439" },{ "lineId":2, "accountType":0, "accountId":"a45a6b4a7e0447b8a6c3f2839d902acd" }] 响应消息示例 httpHTTP/1.1 200 OK Content-Type: application/json;charset=UTF-8 { "total": 2, "successCount":1, "failureCount":1, "errors":[{ "field":"604e67944c7c43fe8b66099254ec3439", "msg":"The resource does not exist or has been deleted" }] } 2.6.2 设备解绑账号 请求方法 POST 请求地址 /v2/dm/devices/{deviceId}/unbindAccounts Path参数 参数 数据类型 是否必需 描述 deviceId String 是 设备id Body参数 参数 数据类型 是否必需 描述 accountIds String[] 是 要解绑的账号ID列表 HTTP状态码 返回值 描述 204 操作成功 400 客户端传参异常 401 鉴权失败 500 服务端异常 响应参数 参数 数据类型 描述 total Integer 解绑总数量 successCount Integer 解绑成功数量 failureCount Integer 解绑失败数量 errors OpError[] 错误信息 OpError对象 参数 数据类型 描述 field String 错误字段 msg String 错误信息 请求消息示例 httpPOST /v2/dm/devices/8d07a56207074d26b61026099625b9e2/unbindAccounts HTTP/1.1 Host: api.ymcs.yealink.com Content-Type: application/json { "accountIds":["604e67944c7c43fe8b66099254ec3439","a45a6b4a7e0447b8a6c3f2839d902acd"] } 响应消息示例 httpHTTP/1.1 200 OK Content-Type: application/json;charset=UTF-8 { "total": 2, "successCount":1, "failureCount":1, "errors":[{ "field":"604e67944c7c43fe8b66099254ec3439", "msg":"The resource does not exist or has been deleted" }] } 2.6.3 设备绑定的账号列表 请求方法 GET 请求地址 /v2/dm/devices/{deviceId}/boundAccounts Path参数 参数 数据类型 是否必需 描述 deviceId String 是 设备id HTTP状态码 返回值 描述 200 操作成功 400 客户端传参异常 401 鉴权失败 500 服务端异常 响应参数 参数 数据类型 描述 data BindAccount[] 绑定的账号信息数组 BindAccount对象定义 参数 数据类型 描述 accountId String 账号ID lineId Integer 账号线路,从1开始 accountType Integer 账号类型: 0：SIP,1:H323 2:SFB accountServer String 账号服务器地址 registerName String 注册名称 username String 用户名称 请求消息示例 httpGET /v2/dm/devices/8d07a56207074d26b61026099625b9e2/boundAccounts HTTP/1.1 Host: api.ymcs.yealink.com 响应消息示例 httpHTTP/1.1 200 Content-Type: application/json [{ "accountId":"604e67944c7c43fe8b66099254ec3439" "lineId":1, "accountType":0, "accountServer":"10.200.108.48", "registerName":"1000", "username":"1000" },{ "accountId":"a45a6b4a7e0447b8a6c3f2839d902acd" "lineId":2, "accountType":0, "accountServer":"10.200.108.48", "registerName":"2000", "username":"2000" }] 3.账号管理 3.1 添加SIP账号 请求方法 POST 请求地址 /v2/dm/sipAccounts Body参数 参数 数据类型 是否必需 描述 registerName String 是 注册名称，最大长度128 username String 是 用户名，最大长度128 password String 是 密码，最大长度128 displayName String 否 显示名，最大长度128 label String 否 标签，最大长度128 sipServer1 SipServer 是 sip服务器1地址 sipServer2 SipServer 否 sip服务器2地址 remark String 否 备注，最大长度512 siteId String 否 要归属的站点ID SipServer对象定义 参数 数据类型 描述 host String 服务器地址,最大长度256 port Integer 服务器端口,0~65535 HTTP状态码 返回值 描述 201 操作成功 400 客户端传参异常 401 鉴权失败 500 服务端异常 响应参数 参数 数据类型 描述 id String 账号id username String 用户名 registerInfo String 注册信息 serverAddress String 服务器地址 accountType Integer 账号类型,0：SIP,1:H323 2:SFB remark String 备注 createTime Long 创建时间 请求消息示例 httpPOST /v2/dm/sipAccounts HTTP/1.1 Host: api.ymcs.yealink.com Content-Type: application/json { "registerName": "2552", "username": "2552", "password": "******", "label": "2552", "displayName": "2552", "sipServer1": { "host": "ume.yealink.com", "port":5061 }, "siteId":"0006d62003684754b11c09c5d94ea687", "remark":"test" } 响应消息示例 httpHTTP/1.1 201 Created Content-Type: application/json;charset=UTF-8 { "id": "e33b8f25247e45de84dd4c74503b241a", "registerInfo": "2552", "username": "2552", "serverAddress": "ume.yealink.com", "accountType": 0, "createTime": 1698052518923 } 3.2 编辑SIP账号 请求方法 PATCH 请求地址 /v2/dm/sipAccounts/{accountId} Path参数 参数 数据类型 是否必需 描述 accountId String 是 账号ID Body参数 参数 数据类型 是否必需 描述 registerName String 是 注册名称，最大长度128 username String 是 用户名，最大长度128 password String 是 密码，最大长度128 displayName String 否 显示名，最大长度128 label String 否 标签，最大长度128 sipServer1 SipServer 是 sip服务器1地址 sipServer2 SipServer 否 sip服务器2地址 remark String 否 备注，最大长度512 siteId String 否 要归属的站点ID SipServer对象定义 参数 数据类型 描述 host String 服务器地址，最大长度256 port Integer 服务器端口,0~65535 HTTP状态码 返回值 描述 204 操作成功 400 客户端传参异常 401 鉴权失败 500 服务端异常 请求消息示例 httpPATCH /v2/dm/sipAccounts/e33b8f25247e45de84dd4c74503b241a HTTP/1.1 Host: api.ymcs.yealink.com Content-Type: application/json { "registerName": "2553", "username": "2552", "password": "******", "label": "2552", "displayName": "2552", "sipServer1": { "host": "ume.yealink.com", "port":5061 }, "siteId":"0006d62003684754b11c09c5d94ea687", "remark":"test" } 响应消息示例 httpHTTP/1.1 204 3.3 账号列表 请求方法 POST 请求地址 /v2/dm/listAccounts Body参数 参数 数据类型 是否必需 描述 skip Long 否 跳过的记录数，默认为0 limit Long 否 获取的最大记录数，默认为10，最大500 autoCount Boolean 否 是否要响应总数量，建议在第一页查询时为true,后续翻页时传false filter Filter 否 搜索参数 Filter对象定义 参数 数据类型 是否必需 描述 username String 否 用户名模糊搜索关键字 HTTP状态码 返回值 描述 200 操作成功 400 客户端传参异常 401 鉴权失败 500 服务端异常 响应参数 参数 数据类型 描述 skip Long 偏移量 limit Long 返回最大数量 total Long 总数量 data Account[] Account信息数组 Account对象定义 参数 数据类型 描述 id String 账号id username String 用户名 registerInfo String 注册信息 serverAddress String 服务器地址 accountType Integer 账号类型,0：SIP,1:H323 2:SFB remark String 备注 createTime Long 创建时间 请求消息示例 httpPOST /v2/dm/listAccounts HTTP/1.1 Host: api.ymcs.yealink.com Content-Type: application/json { "skip": 0, "limit": 20, "autoCount": true, "filter":{ "username":"2552" } } 响应消息示例 httpHTTP/1.1 200 Content-Type: application/json;charset=UTF-8 { "skip": 0, "limit": 10, "total": 1, "data":[{ "id": "e33b8f25247e45de84dd4c74503b241a", "registerInfo": "2552", "username": "h323", "accountType": 1, "createTime": 1698052518923 }] } 3.4 删除账号 请求方法 POST 请求地址 /v2/dm/delAccounts Body参数 参数 数据类型 是否必需 描述 accountIds String[] 是 账号ID列表,最大长度200 HTTP状态码 返回值 描述 200 操作成功 400 客户端传参异常 401 鉴权失败 500 服务端异常 响应参数 参数 数据类型 描述 total Integer 删除总条数 successCount Integer 成功删除总数量 failureCount Integer 失败总数量 errors OpError[] 错误信息 OpError对象 参数 数据类型 描述 field String 错误字段 msg String 错误信息 请求消息示例 httpPOST /v2/dm/delAccounts HTTP/1.1 Host: api.ymcs.yealink.com Content-Type: application/json { "accountIds":["e33b8f25247e45de84dd4c74503b241a","2d3e77b736e240eabf25aa1f5448aa0c"] } 响应消息示例 httpHTTP/1.1 200 OK Content-Type: application/json;charset=UTF-8 { "total": 2, "successCount":1, "failureCount":1, "errors":[{ "field":"2d3e77b736e240eabf25aa1f5448aa0c", "msg":"The resource does not exist or has been deleted" }] } 4.配置管理 4.1 话机设备配置管理 4.1.1 设备配置列表 请求方法 POST 请求地址 /v2/dm/listDeviceConfigs Body参数 参数 数据类型 是否必需 描述 skip Long 否 跳过的记录数，默认为0 limit Long 否 获取的最大记录数，默认为10，最大500 autoCount Boolean 否 是否要返回记录总数据量 filter Filter 否 过滤条件 Filter对象定义 参数 数据类型 是否必需 描述 mac String 否 设备MAC模糊搜索关键字,最大长度17,支持带:或-,如00:15:65:bb:b1:a9 响应参数 参数 数据类型 描述 skip Long 偏移量 limit Long 返回最大数量 total Long 总数据量 data Config[] Config信息数组 Config对象定义 参数 数据类型 描述 id String 主键id name String 配置名称 modelId String 型号ID description String 配置描述 HTTP状态码 返回值 描述 200 操作成功 400 客户端传参异常 401 鉴权失败 500 服务端异常 请求消息示例 httpPOST /v2/dm/listDeviceConfigs HTTP/1.1 Host: api.ymcs.yealink.com Content-Type: application/json { "skip": 0, "limit": 10, "autoCount": true, "filter":{ "mac":"001565bbb1a9" } } 响应消息示例 httpHTTP/1.1 200 Content-Type: application/json;charset=UTF-8 { "skip": 0, "limit": 10, "total": 1, "data":[{ "id": "8d07a56207074d26b61026099625b9e2", "name":"my config", "modelId":"61e659e4d78d42ebada88ef1eb751b64", "description":"my t54s config" }] } 4.1.2 添加设备配置 请求方法 POST 请求地址 /v2/dm/deviceConfigs Body参数 参数 数据类型 是否必需 描述 deviceId String 是 设备ID content String 是 cfg文件内容 autoPush Boolean 否 在话机设备首次上电或恢复出厂时是否自动推送此设备配置,true:是 false:否 HTTP状态码 返回值 描述 201 操作成功 400 客户端传参异常 401 鉴权失败 500 服务端异常 响应参数 参数 数据类型 描述 id String 设备配置id 请求消息示例 httpPOST /v2/dm/deviceConfigs HTTP/1.1 Host: api.ymcs.yealink.com Content-Type: application/json { "deviceId": "8d07a56207074d26b61026099625b9e2", "content": "lang.wui=English\nlang.gui=English", "autoPush":true } 响应消息示例 httpHTTP/1.1 201 Created Content-Type: application/json;charset=UTF-8 { "id": "d916a46b4557464c87c278cb37477bef" } 4.1.3 删除设备配置 请求方法 POST 请求地址 /v2/dm/delDeviceConfigs Body参数 参数 数据类型 是否必需 描述 configIds String[] 是 设备配置ID列表，最大长度200 HTTP状态码 返回值 描述 200 操作成功 400 客户端传参异常 401 鉴权失败 500 服务端异常 响应参数 参数 数据类型 描述 total Integer 删除总条数 successCount Integer 成功删除总数量 failureCount Integer 失败总数量 errors OpError[] 错误信息 OpError对象 参数 数据类型 描述 field String 错误字段 msg String 错误信息 请求消息示例 httpPOST /v2/dm/delDeviceConfigs HTTP/1.1 Host: api.ymcs.yealink.com Content-Type: application/json { "configIds":["e33b8f25247e45de84dd4c74503b241a","8d07a56207074d26b61026099625b9e2"] } 响应消息示例 httpHTTP/1.1 200 OK Content-Type: application/json;charset=UTF-8 { "total": 2, "successCount":1, "failureCount":1, "errors":[{ "field":"e33b8f25247e45de84dd4c74503b241a", "msg":"The resource does not exist or has been deleted" }] } 4.1.4 设备配置详情 请求方法 GET 请求地址 /v2/dm/deviceConfigs/{configId} Path参数 参数 数据类型 是否必需 描述 configId String 是 设备配置id HTTP状态码 返回值 描述 200 操作成功 400 客户端传参异常 401 鉴权失败 500 服务端异常 响应参数 参数 数据类型 描述 id String 设备配置id name String 配置名称 modelId String 型号ID content String 配置内容 description String 配置描述 请求消息示例 httpGET /v2/dm/deviceConfigs/e33b8f25247e45de84dd4c74503b241a HTTP/1.1 Host: api.ymcs.yealink.com 响应消息示例 httpHTTP/1.1 200 Content-Type: application/json;charset=UTF-8 { "id": "8d07a56207074d26b61026099625b9e2", "name":"my config", "modelId":"61e659e4d78d42ebada88ef1eb751b64", "content":"#!version:1.0.0.1\naccount.1.codec.g722.enable=1" "description":"my t54s config" } 4.1.5 推送设备配置 请求方法 POST 请求地址 /v2/dm/deviceConfigs/{configId}/push Path参数 参数 数据类型 是否必需 描述 configId String 是 配置ID HTTP状态码 返回值 描述 204 操作成功 400 客户端传参异常 401 鉴权失败 500 服务端异常 请求消息示例 httpPOST /v2/dm/deviceConfigs/e33b8f25247e45de84dd4c74503b241a/push HTTP/1.1 Host: api.ymcs.yealink.com 响应消息示例 httpHTTP/1.1 204 4.2 话机分站点配置管理 4.2.1 添加分站点配置 请求方法 POST 请求地址 /v2/dm/siteConfigs Body参数 参数 数据类型 是否必需 描述 name String 是 分站点配置名称,长度64 siteId String 是 站点ID deviceType Integer 是 设备类型 1: Phone Device modelId String 否 型号ID,不填写时表示全部型号 content String 否 配置文件内容 description String 否 描述，长度256 HTTP状态码 返回值 描述 201 操作成功 400 客户端传参异常 401 鉴权失败 500 服务端异常 响应参数 参数 数据类型 描述 id String 设备配置id 请求消息示例 httpPOST /v2/dm/siteConfigs HTTP/1.1 Host: api.ymcs.yealink.com Content-Type: application/json { "name": "site1 config", "siteId":"048a97f00ece46bd8d8bf97f5002992a", "deviceType":1, "modelId":"db249ca8f83f425baeda09214288d0a9", "content": "lang.wui=English\nlang.gui=English", "description":"test" } 响应消息示例 httpHTTP/1.1 201 Created Content-Type: application/json;charset=UTF-8 { "id": "8b7f1739ad6d4a578267d09b53a262a3" } 4.2.2 编辑分站点配置 请求方法 PATCH 请求地址 /v2/dm/siteConfigs/{configId} Path参数 参数 数据类型 是否必需 描述 configId String 是 分站点配置ID Body参数 参数 数据类型 是否必需 描述 name String 是 分站点配置名称,长度64 siteId String 是 站点ID deviceType Integer 是 设备类型 1: Phone Device modelId String 否 型号ID,不填写时表示全部型号 content String 否 配置文件内容 description String 否 描述，长度256 HTTP状态码 返回值 描述 204 操作成功 400 客户端传参异常 401 鉴权失败 500 服务端异常 请求消息示例 httpPATCH /v2/dm/siteConfigs/8b7f1739ad6d4a578267d09b53a262a3 HTTP/1.1 Host: api.ymcs.yealink.com Content-Type: application/json { "name": "site1 config2", "siteId":"048a97f00ece46bd8d8bf97f5002992a", "deviceType":1, "modelId":"db249ca8f83f425baeda09214288d0a9", "content": "lang.wui=English\nlang.gui=English", "description":"test2" } 响应消息示例 httpHTTP/1.1 204 4.2.3 删除分站点配置 请求方法 POST 请求地址 /v2/dm/delSiteConfigs Body参数 参数 数据类型 是否必需 描述 configIds String[] 是 分站点配置ID列表，最大长度200 HTTP状态码 返回值 描述 200 操作成功 400 客户端传参异常 401 鉴权失败 500 服务端异常 响应参数 参数 数据类型 描述 total Integer 删除总条数 successCount Integer 成功删除总数量 failureCount Integer 失败总数量 errors OpError[] 错误信息 OpError对象 参数 数据类型 描述 field String 错误字段 msg String 错误信息 请求消息示例 httpPOST /v2/dm/delSiteConfigs HTTP/1.1 Host: api.ymcs.yealink.com Content-Type: application/json { "configIds":["8b7f1739ad6d4a578267d09b53a262a3","e33b8f25247e45de84dd4c74503b241a"] } 响应消息示例 httpHTTP/1.1 200 OK Content-Type: application/json;charset=UTF-8 { "total": 2, "successCount":1, "failureCount":1, "errors":[{ "field":"e33b8f25247e45de84dd4c74503b241a", "msg":"The resource does not exist or has been deleted" }] } 4.2.4 分站点配置详情 请求方法 GET 请求地址 /v2/dm/siteConfigs/{configId} Path参数 参数 数据类型 是否必需 描述 configId String 是 分站点配置id HTTP状态码 返回值 描述 200 操作成功 400 客户端传参异常 401 鉴权失败 500 服务端异常 响应参数 参数 数据类型 描述 id String 分站点配置ID name String 分站点配置名称,长度64 siteId String 站点ID deviceType Integer 设备类型 1: Phone Device modelId String 型号ID content String 配置文件内容 description String 描述，长度256 请求消息示例 httpGET /v2/dm/siteConfigs/8b7f1739ad6d4a578267d09b53a262a3 HTTP/1.1 Host: api.ymcs.yealink.com 响应消息示例 httpHTTP/1.1 200 Content-Type: application/json;charset=UTF-8 { "id": "8b7f1739ad6d4a578267d09b53a262a3", "name": "site1 config2", "siteId":"048a97f00ece46bd8d8bf97f5002992a", "deviceType":1, "modelId":"db249ca8f83f425baeda09214288d0a9", "content": "lang.wui=English\nlang.gui=English", "description":"test2" } 4.2.5 分站点配置列表 请求方法 POST 请求地址 /v2/dm/listSiteConfigs Body参数 参数 数据类型 是否必需 描述 skip Long 否 跳过的记录数，默认为0 limit Long 否 获取的最大记录数，默认为10，最大500 autoCount Boolean 否 是否要返回记录总数据量 响应参数 参数 数据类型 描述 skip Long 偏移量 limit Long 返回最大数量 total Long 总数据量 data Config[] Config信息数组 Config定义 参数 数据类型 描述 id String 分站点配置ID name String 分站点配置名称,长度64 siteId String 站点ID deviceType Integer 设备类型 1: Phone Device modelId String 型号ID description String 描述，长度256 HTTP状态码 返回值 描述 200 操作成功 400 客户端传参异常 401 鉴权失败 500 服务端异常 请求消息示例 httpPOST /v2/dm/listSiteConfigs HTTP/1.1 Host: api.ymcs.yealink.com Content-Type: application/json { "skip": 0, "limit": 10, "autoCount": true } 响应消息示例 httpHTTP/1.1 200 Content-Type: application/json;charset=UTF-8 { "skip": 0, "limit": 10, "total": 1, "data":[{ "id": "8b7f1739ad6d4a578267d09b53a262a3", "name": "site1 config2", "siteId":"048a97f00ece46bd8d8bf97f5002992a", "deviceType":1, "modelId":"db249ca8f83f425baeda09214288d0a9", "description":"test2" }] } 4.2.6 推送分站点配置 请求方法 POST 请求地址 /v2/dm/siteConfigs/{configId}/push Path参数 参数 数据类型 是否必需 描述 configId String 是 配置ID HTTP状态码 返回值 描述 204 操作成功 400 客户端传参异常 401 鉴权失败 500 服务端异常 请求消息示例 httpPOST /v2/dm/siteConfigs/8b7f1739ad6d4a578267d09b53a262a3/push HTTP/1.1 Host: api.ymcs.yealink.com 响应消息示例 httpHTTP/1.1 204 4.3 话机分组配置管理 4.3.1 添加分组配置 请求方法 POST 请求地址 /v2/dm/groupConfigs Body参数 参数 数据类型 是否必需 描述 name String 是 分组配置名称,长度64 deviceGroupId String 是 设备分组ID deviceType Integer 是 设备类型 1: Phone Device modelId String 否 型号ID,不填写时表示全部型号 content String 否 配置文件内容 description String 否 描述，长度256 响应参数 参数 数据类型 描述 id String 分组配置id HTTP状态码 返回值 描述 201 操作成功 400 客户端传参异常 401 鉴权失败 500 服务端异常 请求消息示例 httpPOST /v2/dm/groupConfigs HTTP/1.1 Host: api.ymcs.yealink.com Content-Type: application/json { "name": "group config", "deviceGroupId":"1185861ed00840ea99a7b07aa0f28f88", "deviceType":1, "modelId":"db249ca8f83f425baeda09214288d0a9", "content": "lang.wui=English\nlang.gui=English", "description":"test" } 响应消息示例 httpHTTP/1.1 201 Created Content-Type: application/json;charset=UTF-8 { "id": "8faa39e34929425f85b4cd9925a2bbcb" } 4.3.2 编辑分组配置 请求方法 PATCH 请求地址 /v2/dm/groupConfigs/{configId} Path参数 参数 数据类型 是否必需 描述 configId String 是 分组配置ID Body参数 参数 数据类型 是否必需 描述 name String 是 分组配置名称,长度64 deviceGroupId String 是 设备分组ID deviceType Integer 是 设备类型 1: Phone Device modelId String 否 型号ID,不填写时表示全部型号 content String 否 配置文件内容 description String 否 描述，长度256 HTTP状态码 返回值 描述 204 操作成功 400 客户端传参异常 401 鉴权失败 500 服务端异常 请求消息示例 httpPATCH /v2/dm/groupConfigs/8faa39e34929425f85b4cd9925a2bbcb HTTP/1.1 Host: api.ymcs.yealink.com Content-Type: application/json { "name": "group config2", "deviceGroupId":"1185861ed00840ea99a7b07aa0f28f88", "deviceType":1, "modelId":"db249ca8f83f425baeda09214288d0a9", "content": "lang.wui=English\nlang.gui=English", "description":"test2" } 响应消息示例 httpHTTP/1.1 204 4.3.3 删除分组配置 请求方法 POST 请求地址 /v2/dm/delGroupConfigs Body参数 参数 数据类型 是否必需 描述 configIds String[] 是 分组配置ID列表，最大长度200 HTTP状态码 返回值 描述 200 操作成功 400 客户端传参异常 401 鉴权失败 500 服务端异常 响应参数 参数 数据类型 描述 total Integer 删除总条数 successCount Integer 成功删除总数量 failureCount Integer 失败总数量 errors OpError[] 错误信息 OpError对象 参数 数据类型 描述 field String 错误字段 msg String 错误信息 请求消息示例 httpDELETE /v2/dm/delGroupConfigs HTTP/1.1 Host: api.ymcs.yealink.com Content-Type: application/json { "configIds":["8faa39e34929425f85b4cd9925a2bbcb","e33b8f25247e45de84dd4c74503b241a"] } 响应消息示例 httpHTTP/1.1 200 OK Content-Type: application/json;charset=UTF-8 { "total": 2, "successCount":1, "failureCount":1, "errors":[{ "field":"e33b8f25247e45de84dd4c74503b241a", "msg":"The resource does not exist or has been deleted" }] } 4.3.4 分组配置详情 请求方法 GET 请求地址 /v2/dm/groupConfigs/{configId} Path参数 参数 数据类型 是否必需 描述 configId String 是 分组配置id 响应参数 参数 数据类型 描述 id String 分组配置ID name String 分组配置名称,长度64 deviceGroupId String 分组ID deviceType Integer 设备类型 1: Phone Device modelId String 型号ID content String 配置文件内容 description String 描述，长度256 HTTP状态码 返回值 描述 200 操作成功 400 客户端传参异常 401 鉴权失败 500 服务端异常 请求消息示例 httpGET /v2/dm/groupConfigs/8faa39e34929425f85b4cd9925a2bbcb HTTP/1.1 Host: api.ymcs.yealink.com 响应消息示例 httpHTTP/1.1 200 Content-Type: application/json;charset=UTF-8 { "id": "8faa39e34929425f85b4cd9925a2bbcb", "name": "group config2", "deviceGroupId":"1185861ed00840ea99a7b07aa0f28f88", "deviceType":1, "modelId":"db249ca8f83f425baeda09214288d0a9", "content": "lang.wui=English\nlang.gui=English", "description":"test2" } 4.3.5 分组配置列表 请求方法 POST 请求地址 /v2/dm/listGroupConfigs Body参数 参数 数据类型 是否必需 描述 skip Long 否 跳过的记录数，默认为0 limit Long 否 获取的最大记录数，默认为10，最大500 autoCount Boolean 否 是否要返回记录总数据量 响应参数 参数 数据类型 描述 skip Long 偏移量 limit Long 返回最大数量 total Long 总数据量 data Config[] Config信息数组 Config定义 参数 数据类型 描述 id String 分组配置ID name String 分组配置名称,长度64 deviceGroupId String 分组ID deviceType Integer 设备类型 1: Phone Device modelId String 型号ID description String 描述，长度256 HTTP状态码 返回值 描述 200 操作成功 400 客户端传参异常 401 鉴权失败 500 服务端异常 请求消息示例 httpPOST /v2/dm/listGroupConfigs HTTP/1.1 Host: api.ymcs.yealink.com Content-Type: application/json { "skip": 0, "limit": 10, "autoCount": true } 响应消息示例 httpHTTP/1.1 200 Content-Type: application/json;charset=UTF-8 { "skip": 0, "limit": 10, "total": 1, "data":[{ "id": "8faa39e34929425f85b4cd9925a2bbcb", "name": "group config2", "deviceGroupId":"1185861ed00840ea99a7b07aa0f28f88", "deviceType":1, "modelId":"db249ca8f83f425baeda09214288d0a9", "description":"test2" }] } 4.3.6 推送分组配置 请求方法 POST 请求地址 /v2/dm/groupConfigs/{configId}/push Path参数 参数 数据类型 是否必需 描述 configId String 是 配置ID HTTP状态码 返回值 描述 204 操作成功 400 客户端传参异常 401 鉴权失败 500 服务端异常 请求消息示例 httpPOST /v2/dm/groupConfigs/8faa39e34929425f85b4cd9925a2bbcb/push HTTP/1.1 Host: api.ymcs.yealink.com 响应消息示例 httpHTTP/1.1 204 4.4 会议室设备配置管理 4.4.1 保存设备配置 请求方法 PUT 请求地址 /v2/dm/rooms/deviceConfigs Body参数 参数 数据类型 是否必需 描述 deviceId String 是 设备ID content String 是 cfg文件内容 HTTP状态码 返回值 描述 200 操作成功 400 客户端传参异常 401 鉴权失败 500 服务端异常 响应参数 参数 数据类型 描述 id String 设备配置id 请求消息示例 httpPUT /v2/dm/rooms/deviceConfigs HTTP/1.1 Host: api.ymcs.yealink.com Content-Type: application/json { "deviceId": "8d07a56207074d26b61026099625b9e2", "content": "lang.wui=English\nlang.gui=English" } 响应消息示例 httpHTTP/1.1 200 OK Content-Type: application/json;charset=UTF-8 { "id": "d916a46b4557464c87c278cb37477bef" } 4.4.2 设备配置详情 请求方法 GET 请求地址 /v2/dm/rooms/deviceConfigs/{configId} Path参数 参数 数据类型 是否必需 描述 configId String 是 设备配置id HTTP状态码 返回值 描述 200 操作成功 400 客户端传参异常 401 鉴权失败 500 服务端异常 响应参数 参数 数据类型 描述 id String 设备配置id content String 配置内容 请求消息示例 httpGET /v2/dm/rooms/deviceConfigs/e33b8f25247e45de84dd4c74503b241a HTTP/1.1 Host: api.ymcs.yealink.com 响应消息示例 httpHTTP/1.1 200 Content-Type: application/json;charset=UTF-8 { "id": "8d07a56207074d26b61026099625b9e2", "content":"#!version:1.0.0.1\naccount.1.codec.g722.enable=1" } 4.4.3 推送设备配置 请求方法 POST 请求地址 /v2/dm/rooms/deviceConfigs/{configId}/push Path参数 参数 数据类型 是否必需 描述 configId String 是 配置ID HTTP状态码 返回值 描述 204 操作成功 400 客户端传参异常 401 鉴权失败 500 服务端异常 请求消息示例 httpPOST /v2/dm/rooms/deviceConfigs/e33b8f25247e45de84dd4c74503b241a/push HTTP/1.1 Host: api.ymcs.yealink.com 响应消息示例 httpHTTP/1.1 204 5.RPS管理 5.1 RPS设备管理 5.1.1 添加设备 请求方法 POST 请求地址 /v2/rps/devices Body参数 参数 数据类型 是否必需 描述 mac String 是 设备MAC，最小长度12，最大长度17 sn String 是 SN码，最大长度128 serverId String 否 服务器ID uniqueServerUrl String 否 服务器地址，最大长度256 authName String 否 鉴权用户名，最大长度128 password String 否 鉴权密码，最大长度128 remark String 否 备注，最大长度256 HTTP状态码 返回值 描述 201 操作成功，详见响应参数 400 客户端传参异常 401 鉴权失败 500 服务端异常 响应参数 参数 数据类型 描述 id String 设备id mac String 设备MAC sn String 分组id serverId String 服务器ID uniqueServerUrl String 服务器地址 authName String 鉴权用户名 remark String 备注 请求消息示例 httpPOST /v2/rps/devices HTTP/1.1 Host: api.ymcs.yealink.com Content-Type: application/json { "mac":"001565bbb1a9", "sn":"1106312113402006", "serverId":"ba7c7b13ed114a5fa6f12063ea9dff41", "remark":"SeakeerDevice", "authName":"Seakeer", "password":"654321" } 响应消息示例 httpHTTP/1.1 201 Created Content-Type: application/json;charset=UTF-8 { "id": "8d07a56207074d26b61026099625b9e2", "mac":"001565bbb1a9", "sn":"1106312113402006", "serverId":"ba7c7b13ed114a5fa6f12063ea9dff41", "remark":"SeakeerDevice", "authName":"Seakeer", } 5.1.2 批量添加设备 注意：每次最多100条 请求方法 POST 请求地址 /v2/rps/addDevices Body参数 参数 数据类型 是否必需 描述 mac String 是 设备MAC，最小长度12，最大长度17 sn String 是 SN码，最大长度128 serverId String 否 服务器ID uniqueServerUrl String 否 服务器地址，最大长度256 authName String 否 鉴权用户名，最大长度128 password String 否 鉴权密码，最大长度128 remark String 否 备注，最大长度256 HTTP状态码 返回值 描述 200 操作成功，详见响应参数 400 客户端传参异常 401 鉴权失败 500 服务端异常 响应参数 参数 数据类型 描述 total Integer 批量添加总条数 successCount Integer 成功添加总数量 failureCount Integer 失败总数量 errors AddError[] 错误信息 AddError对象 参数 数据类型 描述 mac String 设备MAC sn String 设备SN errorInfo String 错误信息 请求消息示例 httpPOST /v2/rps/addDevices HTTP/1.1 Host: api.ymcs.yealink.com Content-Type: application/json [{ "mac":"3a1565bbb1a9", "sn":"1106312113402006", "serverId":"ba7c7b13ed114a5fa6f12063ea9dff41", "remark":"SeakeerDevice", "authName":"Seakeer", "password":"654321" }] 响应消息示例 httpHTTP/1.1 200 OK Content-Type: application/json;charset=UTF-8 { "total": 1, "successCount":0, "failureCount":1, "errors":[{ "mac":"3a1565bbb1a9", "sn":"1106312113402006", "errorInfo":"Invalid MAC" }] } 5.1.3 添加设备不带SN 注意：每次最多100条 请求方法 POST 请求地址 /v2/rps/addDevicesByMac Body参数 参数 数据类型 是否必需 描述 mac String 是 设备MAC，最小长度12，最大长度17 serverId String 否 服务器ID uniqueServerUrl String 否 服务器地址，最大长度256 authName String 否 鉴权用户名，最大长度128 password String 否 鉴权密码，最大长度128 remark String 否 备注，最大长度256 HTTP状态码 返回值 描述 200 操作成功，详见响应参数 400 客户端传参异常 401 鉴权失败 500 服务端异常 响应参数 参数 数据类型 描述 total Integer 批量添加总条数 successCount Integer 成功添加总数量 failureCount Integer 失败总数量 errors AddError[] 错误信息 AddError对象 参数 数据类型 描述 mac String 设备MAC sn String 设备SN errorInfo String 错误信息 请求消息示例 httpPOST /v2/rps/addDevicesByMac HTTP/1.1 Host: api.ymcs.yealink.com Content-Type: application/json [{ "mac":"3a1565bbb1a9", "serverId":"ba7c7b13ed114a5fa6f12063ea9dff41", "remark":"SeakeerDevice", "authName":"Seakeer", "password":"654321" }] 响应消息示例 httpHTTP/1.1 200 OK Content-Type: application/json;charset=UTF-8 { "total": 1, "successCount":0, "failureCount":1, "errors":[{ "mac":"3a1565bbb1a9", "sn":"1106312113402006", "errorInfo":"Invalid MAC" }] } 5.1.4 编辑设备 请求方法 PATCH 请求地址 /v2/rps/devices/{deviceId} Path参数 参数 数据类型 是否必需 描述 deviceId String 是 设备ID Body参数 参数 数据类型 是否必需 描述 serverId String 否 服务器ID uniqueServerUrl String 否 服务器地址，最大长度256 authName String 否 鉴权用户名，最大长度128 password String 否 鉴权密码，最大长度128 remark String 否 备注，最大长度256 HTTP状态码 返回值 描述 204 操作成功 400 客户端传参异常 401 鉴权失败 500 服务端异常 请求消息示例 httpPATCH /v2/rps/devices/8d07a56207074d26b61026099625b9e2 HTTP/1.1 Host: api.ymcs.yealink.com Content-Type: application/json { "serverId":"ba7c7b13ed114a5fa6f12063ea9dff41", "remark":"SeakeerDevice", "authName":"Seakeer", "password":"654321" } 响应消息示例 httpHTTP/1.1 204 5.1.5 设备分页列表 请求方法 POST 请求地址 /v2/rps/listDevices Body参数 参数 数据类型 是否必需 描述 skip Long 否 跳过的记录数，默认为0 limit Long 否 获取的最大记录数，默认为10，最大500 autoCount Boolean 否 是否要响应总数量，建议在第一页查询时设置为true,其他页查询设置为false filter Filter 否 搜索参数 Filter对象定义 参数 数据类型 是否必需 描述 mac String 否 设备MAC,最大长度17,支持带:或-,如00:15:65:bb:b1:a1 HTTP状态码 返回值 描述 200 操作成功 400 客户端传参异常 401 鉴权失败 500 服务端异常 响应参数 参数 数据类型 描述 skip Long 偏移量 limit Long 返回最大数量 total Long 总数量 data Device[] Device信息数组 Device对象定义 参数 数据类型 描述 id String 设备id mac String 设备MAC sn String 设备SN码 serverId String 服务器ID serverName String 服务器名称 serverUrl String 服务器地址 uniqueServerUrl String 唯一服务器地址 ipAddress String IP地址 remark String 备注 dateRegistered Long 绑定时间 lastConnected Long 最后连接时间 请求消息示例 httpPOST /v2/rps/listDevices HTTP/1.1 Host: api.ymcs.yealink.com Content-Type: application/json { "skip": 0, "limit": 20, "autoCount": true, "filter":{ "mac":"001565bbb1a9" } } 响应消息示例 httpHTTP/1.1 200 Content-Type: application/json;charset=UTF-8 { "skip": 0, "limit": 10, "total": 1, "data":[{ "id": "8d07a56207074d26b61026099625b9e2", "mac":"001565bbb1a9", "sn":"1106312113402006", "serverId": "b25ac1016caf416a90d5ca1ee438153a", "serverName": "SeakeerServerTest", "serverUrl": "https://dm30-devtest.yealinkclient.com/dm.cfg", "ipAddress": null, "dateRegistered": 1542680124026, "lastConnected": null, "remark": "edit" }] } 5.1.6 设备详情 请求方法 GET 请求地址 /v2/rps/devices/{deviceId} PATH参数 参数 数据类型 是否必需 描述 deviceId String 是 设备ID 响应参数 参数 数据类型 描述 id String 设备id mac String 设备MAC sn String 设备SN码 serverId String 服务器ID serverName String 服务器名称 serverUrl String 服务器地址 uniqueServerUrl String 唯一服务器地址 ipAddress String IP地址 remark String 备注 dateRegistered Long 绑定时间 lastConnected Long 最后连接时间 authName String 鉴权用户名 请求消息示例 httpGET /v2/rps/devices/8d07a56207074d26b61026099625b9e2 HTTP/1.1 Host: api.ymcs.yealink.com 响应消息示例 httpHTTP/1.1 200 Content-Type: application/json;charset=UTF-8 { "id": "8d07a56207074d26b61026099625b9e2", "mac":"001565bbb1a9", "sn":"1106312113402006", "serverId": "b25ac1016caf416a90d5ca1ee438153a", "serverName": "SeakeerServerTest", "serverUrl": "https://dm30-devtest.yealinkclient.com/dm.cfg", "ipAddress": null, "dateRegistered": 1542680124026, "lastConnected": null, "remark": "edit", "authName": "edit", } 5.1.7 删除设备 请求方法 POST 请求地址 /v2/rps/delDevices Body参数 参数 数据类型 是否必需 描述 deviceIds String 是 设备ID列表，最大长度200 HTTP状态码 返回值 描述 200 操作成功 400 客户端传参异常 401 鉴权失败 500 服务端异常 响应参数 参数 数据类型 描述 total Integer 删除总条数 successCount Integer 成功删除总数量 failureCount Integer 失败总数量 errors OpError[] 错误信息 OpError对象 参数 数据类型 描述 field String 错误字段 msg String 错误信息 请求消息示例 httpPOST /v2/rps/delDevices HTTP/1.1 Host: api.ymcs.yealink.com Content-Type: application/json { "deviceIdType":"mac", "deviceIds":["001565bbb1a9","001567"] } 响应消息示例 httpHTTP/1.1 200 OK Content-Type: application/json;charset=UTF-8 { "total": 2, "successCount":1, "failureCount":1, "errors":[{ "field":"001567", "msg":"Invalid MAC" }] } 5.2 RPS服务器管理 5.2.1 添加服务器 请求方法 POST 请求地址 /v2/rps/servers Body参数: 请求参数 参数类型 是否必须 参数说明 serverName String 是 服务器名称，最大长度20 url String 是 服务器Url，最大长度512 authName String 否 鉴权用户名，最大长度32 password String 否 鉴权密码，最大长度32 certificateUrl String 否 证书url serverCertificateUrl String 否 服务器证书url serverCertificateEnable Boolean 否 是否开启自定义证书 serverCertificateEnableWithSHA256 Boolean 否 仅当证书类型非SHA256时开启 HTTP状态码 返回值 描述 201 操作成功，详见响应参数 400 客户端传参异常 401 鉴权失败 500 服务端异常 响应参数 参数 数据类型 描述 id String 服务器id serverName String 服务器名称 url String 服务器地址 authName String 鉴权用户名 请求消息示例 httpPOST /v2/rps/servers HTTP/1.1 Host: api.ymcs.yealink.com Content-Type: application/json { "serverName":"TestServer", "url":"https://https://www.yealink.com", "serverCertificateEnable": true, "serverCertificateEnableWithSHA256": true, "authName":"Seakeer", "password":"123456", "certificateUrl":"https://www.yealink.com/certificate" } 响应消息示例 httpHTTP/1.1 201 Created Content-Type: application/json;charset=UTF-8 { "id": "b38dea23a4e6458188799833b72d950f", "serverName": "TestServer", "url": "https://www.yealink.com", "authName": "Seakeer" } 5.2.2 编辑服务器 请求方法 PATCH 请求地址 /v2/rps/servers/{serverId} PATH参数 参数 数据类型 是否必需 描述 serverId String 是 服务器ID Body参数: 请求参数 参数类型 是否必须 参数说明 serverName String 是 服务器名称，最大长度20 url String 是 服务器Url，最大长度512 authName String 否 鉴权用户名，最大长度32 password String 否 鉴权密码，最大长度32 certificateUrl String 否 证书url serverCertificateUrl String 否 服务器证书url serverCertificateEnable Boolean 否 是否开启自定义证书 serverCertificateEnableWithSHA256 Boolean 否 仅当证书类型非SHA256时开启 HTTP状态码 返回值 描述 204 操作成功 400 客户端传参异常 401 鉴权失败 500 服务端异常 请求消息示例 httpPATCH /v2/rps/servers/b38dea23a4e6458188799833b72d950f HTTP/1.1 Host: api.ymcs.yealink.com Content-Type: application/json { "serverName":"YealinkServer", "url":"http://www.yealink.com", "authName":"Yealink", "password":"Yealink", "certificateUrl":"http://cer/cer.cer", "serverCertificateEnable": true, "serverCertificateEnableWithSHA256": true } 响应消息示例 httpHTTP/1.1 204 5.2.3 删除服务器 请求方法 POST 请求地址 /v2/rps/delServers Body参数 参数 数据类型 是否必需 描述 serverIds String[] 是 服务器id列表，最大长度200 响应参数 参数 数据类型 描述 total Integer 删除总条数 successCount Integer 成功删除总数量 failureCount Integer 失败总数量 errors OpError[] 错误信息 OpError对象 参数 数据类型 描述 field String 错误字段 msg String 错误信息 请求消息示例 httpPOST /v2/rps/delServers HTTP/1.1 Host: api.ymcs.yealink.com Content-Type: application/json { "serverIds":["b38dea23a4e6458188799833b72d950f","1234"] } 响应消息示例 httpHTTP/1.1 200 OK Content-Type: application/json;charset=UTF-8 { "total": 2, "successCount":1, "failureCount":1, "errors":[{ "field":"1234", "msg":"The resource does not exist or has been deleted" }] } 5.2.4 服务器详情 请求方法 GET 请求地址 /v2/rps/servers/{serverId} Path参数 参数 数据类型 是否必需 描述 serverId String 是 服务器ID 响应参数 参数 数据类型 描述 id String 服务器id serverName String 服务器名称 url String 服务器地址 authName String 鉴权用户名 certificateUrl String 证书url serverCertificateUrl String 服务器证书url serverCertificateEnable Boolean 是否开启自定义证书 serverCertificateEnableWithSHA256 Boolean 仅当证书类型非SHA256时开启 请求消息示例 httpGET /v2/rps/servers/b38dea23a4e6458188799833b72d950f HTTP/1.1 Host: api.ymcs.yealink.com 响应消息示例 httpHTTP/1.1 200 Content-Type: application/json;charset=UTF-8 { "id": "b38dea23a4e6458188799833b72d950f", "serverName": "TestServer", "url": "https://www.yealink.com", "authName": "Seakeer", "certificateUrl":"http://cer/cer.cer", "serverCertificateEnable": true, "serverCertificateEnableWithSHA256": true } 5.2.5 服务器分页列表 请求方法 POST 请求地址 /v2/rps/listServers Body参数 参数 数据类型 是否必需 描述 searchKey String 否 搜索关键词，支持服务器名称，URL搜索 skip Long 否 跳过的记录数，默认为0 limit Long 否 获取的最大记录数，默认为10，最大500 autoCount Boolean 否 是否要返回记录总数据量 filter Filter 否 搜索参数 Filter对象定义 参数 数据类型 是否必需 描述 name String 否 服务器名称 HTTP状态码 返回值 描述 200 操作成功 400 客户端传参异常 401 鉴权失败 500 服务端异常 响应参数 参数 数据类型 描述 skip Long 偏移量 limit Long 返回最大数量 total Long 总数据量 data Server[] Server信息数组 Server对象定义 参数 数据类型 描述 id String 服务器id serverName String 服务器名称 url String 服务器地址 authName String 鉴权用户名 请求消息示例 httpPOST /v2/rps/listServers HTTP/1.1 Host: api.ymcs.yealink.com Content-Type: application/json { "skip": 0, "limit": 20, "autoCount": true, "filter":{ "name":"test" } } 响应消息示例 httpHTTP/1.1 200 Content-Type: application/json;charset=UTF-8 { "skip": 0, "limit": 10, "total": 1, "data":[{ "id": "b38dea23a4e6458188799833b72d950f", "serverName": "test", "url": "https://www.yealink.com", "authName": "Seakeer" }] } 6.通话质量管理 6.1 分页列表 请求方法 POST 请求地址 /v2/dm/listQoes Body参数 参数名称 数据类型 是否必须 参数说明 skip Long 否 跳过的记录数，默认为0 limit Long 否 获取的最大记录数，默认为10，最大500 autoCount Boolean 否 是否要返回记录总数据量 filter Filter 否 搜索参数 Filter对象定义 参数 数据类型 是否必需 描述 mac String 否 设备MAC,最大长度17,支持带:或-,如00:15:65:bb:b1:a9 siteIds List false 要查询的站点ID列表 startTime Long false 要查询的起始时间 endTime Long false 要查询的结束时间 响应参数 参数 数据类型 描述 skip Long 偏移量 limit Long 返回最大数量 total Long 总数据量 data QoeInfo[] QoeInfo信息数组 QoeInfo对象定义 名称 类型 描述 id String QOE记录id deviceName String 设备名称 mac String MAC modelName String 设备型号 firmwareVersion String 固件版本 username String 账号-用户名 displayName String 账号-显示名称 siteName String 归属站点 quality String 通话质量 Good,Poor,Bad startTime long 通话开始时间戳 endTime long 通话结束时间戳 callerURI String 主叫URL,fromURI calleeURI String 被叫URL,toURI duration long 通话持续时间(ms) 请求消息示例 httpPOST /v2/dm/listQoes HTTP/1.1 Host: api.ymcs.yealink.com Content-Type: application/json { "skip":0, "limit":10, "filter":{ "startTime":1700876148000, "endTime":1703468148329, "siteIds":["126b25122362470daca91ae8ad038a27"] } } 响应消息示例 httpHTTP/1.1 200 Content-Type: application/json;charset=UTF-8 { "skip": 0, "limit": 10, "total": 1, "data":[{ "id": "a26b25122362470daca91ae8ad038a27", "deviceName": null, "mac": "805ec091cfc6", "modelName": "UNKNOW", "firmwareVersion": "108.86.0.57", "username": "8195", "displayName": "8195", "siteName": "global测试-baiyf", "quality": "Good", "startTime": 1660542991000, "endTime": 1660543218000, "callerURI": "\"8195\" <sip:8195@ume.yealink.com:5061>", "calleeURI": "<sip:77031@ume.yealink.com>", "duration": 227000 }] } 6.2 QOE详情 请求方法 GET 请求地址 /v2/dm/qoe/{qoeId} Path参数 参数 数据类型 是否必需 描述 qoeId String 是 QOE记录 ID 响应参数 名称 类型 描述 id String QOE记录id sessionId String 通话的会议ID reportTime long 通话数据上报时间 deviceName String 设备名称 mac String MAC modelName String 设备型号 firmwareVersion String 固件版本 ip String 设备IP deviceType String 设备类型：audio,video username String 账号-用户名 displayName String 账号-显示名称 serverType String 账号类型 siteName String 归属站点 quality String 通话质量 Good,Poor,Bad startTime long 通话开始时间戳 endTime long 通话结束时间戳 callId String 通话Id callerURI String 主叫URL,fromURI calleeURI String 被叫URL,toURI isCaller boolean 是否为主叫 callType String 通话类型 confURI String 配置url time long 当前时间 event String 事件 duration long 通话持续时间(ms) inJitterAvg int 输入抖动平均值 inJitterMax int 输入抖动最大值 inLossRateAvg double 输入丢失率平均值 inLossRateMax double 输入丢失率最大值 inLossTotal int 输入丢失值 inDelayAvg int 输入延迟平均值 inDelayMax int 输入延迟最大值 inListenMosAvg double 输入接听语音质量评分平均值 inListenMosMin double 输入接听语音质量评分最小值 inConversationalMosAvg double 输入对话语音质量评分平均值 inConversationalMosMin double 输入对话语音质量评分最小值 inReceivePacketTotal int 入包总数 inPayloadName String 输入负载名称 outJitterAvg int 输出抖动平均值 outJitterMax int 输出抖动最大值 outLossRateAvg double 输出丢失率平均值 outLossRateMax double 输出丢失率最大值 outLossTotal int 输出丢失值 outDelayAvg int 输出延迟平均值 outDelayMax int 输出延迟最大值 outListenMosAvg double 输出接听语音质量评分平均值 outListenMosMin double 输出接听语音质量评分最小值 outConversationalMosAvg double 输出对话语音质量评分平均值 outConversationalMosMin double 输出对话语音质量评分最小值 outReceivePacketTotal int 出包总数 outPayloadName String 输出负载名称 请求消息示例 httpGET /v2/dm/qoe/c5a56e74bab546c8bc3cccf2e82aeb0c HTTP/1.1 Host: api.ymcs.yealink.com 响应消息示例 httpHTTP/1.1 200 Content-Type: application/json;charset=UTF-8 { "id": "a26b25122362470daca91ae8ad038a27", "sessionId": "805ec091cfc6-0_934910374@10.50.144.6", "reportTime": 1660543237204, "deviceName": null, "mac": "805ec091cfc6", "modelName": "UNKNOW", "firmwareVersion": "108.86.0.57", "ip": "10.50.144.6", "deviceType": "UNKNOW", "username": "8195", "displayName": "8195", "serverType": "SIP", "siteName": "global测试-baiyf", "quality": "Good", "startTime": 1660542991000, "endTime": 1660543218000, "callId": "0_934910374@10.50.144.6", "callerURI": "\"8195\" <sip:8195@ume.yealink.com:5061>", "calleeURI": "<sip:77031@ume.yealink.com>", "remoteIP": null, "callType": "p2p", "confURI": null, "time": 1660543218000, "event": "0", "duration": 227000, "inJitterAvg": 3, "inJitterMax": 3, "inLossRateAvg": 0.0, "inLossRateMax": 0.0, "inDelayAvg": 5, "inDelayMax": 5, "inListenMosAvg": 4.0, "inListenMosMin": 4.0, "inConversationalMosAvg": 4.0, "inConversationalMosMin": 4.0, "inReceivePacketTotal": 11299, "inPayloadName": "G722", "outJitterAvg": 3, "outJitterMax": 4, "outLossRateAvg": 0.0, "outLossRateMax": 0.0, "outLossTotal": 0, "outDelayAvg": 5, "outDelayMax": 5, "outListenMosAvg": 4.4, "outListenMosMin": 4.0, "outConversationalMosAvg": 4.4, "outConversationalMosMin": 4.4, "outReceivePacketTotal": 11333, "outPayloadName": "G722", } 7.统计 7.1 设备总数 请求方法 GET 请求地址 /v2/dm/statistics/deviceCount Query参数 参数名称 数据类型 是否必须 参数说明 deviceStatus Integer false 设备状态，1:在线， 0:离线，-1:未上报, 不传此参数时获取总数 deviceType Integer false 设备类型 响应参数 名称 类型 说明 total Long 设备数量 请求消息示例 httpGET /v2/dm/statistics/deviceCount?deviceStatus=1 HTTP/1.1 Host: api.ymcs.yealink.com 响应消息示例 httpHTTP/1.1 200 Content-Type: application/json;charset=UTF-8 { "total":100 } 7.2 QOE统计 请求方法 POST 请求地址 /v2/dm/statistics/qoe Body参数 参数名称 数据类型 是否必须 参数说明 siteIds String[] false 要统计的站点ID列表 startTime Long false 要统计的起始时间，此值要和endTime一起使用，否则 不生效 endTime Long false 要统计的结束时间, 此值要和startTime一起使用，否则不生效 响应参数 名称 类型 说明 total long 通话总数量 badPercentage double 质量差的占比 badTotal long 质量差 goodPercentage double 质量好的占比 goodTotal long 质量好 meetingPercentage double 会议总数百分比 meetingTotal long 会议总数 p2pPercentage double p2p通话百分比 p2pTotal long p2p通话总数 poorPercentage double 质量一般的占比 poorTotal long 质量一般 voiceMailPercentage double 语音邮件总数 voiceMailTotal long 语音邮件总数 请求消息示例 httpPOST /v2/dm/statistics/qoe HTTP/1.1 Host: api.ymcs.yealink.com Content-Type: application/json { "startTime":1700876148000, "endTime":1703468148329, "siteIds":["126b25122362470daca91ae8ad038a27"] } 响应消息示例 httpHTTP/1.1 200 Content-Type: application/json;charset=UTF-8 { "total":25, "goodTotal": 24, "poorTotal": 1, "badTotal": 0, "goodPercentage": 0.96, "poorPercentage": 0.04, "badPercentage": 0.0, "p2pTotal": 25, "meetingTotal": 0, "voiceMailTotal": 0, "p2pPercentage": 1.0, "meetingPercentage": 0.0, "voiceMailPercentage": 0.0 } 8.型号管理 8.1 型号列表 请求方法 GET 请求地址 /v2/dm/models Query参数 参数 数据类型 是否必需 描述 deviceType Integer 是 设备类型 1: Phone Device 3:Room Device 响应参数 参数 数据类型 描述 data Model[] 型号信息数组 Model对象定义 参数 数据类型 描述 id String 型号id name String 型号名称 请求消息示例 httpGET /v2/dm/models?deviceType=1 HTTP/1.1 Host: api.ymcs.yealink.com 响应消息示例 httpHTTP/1.1 200 Content-Type: application/json;charset=UTF-8 [{ "id": "61e659e4d78d42ebada88ef1eb751b64", "name":"SIP-T54S", },{ "id":"02c47b640c3046dc86853c9ccfd37dd0", "name":"SIP-T31P" }] 9.站点管理 9.1 添加站点 请求方法 POST 请求地址 /v2/dm/sites Body参数 参数 数据类型 是否必需 描述 name String 是 站点名称，最大长度128 parentId String 是 上级站点ID description String 否 描述，最大长度1024 HTTP状态码 返回值 描述 201 操作成功，详见响应参数 400 客户端传参异常 401 鉴权失败 500 服务端异常 响应参数 参数 数据类型 描述 id String 站点id name String 站点名称 parentId String 上级站点ID siteNumber String 站点编码 请求消息示例 httpPOST /v2/dm/sites HTTP/1.1 Host: api.ymcs.yealink.com Content-Type: application/json { "name":"site1", "parentId":"d3a6ff43f2154b868ba1157eb3677c1e", "description":"site1" } 响应消息示例 httpHTTP/1.1 201 Created Content-Type: application/json;charset=UTF-8 { "id": "0006d62003684754b11c09c5d94ea687", "name":"site1", "parentId":"d3a6ff43f2154b868ba1157eb3677c1e", "siteNumber":"ofpb5gvg" } 9.2 编辑站点 请求方法 PATCH 请求地址 /v2/dm/sites/{siteId} Path参数 参数 数据类型 是否必需 描述 siteId String 是 站点ID Body参数 参数 数据类型 是否必需 描述 name String 否 站点名称 parentId String 否 上级站点ID description String 否 描述，最大长度1024 HTTP状态码 返回值 描述 204 操作成功 400 客户端传参异常 401 鉴权失败 500 服务端异常 请求消息示例 httpPATCH /v2/dm/sites/0006d62003684754b11c09c5d94ea687 HTTP/1.1 Host: api.ymcs.yealink.com Content-Type: application/json { "name":"site11", "description":"site11", "parentId":"d3a6ff43f2154b868ba1157eb3677c1e" } 响应消息示例 httpHTTP/1.1 204 9.3 删除站点 请求方法 DELETE 请求地址 /v2/dm/sites/{siteId} PATH参数 参数 数据类型 是否必需 描述 siteId String 是 站点id 请求消息示例 httpDELETE /v2/dm/sites/e33b8f25247e45de84dd4c74503b241a HTTP/1.1 Host: api.ymcs.yealink.com 响应消息示例 httpHTTP/1.1 204 9.4 站点列表 请求方法 POST 请求地址 /v2/dm/listSites Body参数 参数名称 数据类型 是否必须 参数说明 skip Long 否 跳过的记录数，默认为0 limit Long 否 获取的最大记录数，默认为10，最大500 autoCount Boolean 否 是否要返回记录总数据量 filter Filter 否 搜索参数 Filter对象定义 参数 数据类型 是否必需 描述 name String 否 站点名称 响应参数 参数 数据类型 描述 data Site[] Site信息数组 Site对象定义 参数 数据类型 描述 id String 站点id parentId String 上级站点ID name String 站点名称 level Integer 站点层级，0表示根站点 sequence Integer 站点在层级中的序号 请求消息示例 httpPOST /v2/dm/listSites HTTP/1.1 Host: api.ymcs.yealink.com Content-Type: application/json { "skip":0, "limit":10, "filter":{ "name":"test" } } 响应消息示例 httpHTTP/1.1 200 Content-Type: application/json;charset=UTF-8 { "skip": 0, "limit": 10, "total": 1, "data":[{ "id":"1e876bc0fca24b728eeb3e52bbfebf5e", "parentId":"23b63cac1f6d4134b5459a4face901c3", "name":"test", "level":2, "sequence":1, }] } 9.5 站点详情 请求方法 GET 请求地址 /v2/dm/sites/{siteId} Path参数 参数 数据类型 是否必需 描述 siteId String 是 站点ID 响应参数 参数 数据类型 描述 id String 站点id parentId String 上级站点id name String 站点名称 siteNumber String 站点编码 description String 描述信息 请求消息示例 httpGET /v2/dm/sites/288ff0d0bd4948b0a95785ba7bc72a8e HTTP/1.1 Host: api.ymcs.yealink.com HTTP状态码 返回值 描述 200 操作成功 400 客户端传参异常 401 鉴权失败 500 服务端异常 响应消息示例 httpHTTP/1.1 200 Content-Type: application/json;charset=UTF-8 { "id": "288ff0d0bd4948b0a95785ba7bc72a8e", "name":"site1", "parentId":"d3a6ff43f2154b868ba1157eb3677c1e", "siteNumber":"ofpb5gvg", "description":"site1" } 10.资源管理 10.1 固件管理 10.1.1 固件列表 请求方法 POST 请求地址 /v2/dm/listFirmwares Body参数 参数 数据类型 是否必需 描述 skip Long 否 跳过的记录数，默认为0 limit Long 否 获取的最大记录数，默认为10，最大500 autoCount Boolean 否 是否要响应总数量，建议在第一页查询时为true,后续翻页时传false filter Filter 否 搜索参数 Filter对象定义 参数 数据类型 是否必需 描述 modelId String 否 固件型号ID firmwareType Integer 否 固件类型 0：主设备 1:配件 deviceType Integer 否 设备类型 1: Phone Device 3:Room Device HTTP状态码 返回值 描述 200 操作成功 400 客户端传参异常 401 鉴权失败 500 服务端异常 响应参数 参数 数据类型 描述 skip Long 偏移量 limit Long 返回最大数量 total Long 总数量 data Firmware[] Firmware信息数组 Firmware对象定义 参数 数据类型 描述 id String 固件id name String 固件名称 deviceType Integer 设备类型 1: Phone Device 3:Room Device firmwareType Integer 固件类型 0：主设备 1:配件 version String 固件版本号 请求消息示例 httpPOST /v2/dm/listFirmwares HTTP/1.1 Host: api.ymcs.yealink.com Content-Type: application/json { "skip": 0, "limit": 10, "autoCount": true, "filter":{ "firmwareType":0, "deviceType":1 } } 响应消息示例 httpHTTP/1.1 200 Content-Type: application/json;charset=UTF-8 { "skip": 0, "limit": 10, "total": 1, "data":[{ "id": "01d7ae1897f7418dad2d26609329be38", "name":"t54s firmware", "deviceType":1, "firmwareType":0, "version":"108.85.3.19", }] } 10.1.2 固件详情 请求方法 GET 请求地址 /v2/dm/firmwares/{firmwareId} Path参数 参数 数据类型 是否必需 描述 firmwareId String 是 固件ID HTTP状态码 返回值 描述 200 操作成功，详见响应参数 400 客户端传参异常 401 鉴权失败 500 服务端异常 响应参数 参数 数据类型 描述 id String 固件id name String 固件名称 filename String 固件文件名称 deviceType Integer 设备类型 1: Phone Device 3:Room Device firmwareType Integer 固件类型 0：主设备 1:配件 downloadUrl String 下载地址 version String 固件版本号 supportModels String[] 支持的型号列表 siteId String 所属站点ID description String 固件描述 请求消息示例 httpGET /v2/dm/firmwares/01d7ae1897f7418dad2d26609329be38 HTTP/1.1 Host: api.ymcs.yealink.com 响应消息示例 httpHTTP/1.1 200 Content-Type: application/json;charset=UTF-8 { "id": "01d7ae1897f7418dad2d26609329be38", "name":"t54s firmware", "filename":"t54s.rom", "deviceType":1, "firmwareType":0, "downloadUrl":"https://resources.yiot.yealink.com/yiot-manager/api/v1/terminal/resource/download/69847884d3be4327b86bffd0513c4572/1/T46S(T48S,T42S,T41S)-66.86.0.15.rom", "version":"108.85.3.19", "supportModels":["SIP-T54S"], "siteId":"ee06cddee78948a298fc12565a35cdbe" } 10.1.3 官方固件列表 请求方法 POST 请求地址 /v2/dm/listOfficalFirmwares Body参数 参数 数据类型 是否必需 描述 skip Long 否 跳过的记录数，默认为0 limit Long 否 获取的最大记录数，默认为10，最大500 autoCount Boolean 否 是否要响应总数量，建议在第一页查询时为true,后续翻页时传false filter Filter 是 搜索参数 Filter对象定义 参数 数据类型 是否必需 描述 modelId String 是 固件型号ID HTTP状态码 返回值 描述 200 操作成功 400 客户端传参异常 401 鉴权失败 500 服务端异常 响应参数 参数 数据类型 描述 skip Long 偏移量 limit Long 返回最大数量 total Long 总数量 data Firmware[] Firmware信息数组 Firmware对象定义 参数 数据类型 描述 id String 固件id name String 固件名称 version String 固件版本号 请求消息示例 httpPOST /v2/dm/listOfficalFirmwares HTTP/1.1 Host: api.ymcs.yealink.com Content-Type: application/json { "skip": 0, "limit": 10, "autoCount": true, "filter":{ "modelId":"23a5da55f3534f84abc7956a9f183330" } } 响应消息示例 httpHTTP/1.1 200 Content-Type: application/json;charset=UTF-8 { "skip": 0, "limit": 10, "total": 1, "data":[{ "id": "01d7ae1897f7418dad2d26609329be38", "name":"t54s firmware", "version":"108.85.3.19" }] } 10.1.4 推送固件 请求方法 POST 请求地址 /v2/dm/firmwares/{firmwareId}/push PATH参数 参数 数据类型 是否必需 描述 firmwareId String 是 固件ID Body参数 参数 数据类型 是否必需 描述 deviceIds String[] 是 设备ID列表，最大长度200 deviceType Integer 是 设备类型 1: Phone Device 3:Room Device HTTP状态码 返回值 描述 200 操作成功 400 客户端传参异常 401 鉴权失败 500 服务端异常 响应参数 参数 数据类型 描述 total Integer 删除总条数 successCount Integer 成功删除总数量 failureCount Integer 失败总数量 errors OpError[] 错误信息 OpError对象 参数 数据类型 描述 field String 错误字段 msg String 错误信息 请求消息示例 httpPOST /v2/dm/firmwares/09972370b360461d868e3e02f9cdec77/push HTTP/1.1 Host: api.ymcs.yealink.com Content-Type: application/json { "deviceIds":["0006572538f74e8683716cf961caa95b","00099642675e4d4bb5e91fd9ae5ce585"], "deviceType":1 } 响应消息示例 httpHTTP/1.1 200 OK Content-Type: application/json;charset=UTF-8 { "total": 2, "successCount":1, "failureCount":1, "errors":[{ "field":"00099642675e4d4bb5e91fd9ae5ce585", "msg":"The resource does not exist or has been deleted" }] } 10.1.5 推送官方固件 请求方法 POST 请求地址 /v2/dm/officalFirmwares/{officalFirmwareId}/push PATH参数 参数 数据类型 是否必需 描述 officalFirmwareId String 是 官方固件ID Body参数 参数 数据类型 是否必需 描述 deviceIds String[] 是 设备ID列表，最大长度200 deviceType Integer 是 设备类型 1: Phone Device 3:Room Device HTTP状态码 返回值 描述 200 操作成功 400 客户端传参异常 401 鉴权失败 500 服务端异常 响应参数 参数 数据类型 描述 total Integer 删除总条数 successCount Integer 成功删除总数量 failureCount Integer 失败总数量 errors OpError[] 错误信息 OpError对象 参数 数据类型 描述 field String 错误字段 msg String 错误信息 请求消息示例 httpPOST /v2/dm/officalFirmwares/09972370b360461d868e3e02f9cdec77/push HTTP/1.1 Host: api.ymcs.yealink.com Content-Type: application/json { "deviceIds":["0006572538f74e8683716cf961caa95b","00099642675e4d4bb5e91fd9ae5ce585"], "deviceType":1 } 响应消息示例 httpHTTP/1.1 200 OK Content-Type: application/json;charset=UTF-8 { "total": 2, "successCount":1, "failureCount":1, "errors":[{ "field":"00099642675e4d4bb5e91fd9ae5ce585", "msg":"The resource does not exist or has been deleted" }] } 11.设备诊断 使用说明：诊断接口成功调用后，从响应中获取diagnosisId, 定时轮询(建议每10秒)查询诊断状态，如果状态响应成功(status=success),则可根据响应中的url获取下载诊断文件的地址，并根据地址获取文件。 11.1 获取网口类型列表 请求方法 GET 请求地址 /v2/dm/devices/{deviceId}/networkInterfaces Path参数 参数 数据类型 是否必需 描述 deviceId String 是 设备ID HTTP状态码 返回值 描述 200 操作成功，详见响应参数 400 客户端传参异常 401 鉴权失败 500 服务端异常 响应参数 参数 数据类型 描述 data String[] 类型列表 请求消息示例 httpGET /v2/dm/devices/8d07a56207074d26b61026099625b9e2/networkInterfaces HTTP/1.1 Host: api.ymcs.yealink.com 响应消息示例 httpHTTP/1.1 200 Content-Type: application/json;charset=UTF-8 ["wan","wlan0","ext0"] 11.2 开始抓包 请求方法 PUT 请求地址 /v2/dm/devices/{deviceId}/startPacketCapture Path参数 参数 数据类型 是否必需 描述 deviceId String 是 设备ID Body参数 参数 数据类型 是否必需 描述 networkInterface String 是 网络端口，具体值从网口类型列表中获取，一般有 wan(广域网端口),ext0(外接电话线口),wlan0(无线局域网端口), 默认wan type Integer 否 抓包类型，0 – Custom, 1 –SIP or H245 or H225, 2 –RTP,3 –Not RTP filter String 否 抓包过滤信息，只有当抓包类型=0时才需要此值 duration Integer 是 抓包最大时长, 单位秒 ，区间：180~3600 HTTP状态码 返回值 描述 200 操作成功，详见响应参数 400 客户端传参异常 401 鉴权失败 500 服务端异常 响应参数 参数 数据类型 描述 diagnosisId String 诊断会话ID 请求消息示例 httpPUT /v2/dm/devices/8d07a56207074d26b61026099625b9e2/startPacketCapture HTTP/1.1 Host: api.ymcs.yealink.com Content-Type: application/json { "networkInterface":"wan", "type":0， "duration":180 } 响应消息示例 httpHTTP/1.1 200 Content-Type: application/json;charset=UTF-8 { "diagnosisId": "0006d62003684754b11c09c5d94ea687", } 11.3 结束抓包 请求方法 PUT 请求地址 /v2/dm/devices/{deviceId}/stopPacketCapture Path参数 参数 数据类型 是否必需 描述 deviceId String 是 设备ID Body参数 参数 数据类型 是否必需 描述 diagnosisId String 是 诊断ID HTTP状态码 返回值 描述 204 操作成功 400 客户端传参异常 401 鉴权失败 500 服务端异常 请求消息示例 httpPUT /v2/dm/devices/8d07a56207074d26b61026099625b9e2/stopPacketCapture HTTP/1.1 Host: api.ymcs.yealink.com Content-Type: application/json { "diagnosisId": "0006d62003684754b11c09c5d94ea687" } 响应消息示例 httpHTTP/1.1 204 11.4 截屏 请求方法 PUT 请求地址 /v2/dm/devices/{deviceId}/captureScreen Path参数 参数 数据类型 是否必需 描述 deviceId String 是 设备ID HTTP状态码 返回值 描述 200 操作成功，详见响应参数 400 客户端传参异常 401 鉴权失败 500 服务端异常 响应参数 参数 数据类型 描述 diagnosisId String 诊断ID 请求消息示例 httpPUT /v2/dm/devices/8d07a56207074d26b61026099625b9e2/captureScreen HTTP/1.1 Host: api.ymcs.yealink.com 响应消息示例 httpHTTP/1.1 200 Content-Type: application/json;charset=UTF-8 { "diagnosisId": "0006d62003684754b11c09c5d94ea687", } 11.5 导出系统日志 请求方法 PUT 请求地址 /v2/dm/devices/{deviceId}/exportSyslog Path参数 参数 数据类型 是否必需 描述 deviceId String 是 设备ID HTTP状态码 返回值 描述 200 操作成功，详见响应参数 400 客户端传参异常 401 鉴权失败 500 服务端异常 响应参数 参数 数据类型 描述 diagnosisId String 诊断ID 请求消息示例 httpPUT /v2/dm/devices/8d07a56207074d26b61026099625b9e2/exportSyslog HTTP/1.1 Host: api.ymcs.yealink.com 响应消息示例 httpHTTP/1.1 200 Content-Type: application/json;charset=UTF-8 { "diagnosisId": "0006d62003684754b11c09c5d94ea687", } 11.6 导出配置文件 请求方法 PUT 请求地址 /v2/dm/devices/{deviceId}/exportConfig Path参数 参数 数据类型 是否必需 描述 deviceId String 是 设备ID HTTP状态码 返回值 描述 200 操作成功 400 客户端传参异常 401 鉴权失败 500 服务端异常 请求消息示例 httpPUT /v2/dm/devices/8d07a56207074d26b61026099625b9e2/exportConfig HTTP/1.1 Host: api.ymcs.yealink.com 响应消息示例 httpHTTP/1.1 200 Content-Type: application/json;charset=UTF-8 { "diagnosisId": "0006d62003684754b11c09c5d94ea687", } 11.7 检测网络-ping 请求方法 PUT 请求地址 /v2/dm/devices/{deviceId}/ping Path参数 参数 数据类型 是否必需 描述 deviceId String 是 设备ID Body参数 参数 数据类型 是否必需 描述 host String 是 要ping的IP/域名 times Integer 是 次数，最小1，最大30 HTTP状态码 返回值 描述 200 操作成功，详见响应参数 400 客户端传参异常 401 鉴权失败 500 服务端异常 响应参数 参数 数据类型 描述 diagnosisId String 诊断ID 请求消息示例 httpPUT /v2/dm/devices/8d07a56207074d26b61026099625b9e2/ping HTTP/1.1 Host: api.ymcs.yealink.com Content-Type: application/json { "host":"www.google.com", "times":1 } 响应消息示例 httpHTTP/1.1 200 Content-Type: application/json;charset=UTF-8 { "diagnosisId": "0006d62003684754b11c09c5d94ea687", } 11.8 检测网络-traceroute 请求方法 PUT 请求地址 /v2/dm/devices/{deviceId}/traceroute Path参数 参数 数据类型 是否必需 描述 deviceId String 是 设备ID Body参数 参数 数据类型 是否必需 描述 host String 是 要traceroute的IP/域名 times Integer 是 次数，最小1，最大30 HTTP状态码 返回值 描述 200 操作成功，详见响应参数 400 客户端传参异常 401 鉴权失败 500 服务端异常 响应参数 参数 数据类型 描述 diagnosisId String 诊断ID 请求消息示例 httpPUT /v2/dm/devices/8d07a56207074d26b61026099625b9e2/traceroute HTTP/1.1 Host: api.ymcs.yealink.com Content-Type: application/json { "host":"www.google.com", "times":1 } 响应消息示例 httpHTTP/1.1 200 Content-Type: application/json;charset=UTF-8 { "diagnosisId": "0006d62003684754b11c09c5d94ea687", } 11.9 查询诊断状态 请求方法 GET 请求地址 /v2/dm/diagnosis/{diagnosisId}/status Path参数 参数 数据类型 是否必需 描述 diagnosisId String 是 诊断ID HTTP状态码 返回值 描述 200 操作成功，详见响应参数 400 客户端传参异常 401 鉴权失败 500 服务端异常 响应参数 参数 数据类型 描述 deviceId String 设备ID status String 诊断状态: inprogress: 进行中 success: 成功 failure:失败 url String 文件下载地址，当status = success时可用 请求消息示例 httpGET /v2/dm/diagnosis/0006d62003684754b11c09c5d94ea687/status HTTP/1.1 Host: api.ymcs.yealink.com 响应消息示例 httpHTTP/1.1 200 Content-Type: application/json;charset=UTF-8 { "deviceId": "0006d62003684754b11c09c5d94ea687", "status":"success", "url":https://yealinkussdev.blob.core.windows.net/single-12/allinone-10.122.131.12-uss%2F40ae7a23e493446695519cc44ad0a17d.txt?sv=2021-06-08&spr=https%2Chttp&se=2024-01-10T02%3A06%3A01Z&sr=b&sp=r&sig=JHco76T2o4idcO09mjvjj02FYFJEJW%2BvDf2RgLR%2BFAs%3D&rscd=attachment%3Bfilename%3DLog_001565bbb1a9_20240110020043_yiot123.txt" } 12.告警管理 12.1 告警列表 请求方法 POST 请求地址 /v2/dm/listAlarms Body参数 参数 数据类型 是否必需 描述 skip Long 否 跳过的记录数，默认为0 limit Long 否 获取的最大记录数，默认为10，最大500 autoCount Boolean 否 是否要响应总数量，建议在第一页查询时为true,后续翻页时传false filter Filter 否 搜索参数 Filter对象定义 参数 数据类型 是否必需 描述 mac String 否 设备MAC模糊搜索关键字,最大长度17,支持带:或-,如00:15:65:bb:b1:a9 deviceType Integer 否 设备类型, 1: Phone Device 3: Room Device ，不填写时为全部 HTTP状态码 返回值 描述 200 操作成功 400 客户端传参异常 401 鉴权失败 500 服务端异常 响应参数 参数 数据类型 描述 skip Long 偏移量 limit Long 返回最大数量 total Long 总数量 data Alarm[] Alarm信息数组 Alarm对象定义 参数 数据类型 描述 id String 告警id event String 告警事件名称 level Integer 告警等级 1-Minor 2-Major 3-Critical mac String MAC model String 型号 ip String IP siteName String 站点 status Integer 处理状态 1-active 2-solve 3-ignore firstAlarmTime Long 首次告警时间 lastAlarmTime Long 最后告警时间 请求消息示例 httpPOST /v2/dm/listAlarms HTTP/1.1 Host: api.ymcs.yealink.com Content-Type: application/json { "skip": 0, "limit": 10, "autoCount": true, "filter":{ "mac":"001565" } } 响应消息示例 httpHTTP/1.1 200 Content-Type: application/json;charset=UTF-8 { "skip": 0, "limit": 10, "total": 1, "data":[{ "id": "01d7ae1897f7418dad2d26609329be38", "event":"Offline", "level":3, "mac":"001565bbb1a9", "model":"SIP-T54S", "ip":"10.50.198.156", "siteName":"test", "status":1, "firstAlarmTime":1737082468768 }] } 13.操作日志管理 13.1 操作日志列表 请求方法 POST 请求地址 /v2/dm/listOpLogs Body参数 参数 数据类型 是否必需 描述 skip Long 否 跳过的记录数，默认为0 limit Long 否 获取的最大记录数，默认为10，最大500 autoCount Boolean 否 是否要响应总数量，建议在第一页查询时为true,后续翻页时传false filter Filter 是 搜索参数 Filter对象定义 参数 数据类型 是否必需 描述 startTime Long 否 开始时间 endTime Long 否 结束时间 HTTP状态码 返回值 描述 200 操作成功 400 客户端传参异常 401 鉴权失败 500 服务端异常 响应参数 参数 数据类型 描述 skip Long 偏移量 limit Long 返回最大数量 total Long 总数量 data Log[] Log信息数组 Log对象定义 参数 数据类型 描述 module String 日志模块 operationType String 日志类型 operationObject String 日志操作对象 operator String 操作者 ip String IP createTime Long 时间 result String 结果 请求消息示例 httpPOST /v2/dm/listOpLogs HTTP/1.1 Host: api.ymcs.yealink.com Content-Type: application/json { "skip": 0, "limit": 10, "autoCount": true, "filter":{ "startTime":1737099689158, "endTime":1738205662000 } } 响应消息示例 httpHTTP/1.1 200 Content-Type: application/json;charset=UTF-8 { "skip": 0, "limit": 10, "total": 1, "data":[{ "module":"i18n.yiot.backend.module.device.management", "operationTypetype":"i18n.yiot.backend.operation.device.management.restart", "operationObject":"805ec0985cd2", "operator":"yiot123@yealink.com", "ip":"10.122.131.12", "createTime":"1736999161388", "result":"success" }] }