[TOC]
## **一、合作商说明**
图灵机器人合作商接口主要针对开发者及企业用户开放，方便开发者及企业用户通过接口的方式对机器人进行批量生成、管理及日常查询等操作。
## **二、功能说明**
**合作商账号功能包含“合作商管理页”及“合作商接口文档”**
**合作商管理后台** 可对接口生成的机器人进行查看、升级、管理。
**合作商接口文档** 开放了“机器人创建管理模块”，“语料库增删改查模块”、“娱乐技能控制模块”三大模块接口。
---
### ****1.合作商管理后台****
#### **基础信息页**
**可开通机器人个数：** 当前合作商账号最多可创建100个机器人，若需要更高创建机器人权限可与图灵机器人联系付费购买；
**服务到期时间：** 服务使用时间默认为1年，若服务即将到期可与图灵机器人联系延长使用期限；
**剩余调用次数：** 即为当前所有子机器人剩余可调用的次数；
**今日合计调用次数：** 所有子机器人当日总调用次数；
#### **机器人管理页**
**日最大调用次数：** 该机器人每日最大调用次数，可通过权限升级接口增加调用量。
**累计调用量：**该机器人自创建以来累积调用次数；
**今日调用量：** 该机器人当日调用次数；
**操作：** “禁用”则该机器人无法使用，“启用”则该机器人恢复使用；
---
### ****2.合作商接口文档****
#### ****机器人创建管理模块****
**（1）批量生成：** 可通过合作商接口批量生成多个机器人。
**（2）多级账户：** 多级账户由父账号和子机器人组成，父账号有机器人管理权，子机器人可用聊天对话、语料库、生活技能等服务。
**（3）权限分配：** 合作商可根据用户业务需求，分配或升级子机器人的调用量、语料内容、技能数量等使用权限。
**（4）属性自定义：** 开放机器人属性自定义接口，可让用户自己修改姓名、性别、年龄、爸爸妈妈等个性化属性。
#### ****语料库增删改查模块****
**（1）语料导入：** 可通过接口在语料库中批量上传问题、答案及相似问题等内容。
**（2）语料删改：** 可对语料库已有内容进行查询、删除、修改。
**（3）匹配度设置：** 可对语料库相似度匹配阈值进行调控，让用户自主选择“完全匹配”或“模糊匹配”模式。
#### ****娱乐技能控制模块****
开放24个生活技能，合作商可通过接口控制各个机器人的技能开关。
## **三、接口说明**
### ****1.接口约定****
#### ****传输格式****
JSON
#### ****编码方式****
UTF-8（调用图灵API的各个环节的编码方式均为UTF-8）
#### ****指定header****
Content-Type 为 application/json
#### ****请求方式****
HTTP POST
#### ****统一返回错误码****
| 异常码 | 说明 |
| --- | --- |
|3\*\* |操作错误 |
|301 |缺少必要参数，参数格式错误 |
|4\*\* |权限错误 |
|401 |APIkey不存在或不具有权限 |
|5\*\* |接口传输错误|
### ****2.机器人管理接口****
#### ****2.1机器人创建****
（1）请求接口
http://openapi.turingapi.com/v1/robot/create
（2）请求数据
```
{
"user": "user",
"data": {
"name":"小灵儿",
"level": 1,
"faq": 1000,
"match": 70
}
}
```
（3）请求数据
| 参数 | 类型 | 是否必须 |说明
| --- | --- | --- | --- | --- |
|user|string|Y|用户名|
|name|string|Y| 机器人名称 |
|level|int|Y| 机器人每日调用上限（整数*1000次)|
|faq|int|N| 知识库存储总量|
|match|int|N| 知识库匹配度|
（4）返回数据
```
{
"code": 0,
"data": {
"apikey": "apikey",
"level": 1,
"faq": 1000,
"name": "小灵儿",
"match": 70
}
}
```
#### ****2.2机器人权限升级****
（1）请求接口
http://openapi.turingapi.com/v1/robot/upgrate
（2）请求数据
```
{
"apikey":"apikey",
"data":{
"level":1,
"faq":2000
}
}
```
（3）参数说明
| 参数 | 类型 | 是否必须 | 说明 |
| --- | --- | --- | --- | --- |
|apikey|string|Y| 机器人Apikey |
|level|string|Y| 机器人每日调用上限（整数*1000次） |
|faq|int|N| 知识库匹配度|
（4）返回数据
```
{
code: 0,
data:{
"level":level,
"faq":faq
}
}
```
#### ****2.3机器人属性设置****
（1）请求接口
http://openapi.turingapi.com/v1/robot/profile
（2）请求数据
```
{
"apikey": " apikey ",
"data": {
"nickname": "hellorobot",
"gender": "F/M",
"age": 22,
"image": "http://图像地址",
"father": "father",
"mother": "mother"
}
}
```
（3）参数说明
| 参数 | 类型 | 是否必须 | 说明 |
| --- | --- | --- | --- | --- |
|apikey|string|Y|机器人apikey|
|nickname|string|N|机器人昵称|
|gender|string|N|性别（男M，女F）|
|age|int|N|年龄|
|image|string|N|头像（url）|
|father|string|N|爸爸名字|
|mother|string|N|妈妈名字|
（4）返回数据
```
{
"code": 0,
"data": {
"nickname": "",
"gender": "F/M",
"age": 22,
"image": "http://图像地址",
"father": "father",
"mother": "mother"
}
}
```
#### ****2.4机器人信息查询****
（1）请求接口
http://openapi.turingapi.com/v1/robot/info
（2）请求数据
```
{
"apikey":" apikey "
}
```
（3）参数说明
| 参数 | 类型 | 是否必须 | 说明 |
| --- | --- | --- | --- | --- |
|apikey|string|Y|机器人apikey|
（4）返回数据
```
{
code:0,
data:{
"faq":{},
"robotSetting":{},
"ability":{}
}
}
```
#### ****2.5机器人禁用开启****
（1）请求接口
http://openapi.turingapi.com/v1/robot/locked
（2）请求数据
```
{
"apikey": "",
"data":{
"locked":true
}
}
```
（3）参数说明
| 参数 | 类型 | 是否必须 | 说明 |
| --- | --- | --- | --- | --- |
|apikey|string|Y|机器人apikey|
|locked|boolean|Y|禁用：true 启用：false|
（4）返回数据
```
{
"code": 0,
"data": {
"locked": true
}
}
```
#### ****2.6机器人删除****
（1）请求接口
http://openapi.turingapi.com/v1/robot/delete
（2）请求数据
```
{
"apikey": ""
}
```
（3）参数说明
| 参数 | 类型 | 是否必须 | 说明 |
| --- | --- | --- | --- | --- |
|apikey|string|Y|机器人apikey|
（4）返回数据
```
{
"code": 0,
"data": {
"delete": "success"
}
}
```
### ****3.语料库管理接口****
#### ****3.1语料库匹配度****
（1）请求接口
http://openapi.turingapi.com/v1/kb/match
（2）请求数据
```
{
"apikey":" apikey ",
"data":{
"match":60
}
}
```
（3）参数说明
| 参数 | 类型 | 是否必须 | 说明 |
| --- | --- | --- | --- | --- |
|apikey|string|Y|机器人apikey|
|match|int|Y|语料库匹配度|
（4）返回数据
```
{
code: 0,
data:{
"match":60
}
}
```
#### ****3.2语料库新增****
（1）请求接口
http://openapi.turingapi.com/v1/kb/import
（2）请求数据
```
{
"apikey":" apikey ",
"data":{
"list":[
{"question":"question",
"answer":"answer",
"simiQuestion":["simiQuestion1","simiQuestion2","simiQuestion3"]
}]
}
}
```
（3）参数说明
| 参数 | 类型 | 是否必须 | 说明 |
| --- | --- | --- | --- | --- |
|apikey|string|Y|机器人apikey|
|question|string|Y|问题|
|answer|string|Y|答案|
|simiQuestion|array|N|相似问题|
（4）返回数据
```
{
"code": 0,
"data": {
"successNum": 1,
"knowledgeList": [
{
"answer": "answer",
"question": "question"，
"id": "2146008",
"time": "2016-10-17 11:14:38",
"label_id": 0,
}
]
}
}
```
#### ****3.3语料库修改****
（1）请求接口
http://openapi.turingapi.com/v1/kb/update
（2）请求数据
```
{
"apikey":" apikey ",
"data":{
"list":[
{
"id":"1",
"question":"question",
"answer":"answer",
"simiQuestion":["新相似问题","新相似问题"]}
]
}
}
```
（3）参数说明
| 参数 | 类型 | 是否必须 | 说明 |
| --- | --- | --- | --- | --- |
|apikey|string|Y|机器人apikey|
|id|int|Y|数据id|
|question|string|N|新的问题|
|answer|string|N|新的答案|
|simiQuestion|array|N|新的相似问题|
（4）返回数据
```
{
"code":0,
"data": {
"successNum": 2
}
}
```
#### ****3.4语料库删除****
（1）请求接口
http://openapi.turingapi.com/v1/kb/delete
（2）请求数据
```
{
"apikey": "apikey",
"data": {
"clear": false,
"ids": [1,2,3]
}
}
```
（3）参数说明
目前支持两种形式的删除接口。
1）如果有"clear"的字段而且 clear 的布尔值为 true，则执行清空操作；
2）第二种会根据用户传过来的 ids 中 json 数组里面的 id，删除对应的记录；
| 参数 | 类型 | 是否必须 | 说明 |
| --- | --- | --- | --- | --- |
|apikey|string|Y|机器人apikey|
|clear|bool|Y|是否执行清空|
|ids|array|N|待删除的问题id|
（4）返回数据
```
{
"code":0,
"data":"3"
}
```
#### ****3.5语料库查询****
（1）请求接口
http://openapi.turingapi.com/v1/kb/select
（2）请求数据
```
{
"apikey":" apikey ",
"data": {
"pages":{
"pageNumber":1,
"pageSize":10,
"searchBy": "question"
}
}
}
```
（3）参数说明
| 参数 | 类型 | 是否必须 | 说明 |
| --- | --- | --- | --- | --- |
|apikey|string|Y|机器人apikey|
|pageNumber|int|Y|页数|
|pageSize|int|Y|每页显示行数|
|searchBy|string|Y|查询的关键词|
（4）返回数据
```
{
"code": 0,
"data": {
"totalCount": 2,
"knowledgeCount": 2,
"knowledgeList": [{
"id": "2",
"simiQuestion": ["相似问题 1","相似问题 2","相似问题 3" ],
"time": "2017-02-15 10:14:25",
"answer": "answer2",
"state": 1,
"label_id": 0,
"question": "question2"
}]
}
}
```
### ****4.机器人技能接口****
（1）请求接口
http://openapi.turingapi.com/v1/robot/ability
（2）请求数据
```
{
"apikey": " apikey ",
"data": {
"list": [{
"news": false
}
]
}
}
```
（3）参数说明
| 参数 | 类型 | 是否必须 | 说明 |
| --- | --- | --- | --- | --- |
|apikey|string|Y|机器人apikey|
|list|array|Y|功能及其开关操作列表|
（4）功能名称对应表
| 功能名称| 英文名称|
| --- | --- | --- | --- | --- | --- |
|数字计算|number_count|
|问答百科|question_answer|
|语料库|knowledgebase|
|中英互译 |translation|
|聊天对话|chat|
|笑话大全 |joke|
|故事大全|story|
|星座运势|constellation|
|脑筋急转弯|brain_twists|
|歇后语| xiehouyu|
|绕口令|tongue_twister|
|顺口溜|jingle|
|天气查询|weather|
|快递查询|express|
|城市邮编|postcode|
（5）返回数据
```
{
code:0,
data:{
list:[
{"appname":true/false},
{"appname":true/false}
]
}
}
```
