> ## Documentation Index
> Fetch the complete documentation index at: https://docs-docflow.textin.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 通过URL上传

> 通过文件URL链接上传文档到DocFlow

> [!TIP]
>
> 本文演示如何通过 REST API 使用文件URL上传文档到 DocFlow。\
> 相比直接上传文件，URL上传方式更适合处理远程文件或批量处理场景。

DocFlow 支持通过文件URL的方式上传文档，无需本地存储文件即可进行文档处理。该方式特别适用于：

* 处理远程服务器上的文件
* 批量处理多个文件URL
* 减少本地存储和网络传输开销

## 01 单个文件URL上传

通过 `application/json` 格式提交文件URL列表：

```bash curl icon=terminal wrap theme={null}
curl -X POST \
  -H "x-ti-app-id: <your-app-id>" \
  -H "x-ti-secret-code: <your-secret-code>" \
  -H "Content-Type: application/json" \
  -d '{
    "urls": ["https://example.com/document.pdf"]
  }' \
  "https://docflow.textin.com/api/app-api/sip/platform/v2/file/upload?workspace_id=<your-workspace-id>"
```

```python Python expandable icon=python lines theme={null}
import requests
import json

ti_app_id = "<your-app-id>"
ti_secret_code = "<your-secret-code>"
workspace_id = "<your-workspace-id>"
file_url = "https://example.com/document.pdf"

host = "https://docflow.textin.com"
url = "/api/app-api/sip/platform/v2/file/upload"

payload = {
    "urls": [file_url]
}

resp = requests.post(
    url=f"{host}{url}",
    params={"workspace_id": workspace_id},
    json=payload,
    headers={
        "x-ti-app-id": ti_app_id,
        "x-ti-secret-code": ti_secret_code,
    },
    timeout=60,
)

print(resp.status_code, resp.text)
```

## 02 批量URL上传

一次请求可以上传多个文件URL，最多支持**10个文件**：

```bash curl icon=terminal wrap theme={null}
curl -X POST \
  -H "x-ti-app-id: <your-app-id>" \
  -H "x-ti-secret-code: <your-secret-code>" \
  -H "Content-Type: application/json" \
  -d '{
    "urls": [
      "https://example.com/invoice1.pdf",
      "https://example.com/invoice2.pdf",
      "https://example.com/contract.docx"
    ]
  }' \
  "https://docflow.textin.com/api/app-api/sip/platform/v2/file/upload?workspace_id=<your-workspace-id>&batch_number=202412190001"
```

```python Python expandable icon=python lines theme={null}
import requests
import json

ti_app_id = "<your-app-id>"
ti_secret_code = "<your-secret-code>"
workspace_id = "<your-workspace-id>"

host = "https://docflow.textin.com"
url = "/api/app-api/sip/platform/v2/file/upload"

# 批量上传多个文件URL
file_urls = [
    "https://example.com/invoice1.pdf",
    "https://example.com/invoice2.pdf", 
    "https://example.com/contract.docx"
]

payload = {
    "urls": file_urls
}

resp = requests.post(
    url=f"{host}{url}",
    params={
        "workspace_id": workspace_id,
        "batch_number": "202412190001",
        "category": "invoice"
    },
    json=payload,
    headers={
        "x-ti-app-id": ti_app_id,
        "x-ti-secret-code": ti_secret_code,
    },
    timeout=60,
)

print(resp.status_code, resp.text)
result = resp.json()
print(f"批次号: {result['result']['batch_number']}")
for file_info in result['result']['files']:
    print(f"文件ID: {file_info['id']}, 文件名: {file_info['name']}")
```

## 03 参数说明

### 必填参数

* `workspace_id`: 空间ID。可以参考[获取工作空间ID](https://docs-docflow.textin.com/docflow/cn/100-faq/get_workspace_id.md)文档。

### 请求体参数

* `urls`: 文件URL列表
  * 类型：字符串数组
  * 限制：一次最多10个URL
  * 格式：必须是 `http://` 或 `https://` 开头的有效URL
  * 文件大小：每个文件最大不超过100MB

### 选填参数

可在 URL 查询参数中按需添加：

* `category`: 文件类别（例如：invoice）
* `batch_number`: 批次编号，未提供时系统自动生成
* `auto_verify_vat`: 是否开启发票验真，默认 false
* `split_flag`: 是否进行文件拆分，默认 false（详见[文件拆分](https://docs-docflow.textin.com/docflow/cn/05-split/split.md)章节）
* `crop_flag`: 是否进行多图切分，默认 false（详见[多图切分](https://docs-docflow.textin.com/docflow/cn/05-split/crop.md)章节）
* `target_process`: 目标处理类型，可选 `classify` 或 `extract`

## 04 URL要求

### 支持的URL格式

* 必须以 `http://` 或 `https://` 开头
* URL必须可公开访问（无需认证）
* 服务器必须支持HTTP GET请求

### 文件要求

* 文件格式：支持[文件格式支持](https://docs-docflow.textin.com/docflow/cn/01-upload/support_format.md)中列出的所有格式
* 文件大小：单个文件不超过100MB
* 文件页数：多页文档不超过1000页

### 示例URL

```bash theme={null}
# 有效的URL示例
https://example.com/document.pdf
https://cdn.example.com/files/invoice.pdf
http://192.168.1.100/shared/contract.docx

# 无效的URL示例
ftp://example.com/file.pdf          # 不支持FTP协议
file:///local/path/document.pdf      # 不支持本地文件路径
https://example.com/protected.pdf   # 需要认证的URL
```

## 05 响应格式

URL上传成功后的响应格式与普通文件上传相同：

```json expandable theme={null}
{
   "code": 200,
   "msg": "成功",
   "result": {
      "batch_number": "202412190001",
      "files": [
         {
            "id": "1955840505753140508",
            "name": "document.pdf",
            "format": "pdf"
         },
         {
            "id": "1955840505753140509", 
            "name": "invoice.pdf",
            "format": "pdf"
         }
      ]
   }
}
```

## 06 查询处理结果

上传完成后，使用返回的 `batch_number` 查询处理结果：

```bash curl icon=terminal wrap theme={null}
curl \
  -H "x-ti-app-id: <your-app-id>" \
  -H "x-ti-secret-code: <your-secret-code>" \
  "https://docflow.textin.com/api/app-api/sip/platform/v2/file/fetch?workspace_id=<your-workspace-id>&batch_number=<your-batch-number>"
```

```python Python expandable icon=python lines theme={null}
import requests
import json

ti_app_id = "<your-app-id>"
ti_secret_code = "<your-secret-code>"
workspace_id = "<your-workspace-id>"
batch_number = "<your-batch-number>"

host = "https://docflow.textin.com"
url = "/api/app-api/sip/platform/v2/file/fetch"

resp = requests.get(
    url=f"{host}{url}",
    params={"workspace_id": workspace_id, "batch_number": batch_number},
    headers={"x-ti-app-id": ti_app_id, "x-ti-secret-code": ti_secret_code},
    timeout=60,
)

data = resp.json()
for f in data.get("result", {}).get("files", []):
    print(f"文件ID: {f['id']}, 文件名: {f.get('name')}, 状态: {f.get('recognition_status')}")
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.