===== 工单(客服)接口 =====

此接口仅供客服使用。

==== JSON格式 ====

^ 名称          ^ 类型       ^ 只读          ^ 必填          ^ 注释 ^
| ticketId     | int     | 是           | 否            | 工单ID，系统自动生成 |
| url          | string      | 是           | 否            | 该工单的url地址 |
| subject      | string      | 否           | 是            | 工单标题 |
| descript     | string      | 否           | 否            | 工单描述，即第一条工单回复的文本内容 |
| ticketSource | int     | 否           | 否            | 工单来源：1--远程，2--聊天，3--呼叫中心，4--留言，5--系统创建，7--API，8--工单模板发布，9--邮件接入 |
| ticketType   | int     | 否           | 否            | 工单类型：1--问题，2--事务，3--故障，4--任务 |
| priorityLevel | int     | 否           | 否            | 工单优先级：1--低，2--正常，3--高，4--紧急 |
| ticketStatus| int    | 否           | 是| 工单状态：1--新建，2--已开启，3--待回应，4--已解决，5--自动关闭，6--手动关闭 |
| custUserId| int     | 否           | 否            | 联系人ID |
| agentId| int    | 否           | 否            | 服务商ID |
| createrId| int     | 否           | 否            | 创建人ID |
| servicerUserId| int     | 否           | 否            | 客服ID |
| servicerGroupId| int     | 否           | 否            | 客服组ID |
| ccUserIdList| string    | 否           | 否            | 抄送人ID列表|
|ccGroupIdList| string |否 | 否 |抄送组ID列表|
|ticketTemplateId| int | 否 | 否 | 工单模板ID。**一个工单有哪些字段取决于工单模板，所以设置工单的字段值，必须传工单模板ID**| 
| tagList| string| 否           | 否            | 工单标签列表|
| createDT| date| 是| 否            | 创建时间|
| updateDT| date| 是| 否            | 更新时间|
| custom_fields| array| 否           | 否            | 工单自定义字段，不支持验证码、评星等特殊自定义字段|
| tables| array| 否           | 否            | 表单类型的工单自定义字段，新建或修改工单时需用到该参数|

====JSON示例====
<code>
{
     "ticketId": 1,
     "url": "https://www.bangwo8.com/api/v1/tickets/1.json",
     "subject": "产品咨询",
     "description": "帮我吧是什么？",
     "ticketSource": 0,
     "ticketType": 1,
     "priorityLevel": 2,
     "ticketStatus": 0,
     "custUserId": 121,
     "agentId": 37809,
     "createrId": 0,
     "servicerUserId": 234,
     "servicerGroupId": 0,
     "ccUserIdList": "123,456,789",
     "ccGroupIdList": "2432,3455,2323"
     "tagList": "vip客户,普通客户",
     "createDT": "2017-05-04 14:08:22",
     "updateDT": "2017-05-04 14:08:22",
     "custom_fields": [
      {
          "key": "field_1",//自定义字段的唯一标识，可从帮我吧后台查看
          "value": "4334"
      },
      {
          "key": "field_3",//自定义字段的唯一标识，可从帮我吧后台查看
          "value": "1" //复选框
      },
      {
          "key": "field_2",
          "value": "下拉菜单的某一项"
      },
      {
          "key": "field_4",
          "value": "附件的下载地址" //附件多个时，以逗号分隔
      }
     ],
     "tables":[
         {//第一个表单
          "custom_fields_key": "", //工单表单字段的唯一标识，可从帮我吧后台查看
          "tableData":[
                {//表单的第一行数据
                   "fieldkey": "第一列内容",//fieldkey为表头项的唯一标识
                   "fieldkey": "第二列内容",//fieldkey为表头项的唯一标识
                    ...
                },
                {//表单的第二行数据
                   "fieldkey": "第一列内容",//fieldkey为表头项的唯一标识
                   "fieldkey": "第二列内容",//fieldkey为表头项的唯一标识
                   ...
                }
                ...
           ]
        },
        {//第二个表单
          "custom_fields_key": "", //工单表单字段的唯一标识，可从帮我吧后台查看
          "tableData":[
                {//表单的第一行数据
                   "fieldkey": "第一列内容",//fieldkey为表头项的唯一标识
                   "fieldkey": "第二列内容",//fieldkey为表头项的唯一标识
                    ...
                },
                {//表单的第二行数据
                   "fieldkey": "第一列内容",//fieldkey为表头项的唯一标识
                   "fieldkey": "第二列内容",//fieldkey为表头项的唯一标识
                   ...
                }
                ...
           ]
        }
        ...
        
     ]
} 
</code>

==== 工单列表 ====

<code>
GET /api/v1/tickets.json
</code>

**查询参数**
^ 名称      ^ 必要的       ^ 类型          ^注释   ^
| created_start    | 否     | string        | 按创建时间查询：开始时间，包含当天 |
| created_end    | 否     | string        | 按创建时间查询：结束时间，包含当天|
| updated_start    | 否     | string        | 按更新时间查询：开始时间，包含当天 |
| updated_end    | 否     | string        | 按更新时间查询：结束时间，包含当天 |
| created_order    | 否     | string        | 按创建时间排序：asc（升序），desc（降序） |
| updated_order    | 否     | string        | 按更新时间排序：asc（升序），desc（降序） |
| status_order    | 否     | string        | 按工单状态排序：asc（升序），desc（降序）|
| page    | 否     | number | 页码，默认为 1 |
| per_page | 否     | number | 每页大小，默认为 100 |

//说明：默认按编码升序返回。时间参数（created_start、created_end、updated_start、updated_end）格式为“2012-01-01 00:00:00”。//



**调用者权限**
  管理员

也可以使用下面的接口
<code>
/*查看服务商下某个客户的工单*/
GET /api/v1/companies/{company_id}/tickets.json
/*查看服务商下某个客户的某个联系人的工单*/
GET /api/v1/users/{user_id}/tickets.json
</code>


**调用示例**
<code>
curl https://www.bangwo8.com/api/v1/tickets.json \
  -v -u {account}:{password}
</code>

**返回值示例**
<code>
Status: 200 OK

{
    "tickets":[
        {
            "ticketId":110,
            "subject":"产品咨询",
            "custom_fields":[
                {
                    "key":"field_14",
                    "value":"15997"
                },
                {
                    "key":"sfsk",
                    "value":"1"
                },
                {
                    "key":"cpxx",
                    "value":[
                        {
                            "cpdm":"001.005",
                            "cpmc":"铺助面板",
                            "zjm":"PZMB",
                            "ggxh":"A6020青古"
                        },
                        {
                            "cpdm":"001.005",
                            "cpmc":"铺助面板",
                            "zjm":"PZMB",
                            "ggxh":"A6020青古"
                        }
                    ]
                }
            ]
        }
    ],
    "count":42,
    "next_page":"https://www.bangwo8.com/api/v1/tickets.json?per_page=40&page=2",
    "previous_page":null
}
</code>


==== 查看工单 ====
<code>
GET /api/v1/tickets/{id}.json
</code>
**
调用者权限**
    管理员
  
**调用示例**
<code>
curl https://www.bangwo8.com/api/v1/tickets/{id}.json \
  -v -u {account}:{password}
</code>

**返回值示例**
<code>
Status: 200 OK

{
	"ticket": {
		"ticketId": 110,
		"subject": "产品咨询",
		...
	}
}
</code>

==== 查看多个工单 ====
<code>
GET /api/v1/tickets/show_many.json?ids={ids}
</code>
//说明：工单id要以逗号分隔。此接口最多返回100个工单。//\\
**
调用者权限**
    管理员
**调用示例**
<code>
curl https://www.bangwo8.com/api/v1/tickets/show_many.json?ids=110,111,112 \
 -v -u {account}:{password}
</code>

**返回值示例**
<code>
Status: 200 OK

{
  "tickets": [
    {
      "ticketId": 110,
      "subject": "产品咨询",
      ...
    },
    {
      "ticketId": 111,
      "subject": "产品服务"
      ...
    },
    ...
  ]
}
</code>

==== 创建工单 ====
<code>
POST /api/v1/tickets.json
</code>

**调用者权限**
    管理员
**请求参数**
^ 名称      ^ 类型      ^ 必须的          ^描述^
| subject    | string     |是        |工单标题|
| ticketReply    | object |是 | 工单描述，请参考[[:工单:工单回复|工单回复]]|
| custUserId| int|否 | 联系人id，说明该工单是为该客户解决问题|
| custUser| object|否 | 联系人信息|
| servicerUserId| int|否 | 受理客服id|
| servicerGroupId| int|否 | 受理客服组id|
| ccUserIdList| string|否 | 抄送客服id列表|
| ccGroupIdList| string|否 | 抄送客服组id列表|
| ticketSource| int|否 | 工单来源：1--远程，2--聊天，3--呼叫中心，4--留言，5--系统创建，7--API，8--工单模板发布，9--邮件接入|
| ticketType| int|否 |工单类型：1--问题，2--事务，3--故障，4--任务|
| priorityLevel| int|否 | 工单优先级：1--低，2--正常，3--高，4--紧急|
| ticketStatus| int|否 | 工单状态：1--新建，2--已开启，3--待回应，4--已解决，5--自动关闭，6--手动关闭|
| ticketTemplateId| int |否 |如果需要传工单来源、类型、优先级、状态或者自定义字段，则必须传该字段值|
| tagList| int|否 | 工单标签列表，以逗号分隔|
| custom_fields| array|否 | 工单自定义字段|

//custUser参数说明//\\
目前支持的联系人信息有mobilephone、name、fixnumber、qq、email，如果要使用该参数，则mobilephone是必需的，其余是选填项。如果数据库里没有该联系人信息，则会自动创建。
<code>
"custUser":{ 
	"mobilephone": 13240138438,
	"name": "张三" ,
	"fixnumber": "010-63701717" ,
	"qq": "601100987" ,
	"email": "bangwo8@126.com" ,
}
</code>
//自定义字段说明// \\
key是字段的唯一标识，可从“帮我吧后台-》工单自定义字段”查看；value是该字段的具体值。
<code>
"custom_fields": [
     {
      "key": "field_1",
      "value": "文本框内容"
     },
     {
      "key": "field_2",
      "value": "下拉框的某选项"
     }
    ]
</code>

//上传工单附件// \\
工单附件包含两种类型：自定义字段类型的附件和工单回复里的附件。无论是哪种类型的附件，都需要先调用[[:工单:工单回复|工单回复]]里的上传附件接口，调用成功后，系统会返回相应的附件token，然后将相应参数置位此token即可。

<code>
/*自定义字段附件*/
"custom_fields": [
	{
            "key": "field_4", //附件自定义字段的唯一标识
            "value": "15761b339251466e9fec23698503eb53,12343b339251466e9fec23698503eb54" //token
        }
]

/*工单回复里的附件*/
"ticketReply": {
        "attachments": [
           "15761b339251466e9fec23698503eb53", //附件1的token
           "12343b339251466e9fec23698503eb54" //附件2的token
        ]
}
</code> 
//创建带表单类型的工单// \\
表单类型的字段与普通自定义字段传值方式不一样，不在“custom_fields”进行传值，而是在“tables”里传值，“tables”与“custom_fields”是并列关系。
<code>
"tables":[
        {
            "custom_fields_key":"",//工单表单字段的唯一标识
            "tableData":[
                {//第一行数据
                    "cpdm":"001.005",
                    "cpmc":"铺助面板",
                    "zjm":"PZMB",
                    "ggxh":"A6020青古"
                },
                {//第二行数据
                    "cpdm":"001.005",
                    "cpmc":"铺助面板",
                    "zjm":"PZMB",
                    "ggxh":"A6020青古"
                }
            ]
        }
    ]
</code>

\\
**调用示例**
<code>
curl https://www.bangwo8.com/api/v1/tickets.json \
  -d '{"ticket": {"subject": "产品咨询", "ticketReply": { "replyMsg":"你好，我想咨询下帮我吧产品" }}}' \
  -H "Content-Type: application/json" -v -u {account}:{password} -X POST
</code>

**返回值示例**
<code>
Status: 200 OK
Location: https://www.bangwo8.com/api/v1/tickets/{id}.json

{
  "ticket": {
    "ticketId": 110,
    "subject": "产品咨询",
    ...
  }
}
</code>

==== 更新工单 ====
<code>
PUT /api/v1/tickets/{id}.json
</code>

**调用者权限**
  所有客服
 
**请求参数**
^ 名称      ^ 类型      ^ 必需的          ^描述^
| ticketReply    | object |是 | 工单描述，请参考[[:工单:工单回复|工单回复]]|
| servicerUserId| int|否 | 受理客服id|
| servicerGroupId| int|否 | 受理客服组id|
| ccUserIdList| int|否 | 抄送客服id列表，如果是抄送的客服分组，则传客服分组id，多个id之间以逗号分隔|
| ticketSource| int|否 | 工单来源：1--远程，2--聊天，3--呼叫中心，4--留言，5--系统创建|
| ticketType| int|否 |工单类型：1--问题，2--事务，3--故障，4--任务|
| priorityLevel| int|否 | 工单优先级：1--低，2--正常，3--高，4--紧急|
| ticketStatus| int|否 | 工单状态：1--新建，2--已开启，3--待回应，4--已解决，5--自动关闭，6--手动关闭|
| ticketTemplateId | int | 否 | 工单模板|
| tagList| int|否 | 工单标签列表，以逗号分隔|
| custom_fields| array|否 | 工单自定义字段|

**调用示例**
<code>
curl https://www.bangwo8.com/api/v1/tickets/3232.json \
  -H "Content-Type: application/json" \
  -d '{"ticket": {"ticketStatus": "open", "ticketReply": { "replyMsg": "这里是工单回复文本内容", "replyUserId": 233434 }}}' \
  -v -u {account}:{password} -X PUT
</code>

**返回值示例**
<code>
Status: 200 OK

{
  "ticket": {
     "ticketId": 3232,
     "subject": "这里是工单标题",
     "ticketStatus":  "已解决",
     ...
  }
}
</code>

====更新多个工单====
<code>
PUT /api/v1/tickets/update_many.json
PUT /api/v1/tickets/update_many.json?ids={ids}
</code>

//说明：一次最多更新100个工单//

**调用者权限**
  所有客服

**调用示例** \\
//对不同的工单进行相同的处理，调用下面的接口：// 
<code>
PUT /api/v1/tickets/update_many.json?ids=111,222,333
</code>
<code>
{
  "ticket": {
    "ticketStatus": "已解决"
  }
}
</code>

//对不同的工单进行不同的处理，调用下面的接口：// 
<code>
PUT /api/v1/tickets/update_many.json
</code>
<code>
{
  "tickets": [
    { "ticketId": 111, "ticketStatus": "已解决" },
    { "ticketId": 222, "ticketStatus": "待回应" }
  ]
}
</code>

**返回值示例**
<code>
Status: 200 OK

{
  "results": [
    {
      "ticketId": 111,
      "success": false,
      "error_log": "字段值不合法"
    },
    {
      "ticketId": 222,
      "success": true,
      "error_log": ""
    }
  ]
}
</code>

====搜索工单====
<code>
GET /api/v1/tickets/search.json
</code>

**调用者权限**
  所有客服
  
**请求参数**
^名称 ^类型 ^必需的 ^注释 ^
|query |string |是 |搜索内容|
|sort_by |string | 否 |按时间排序，目前支持：createDT-创建时间，updateDT-更新时间|
|sort_order| string | 否 | 按升序还是降序返回，取值为：asc-升序，desc-降序，默认为降序|

query参数说明
^搜索内容 ^返回结果 ^
|query=2444 | 模糊搜索，返回工单编号、工单标题或者联系人姓名包含该内容的工单|
|query=ticketStatus:2,4| 搜索工单状态为已开启或已解决的工单|
|query=field_1:454 | 返回自定义字段唯一标识为“field_1”的内容里面包含“454”的工单|
|query=2444 createDT>2017-07-01|返回工单编号、工单标题或者联系人姓名包含该内容的工单，并且创建时间是2017年7月1日以后的|
|query=ticketStatus:2,4 createDT< =2017-07-01|返回工单状态为已开启或已解决的工单，并且创建时间是2017年7月1日以前的，包含2017年7月1日当天|
|query=ticketStatus:2,4 updateDT>=2017-07-01|返回工单状态为已开启或已解决的工单，并且更新时间是2017年7月1日以后的，包含2017年7月1日当天|

//说明： //\\
//1、暂不支持搜索内容本身带有空格// \\
//2、当query参数增加了时间的过滤条件时，两个条件之间要以空格分开，比如“ticketStatus:2,4 updateDT>=2017-07-01”// \\
//3、时间过滤条件目前支持以下几种方式：（以createDT为例）// \\
  createDT<2017-09-01 //过滤2017-09-01之前的工单，不包含2017-09-01当天
  createDT>2017-09-01 //过滤2017-09-01之后的工单，不包含2017-09-01当天
  createDT:2017-09-01 //过滤2017-09-01当天的工单
  createDT<=2017-09-01 //过滤2017-09-01之前的工单，包含2017-09-01当天
  createDT>=2017-09-01 //过滤2017-09-01之后的工单，包含2017-09-01当天

**调用示例**
<code>
curl "https://www.bangwo8.com/api/v1/tickets/search.json" \
  -G --data-urlencode "query=ticketStatus:4 createDT>2017-07-03" \
  -v -u {account}:{password}
</code>

**返回值示例**
<code>
Status: 200 OK

{
  "results": [
    {
      "subject":   "这里是工单标题",
      "createDT":  "2009-05-13 10:07:08",
      "updateDT":  "2011-07-22 11:11:12",
      "ticketId":  211,
      "url":       "https://www.bangwo8.com/api/v1/tickets/211.json"
    },
    {
      "subject":   "这里是工单标题",
      "createDT":  "2010-07-13 10:07:08",
      "updateDT":  "2011-07-13 11:11:12",
      "ticketId":  122,
      "url":       "https://www.bangwo8.com/api/v1/tickets/122.json"
    },
    ...
  ],
  "next_page": "https://www.bangwo8.com/api/v1/tickets/search.json?query=\"status:已开启\"&sort_by=createDT&sort_order=desc&page=2",
  "prev_page": null,
  "count":     1234
}
</code>