osTicket API 开发指南：工单创建接口详解

概述

osTicket作为一款开源客服工单系统，提供了丰富的API接口用于系统集成。本文将深入解析osTicket的工单创建API，帮助开发者理解如何通过HTTP接口创建工单。

接口基础信息

osTicket目前支持通过三种格式创建工单：

• XML格式：api/tickets.xml
• JSON格式：api/tickets.json
• 邮件格式：api/tickets.email

需要注意的是，当前API仅支持工单创建功能，暂不支持通过API修改或删除已有工单。

必填字段说明

创建工单时必须包含以下核心字段：

1. email：提交者的电子邮箱地址
2. name：提交者的姓名
3. subject：工单主题
4. message：工单的初始消息内容

可选字段详解

除了必填字段外，API还支持以下可选参数：

• alert：是否通知客服人员，默认为true
• autorespond：是否发送自动回复，默认为true
• ip：提交者的IP地址
• priority：工单优先级ID
• source：工单来源，默认为"API"
• topicId：关联的帮助主题ID
• attachments：附件数组，可包含多个文件

附件处理规范

附件字段需要遵循特定格式：

• name：文件名（必填）
• data：文件内容（必填）
• type：MIME类型，默认为text/plain
• encoding：编码方式，如使用base64编码需明确指定

自定义表单字段

osTicket支持通过API提交自定义表单字段数据，这些字段需要在表单设计器中预先配置。系统内置了一些常用字段：

• phone：电话号码（可使用"X"后接分机号）
• notes：仅客服可见的内部备注

特殊字段数据处理规则

1. 日期字段：需格式化为Unix时间戳或ISO 8601格式
2. 电话号码字段：分机号前需加"X"
3. 选择字段：使用选项的键值或名称

请求示例

XML格式示例

<?xml version="1.0" encoding="UTF-8"?>
<ticket alert="true" autorespond="true" source="API">
    <name>示例用户</name>
    <email>user@example.com</email>
    <subject>API测试工单</subject>
    <phone>021-12345678X1001</phone>
    <message type="text/plain"><![CDATA[这是工单的详细描述内容]]></message>
    <attachments>
        <file name="log.txt" type="text/plain"><![CDATA[
            这里是日志文件内容
        ]]></file>
    </attachments>
</ticket>

JSON格式示例

{
    "alert": true,
    "autorespond": true,
    "source": "API",
    "name": "示例用户",
    "email": "user@example.com",
    "subject": "API测试工单",
    "message": "data:text/plain,这是工单的详细描述内容",
    "attachments": [
        {"log.txt": "data:text/plain;charset=utf-8,这里是日志文件内容"}
    ]
}

邮件格式示例

邮件格式支持MIME标准，可包含HTML内容和多部分附件：

MIME-Version: 1.0
Content-Type: multipart/mixed; boundary=boundary_string

--boundary_string
Content-Type: text/plain; charset=UTF-8

这是工单的文本内容

--boundary_string
Content-Type: application/pdf; name="document.pdf"
Content-Disposition: attachment; filename="document.pdf"
Content-Transfer-Encoding: base64

[base64编码的文件内容]
--boundary_string--

响应处理

成功创建工单后，API会返回：

• 状态码：201 Created
• 响应体：新创建工单的外部ID

常见错误包括：

• 缺少必填字段
• 数据类型不匹配
• Base64编码错误
• 发送了不受支持的字段
• 格式错误（JSON/XML语法错误）

最佳实践建议

1. 始终验证必填字段
2. 对附件内容进行适当的编码处理
3. 处理API响应时检查状态码
4. 为关键操作添加日志记录
5. 考虑实现重试机制处理暂时性失败

通过本文的详细解析，开发者应能充分理解osTicket工单创建API的使用方法，并能在实际项目中正确实现集成。