> ## Documentation Index
> Fetch the complete documentation index at: https://beaver.voc.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 工单查询接口

> Shulex → 第三方：拉取完整工单详情

# 工单查询接口

> Shulex → 第三方：拉取完整工单详情

Shulex 收到 Webhook 触发后，会向渠道配置中的 `queryUrl` 发起 `GET` 请求，以获取完整的工单上下文。

## 请求格式

```http theme={null}
GET {queryUrl}?ticketId={ticketId}
{queryAuthHeader}
```

示例：

```http theme={null}
GET https://example.com/open-api/tickets/detail?ticketId=order-2024-88001
Authorization: Bearer xxx
```

## 响应体格式

<Warning>
  `queryUrl` 必须返回包装结构，工单详情必须位于 `data` 字段中；直接返回工单对象的旧格式不兼容。
</Warning>

```json theme={null}
{
  "code": 200,
  "msg": "ok",
  "data": {
    "ticketId": "order-2024-88001",
    "subject": "Package damaged upon arrival",
    "customerEmail": "buyer@example.com",
    "supportEmail": "support@yourstore.com",
    "tags": ["existing-tag"],
    "messages": [
      {
        "id": "msg-20260716-001",
        "role": "user",
        "format": "html",
        "content": "<p>My package arrived damaged. <a href=\"https://cdn.example.com/damage.jpg\">Photo</a></p>",
        "attachments": [
          {
            "name": "damage.jpg",
            "url": "https://cdn.example.com/damage.jpg",
            "contentType": "image/jpeg"
          }
        ],
        "createdAt": "2026-07-16T10:00:00Z"
      },
      {
        "id": "msg-20260716-002",
        "role": "assistant",
        "content": "Could you share a photo of the damage?",
        "createdAt": "2026-07-16T10:02:00Z"
      }
    ],
    "attachments": [
      {
        "name": "invoice.pdf",
        "url": "https://cdn.example.com/invoice.pdf",
        "contentType": "application/pdf"
      }
    ],
    "customFields": {
      "orderId": "ORD-1001",
      "carrier": "UPS"
    }
  },
  "total": null
}
```

### 顶层包装字段

| 字段      | 类型            | 必填 | 说明                        |
| ------- | ------------- | -- | ------------------------- |
| `code`  | number/string | 建议 | 业务状态码，成功时建议返回 `200` 或 `0` |
| `msg`   | string        | 否  | 业务提示信息                    |
| `data`  | object        | 是  | 工单详情对象，Shulex 实际读取该字段     |
| `total` | number/object | 否  | 当前链路不使用，可返回 `null`        |

### `data` 工单字段

| 字段              | 类型     | 必填 | 说明                           |
| --------------- | ------ | -- | ---------------------------- |
| `ticketId`      | string | 是  | 必须与 Webhook 中的 `ticketId` 一致 |
| `subject`       | string | 否  | 工单主题                         |
| `customerEmail` | string | 否  | 客户邮箱，用于补充客户信息                |
| `supportEmail`  | string | 否  | 客服邮箱，用于补充工单上下文               |
| `tags`          | array  | 否  | 当前工单标签，用于流程判断                |
| `messages`      | array  | 是  | 按实际对话顺序返回的完整消息历史             |
| `attachments`   | array  | 否  | 无明确消息归属的工单级附件                |
| `customFields`  | object | 否  | 订单号、物流单号等业务补充字段              |

### `messages[]` 字段

| 字段            | 类型     | 必填 | 说明                                    |
| ------------- | ------ | -- | ------------------------------------- |
| `id`          | string | 建议 | 消息唯一 ID，用于消息关联                        |
| `role`        | string | 是  | `user` 或 `assistant`；其他值按 `user` 处理   |
| `format`      | string | 否  | `text`（默认）或 `html`                    |
| `content`     | string | 是  | 消息正文                                  |
| `attachments` | array  | 否  | 该消息所属附件，推荐优先使用                        |
| `createdAt`   | string | 否  | ISO-8601 时间，例如 `2026-07-16T10:00:00Z` |

### 附件字段

`messages[].attachments` 与顶层 `attachments` 均使用以下结构：

| 字段            | 类型     | 必填 | 说明                                        |
| ------------- | ------ | -- | ----------------------------------------- |
| `id`          | string | 否  | 附件唯一 ID                                   |
| `name`        | string | 否  | 文件名                                       |
| `url`         | string | 是  | Shulex 服务端可访问的文件 URL                      |
| `contentType` | string | 否  | MIME 类型，例如 `image/jpeg`、`application/pdf` |

## Shulex 对查询结果的使用方式

* `messages` 是回复处理的主要上下文；`assistant` 表示历史客服或已发送回复。
* `format=html` 时，Shulex 保留 HTML 正文，并从其中提取 URL 作为附件。
* 显式附件与 HTML 正文中解析出的同一 URL 会去重。
* 顶层 `attachments` 会附加到最后一条客户消息；没有客户消息时不会自动创建一条消息。
* `customerEmail`、`supportEmail` 与 `customFields` 作为工单补充信息传递，不会自动转换为对话消息。

## 接入建议

* 请保证 `messages` 的数组顺序就是实际对话顺序。
* 附件 URL 应为可长期访问的 HTTPS 地址，并确保 Shulex 服务端可下载。
* 建议为消息与附件提供稳定 ID，便于第三方排查与关联。
* 完整工单应尽量一次返回，避免只返回增量消息导致上下文缺失。