跳到主要内容

开放接口入门

访问鉴权​

开放接口访问需要以下信息进行系统鉴权

  • AppID
  • AppKey

获得AppID与AppKey​

  1. 使用具有开放接口权限的账号登录系统，超级管理员与系统管理权限也具备开放接口权限

  2. 从 我的 → 我的信息 → 开放接口配置 中取得AppID与AppKey

    如果不存在鉴权信息，点击 新建，然后 保存 即可

    提示

    开放接口如果有权限限制。则受限于当前人员的系统权限

访问方式​

开放接口根据接口类型不同支持多种访问模式

使用网络通过服务端调用​

指令直接发送给 服务端，需要指定指令的 目标坐席或目标设备

使用 服务端通用设备指令 发送指令

支持 系统级接口 与 方案级接口

使用网络通过设备调用​

指令之间发送给设备，需要第三方系统存有相关 设备 IP 地址

使用 设备端通用指令 发送指令

支持 方案级接口

部署 3IS 控制器端使用 USB 通过设备调用​

指令发送到 本地 ( 127.0.0.1 ) ，需要在本地部署 3IS 控制器端

使用 设备端通用指令 发送指令

支持 方案级接口

各模式对比​

模式通讯通道目标地址端口设备接入要求指令目标接口类型
使用网络通过服务端调用网络 ( 有线 / 无线 )服务端 IP默认27000网络 / USB坐席 / 设备系统 / 方案
使用网络通过设备调用网络 ( 有线 / 无线 )设备地址27100网络/方案
3IS控制器端使用USB通过设备调用控制器端 USB127.0.0.127100USB/方案

两种接口级别​

系统支持 2 种级别的开放接口

系统级接口​

  1. 特点

    • 系统级接口不依赖模板与方案
    • 仅支持单一接口访问方式 使用网络通过服务端调用
    • 不允许定制

  2. 指令

    使用 服务端通用设备指令 发送指令

  3. 参数

    参见各系统级接口文档

方案级接口​

  1. 特点

    • 依赖于方案
    • 创建模版后生效
    • 可根据客户需求定制
    • 可定制接口参数与内容
    • 可定制接口行为与逻辑
    • 可定制交互内容
    • 支持所有 3 种接口访问方式

  2. 指令

    使用 设备端通用指令 或 服务端通用设备指令 发送指令

  3. 参数

    详见 下面的方案级接口参数详解

方案级接口文档​

包含有接口的方案可通过以下方式访问接口文档

  • 管理 → 授权许可

  • 内容 → 交互模板 → 交互模板编辑

  • 通过文档中心查询

  • 通过技术支持获取

方案级接口参数详解​

  1. 输入参数

    参考 设备端通用指令 或 服务端通用设备指令

    根据接口目标不同，分为 设备 与 服务端 两种类型，其参数具体差异如下表

    参数说明类型服务端设备端
    appidAppIDlong✓✓
    appkeyAppKeystring✓✓
    seat指定坐席，坐席编号或者坐席名称 注意：使用名称时，名称在系统中不唯一，仅使用第一个取得的名称 device和seat可取其中之一string○
    device指定设备，设备名称 device和seat可取其中之一string○
    command指令名称，自定义的指令名称string✓✓
    timeout指令超时时间，单位：秒long○
    sync指令是否同步执行，即是否等待指令执行结果再返回bool○
    data指令数据 指令数据由方案指令决定，需参阅方案说明object✓✓

    ✓ 必须参数

    ○ 可选参数

    提示

    💡 data 数据项内容由方案进行指定

    设备类型示例：

    {
        "appid":4,
        "appkey":"UcH5HjT71zXWeUGxCCGhMsEs6nzSzLzs1oEBQOgzryLnjS6d",
        "command":"Evaluate",
        "timeout":10,
        "data":{
            "timeout":6,
            "keys":[5,4,3]
        }
    }

    服务端类型示例

    {
        "appid":4,
        "appkey":"ID8wlo9Pt8BfYsGRTjr39rX9xSXqzrm7yFC8nkh6NceTvrQQ",
        "seat":"班牌1",
        "command":"Test",
        "data":{
            "message":"这是一个指令测试"
        }
    }

  2. 输出参数

    参考 设备端通用指令 或 服务端通用设备指令

    参数说明类型
    success操作是否成功bool
    message操作结果描述，当success为错误时，为错误码字符串，见错误码表string
    dataobject

    其中 data 数据项根据接口目标不同而有所差异

    • 目标为 设备 时

      data 为返回结果数据 数据结构参考方案接口说明

    • 目标为 服务端 时

      data数据结构为

      参数说明类型
      items结果数据项 如发送的目标是坐席，且坐席中存在多个设备，则会存在多个数据array
      item.uid指令uid 如果sync模式执行，需使用此uid获取指令结果string
      item.ip目标设备IPstring
      item.name目标设备名称string
      item.time指令结果时间 (yyyy-mm-dd hh:mm)string
      item.data执行结果 根据方案指令不一样而不同，具体查阅各方案指令说明object
      item.timeout指令在设备端执行超时时，为truebool
      uid指令uid

    设备类型示例:

    {
        "success": true,
        "data": {
            "value": 4,
            "uid": 13
        }
    }

    服务端类型示例 (sync模式) :

    {
        "success": true,
        "data": {
            "items": [{
                "uid": "xGoF5HmoZOf3ZoeB61",
                "ip": " 192.168.1.190",
                "name": "11",
                "time": 638340207158651150,
                "data": {
                    "value": 3
                }
            }],
            "uid": "xGoF5HmoZOf3ZoeB61"
        }
    }

通用错误信息​

错误说明
open.service.authorize.error授权错误，appkey或appid不匹配
open.service.restricted.error白名单限制，不在白名单中
open.service.authorize.notfound授权错误，appid不存在
open.service.unknown.error未知接口错误
open.service.executing接口执行