接口功能规范

当前版本: V6.2
旧版本呼叫中心接口参考 (opens new window)

统一认证

智齿开放接口在基于 Json Web Token(JWT) 基础上实现标准的 API 进行授权访问的机制，满足用户安全设置的需求。

基本流程及使用说明

流程上是这样的：

1. 客户端使用 appId、app_secret 来请求服务器
2. 服务器进行验证认证的信息
3. 服务器通过验证发送给用户 access_token
4. 客户端存储 access_token;
5. 并在每次请求时附送上这个 access_token 值 (存在 head 里的参数 Authorization）
6. 服务端验证 access_token 值，并返回数据
7. access_token 在申请后会携带超时时间，客户端应该在 access_token 超时时间过半时重新获取 token。
8. 如果服务器验证 access_token 过期, 返回 status 401

座席级授权接口

● 座席token接口定义

座席级 token 用于 JSSDK 及 UISDK 请求获取 token

https://openapi.soboten.com/tokens/agent

请求参数:

参数	类型	必填	描述
responseType	String	是	请求的jwt类型，目前仅可使用：token
appId	String	是	用户唯一标识
currentTime	Long	是	当前服务器时间（时间戳（毫秒），例如：2022-06-25 15:49:33 的时间戳 1656143373000）
sign	String	是	签名 ，计算方法为 MD5(app_id+current_time+response_type+app_secret)
agentId	String	否	座席id
agentNo	String	否	座席工号

注意：接口的参数中agentId与agentNumber中至少必须存在一个，当存在agentId时，agentNumber无效。 请求示例

curl -X post https://openapi.soboten.com/tokens/agent -D
'{\
    "responseType":"token",\
    "appId":"b86fc8142f784bfb9215d45df64a17ea",\
    "currentTime":"1627462929415",\
    "sign":"fdf6066cfc12e73d7ebc571235c8be45",\
    "agentNo":"1008"
}'

成功时返回

{
"response_type":"token",
"access_token":"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE0ODUxNDA5ODQsImlhdCI6MTQ4NTEzNzM4NCwiaXNzIjoiYWNtZS5jb20iLCJzdWIiOiIyOWFjMGMxOC0wYjRhLTQyY2YtODJmYy0wM2Q1NzAzMThhMWQiLCJhcHBsaWNhdGlvbklkIjoiNzkxMDM3MzQtOTdhYi00ZDFhLWFmMzctZTAwNmQwNWQyOTUyIiwicm9sZXMiOltdfQ.Mp0Pcwsz5VECK11Kf2ZZNF_SMKu5CgBeLN9ZOP04kZo",
"expires_in": 86400000,
"realm":"third",
"domain":"sobot"
}

失败时返回

{
  "errcode": 400,
  "error_desc":"invalid params"  
}

● 使用access_token

对智齿所有对外的 API 都需要增加 HTTP Authorization header。 范例如下:

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE0ODUxNDA5ODQsImlhdCI6MTQ4NTEzNzM4NCwiaXNzIjoiYWNtZS5jb20iLCJzdWIiOiIyOWFjMGMxOC0wYjRhLTQyY2YtODJmYy0wM2Q1NzAzMThhMWQiLCJhcHBsaWNhdGlvbklkIjoiNzkxMDM3MzQtOTdhYi00ZDFhLWFmMzctZTAwNmQwNWQyOTUyIiwicm9sZXMiOltdfQ.Mp0Pcwsz5VECK11Kf2ZZNF_SMKu5CgBeLN9ZOP04kZo

● 错误编码

Status	Message	Description
400	invalid params	获取token是非法的参数
401	Unauthorized	无效的token
403	Forbidden	非法的请求资源

公司级授权接口

● 公司 token 接口定义

公司级 token 用于访问 HTTP 开放接口 请求获取 token

https://openapi.soboten.com/tokens/company

请求参数：

参数	类型	必填	描述
responseType	String	是	请求的jwt类型，目前仅可使用：token
appId	String	是	用户唯一标识
currentTime	Long	是	当前服务器时间（时间戳（毫秒），例如：2022-06-25 15:49:33 的时间戳 1656143373000）
sign	String	是	签名 ，计算方法为 MD5(app_id+current_time+response_type+app_secret)

请求示例

curl -X post https://openapi.soboten.com/tokens/company -D
'{\
    "responseType":"token",\
    "appId":"b86fc8142f784bfb9215d45df64a17ea",\
    "currentTime":"1627462929415",\
    "sign":"fdf6066cfc12e73d7ebc571235c8be45"\
}'

成功时返回

{
"response_type":"token",
"access_token":"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE0ODUxNDA5ODQsImlhdCI6MTQ4NTEzNzM4NCwiaXNzIjoiYWNtZS5jb20iLCJzdWIiOiIyOWFjMGMxOC0wYjRhLTQyY2YtODJmYy0wM2Q1NzAzMThhMWQiLCJhcHBsaWNhdGlvbklkIjoiNzkxMDM3MzQtOTdhYi00ZDFhLWFmMzctZTAwNmQwNWQyOTUyIiwicm9sZXMiOltdfQ.Mp0Pcwsz5VECK11Kf2ZZNF_SMKu5CgBeLN9ZOP04kZo",
"expires_in": 86400000,
"realm":"third",
"domain":"sobot"
}

失败时返回

{
  "code": 400,
  "error_desc":"invalid params"  
}

错误处理

统一的错误处理

{
  "apiVersion": "6.2", //api版本
  "status": "Failure", //Success 或者 Failure
  "message": "对不起,系统维护中，请稍等.", // 给使用用户提示错误信息; 通过Accept-Language显示多语言.默认中文
  "code": 500,  //http status code
  "reason": "error.message.label",  //错误信息key label
  "kind": "MainCDRInfo",  //实体类型，在这包括 MainCDRInfo,PartyCDRInfo
  "metaData": {
      "creatorId":"1f9ce5af91d8-1ecc12b03aa7a8755ad2",
      "creationTime":1617173030902,
      "updateUserId":"44c8f4014e53c4677736c4c8c26a7c0d",
      "updatedTime":1617173096236
  }
}