# 通过URL导入附件

`POST` `/api/agent/attachment/uploadByUrl`

从可访问的HTTPS地址同步导入附件，fileName和fileUrl为必填项。bizKey和sessionId均为可选，两者同时传入时优先使用bizKey。导入最长可能持续11分钟；附件上传不会自动重试，接口返回失败时请避免立即重复提交，以免重复创建附件。

## 请求参数

### 请求头参数

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| X-Principal-Id | integer | 否 | 身份主体ID（Long类型）。通过API访问时必须传递以标识操作主体；通过页面访问时无需传递。可通过「身份主体」模块的创建接口获取。 |

### 请求体（JSON）

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| fileName | string | 是 | 导入后的文件名，最多255个字符，不得包含路径分隔符，建议保留原文件扩展名 |
| fileUrl | string | 是 | 待导入文件的HTTPS地址，仅支持HTTPS协议，最多4096个字符 |
| bizKey | string | 否 | 业务键，与sessionId均为可选；两者同时传入时优先使用bizKey |
| sessionId | integer | 否 | 会话ID，与bizKey均为可选；两者同时传入时优先使用bizKey |

## 响应

### 200

| 参数名 | 类型 | 说明 |
|--------|------|------|
| httpStatusCode | integer | HTTP状态码 |
| message | string | 响应消息 |
| data | AttachmentUploadVO | 响应数据 |
|     attachmentId | integer | 附件ID |
|     virtualPath | string | 虚拟文件系统路径 |
|     fileName | string | 原始文件名 |
|     fileSize | integer | 文件大小（字节） |
|     replaced | boolean | 是否为替换上传 |
|     previewUrl | string | 附件预览URL，可直接用于图片渲染或文件预览 |
| success | boolean | 是否成功 |
| requestId | string | 上游请求ID，用于跨系统链路追踪排查问题 |
| errCode | string | 上游错误码，前端可据此做特殊UI处理 |

### 400

| 参数名 | 类型 | 说明 |
|--------|------|------|
| httpStatusCode | integer | HTTP状态码 |
| message | string | 响应消息 |
| data | object | 响应数据 |
| success | boolean | 是否成功 |
| requestId | string | 上游请求ID，用于跨系统链路追踪排查问题 |
| errCode | string | 上游错误码，前端可据此做特殊UI处理 |

### 500

| 参数名 | 类型 | 说明 |
|--------|------|------|
| httpStatusCode | integer | HTTP状态码 |
| message | string | 响应消息 |
| data | object | 响应数据 |
| success | boolean | 是否成功 |
| requestId | string | 上游请求ID，用于跨系统链路追踪排查问题 |
| errCode | string | 上游错误码，前端可据此做特殊UI处理 |