跳转到主要内容
本文演示如何通过 REST API 使用同步上传接口上传文件到 DocFlow。
同步上传接口会等待文件处理完成后再返回结果，适合需要立即获取处理结果的场景。
DocFlow 提供同步上传接口 /api/app-api/sip/platform/v2/file/upload/sync，该接口与普通上传接口 /api/app-api/sip/platform/v2/file/upload 的区别在于：
  • 普通上传接口：上传文件后立即返回，需要后续通过 /file/fetch 接口查询处理结果
  • 同步上传接口：上传文件后等待处理完成，直接返回完整的处理结果，无需额外查询
同步上传接口会等待文件处理完成，处理时间取决于文件大小和复杂度。
对于大文件或复杂文档，可能需要较长的等待时间。建议设置合适的超时时间。

​
01 同步上传单个文件

通过 multipart/form-data 格式上传文件： 
curl -X POST \
  -H "x-ti-app-id: <your-app-id>" \
  -H "x-ti-secret-code: <your-secret-code>" \
  -F "file=@/path/to/your/file.pdf" \
  "https://docflow.textin.com/api/app-api/sip/platform/v2/file/upload/sync?workspace_id=<your-workspace-id>"

​
02 同步上传多个文件

一次请求可以上传多个文件，系统会等待所有文件处理完成后再返回： 
curl -X POST \
  -H "x-ti-app-id: <your-app-id>" \
  -H "x-ti-secret-code: <your-secret-code>" \
  -F "file=@/path/to/1.pdf" \
  -F "file=@/path/to/2.pdf" \
  "https://docflow.textin.com/api/app-api/sip/platform/v2/file/upload/sync?workspace_id=<your-workspace-id>&batch_number=202412190001"

​
03 通过URL同步上传

同步上传接口也支持通过文件URL上传： 
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/sync?workspace_id=<your-workspace-id>"

​
04 参数说明

同步上传接口的参数与普通上传接口完全相同：

​
必填参数

​
选填参数

可在 URL 查询参数中按需添加：
  • category: 文件类别（例如：invoice）
  • batch_number: 批次编号，未提供时系统自动生成
  • auto_verify_vat: 是否开启发票验真，默认 false
  • split_flag: 是否进行文件拆分，默认 false（详见文件拆分章节）
  • crop_flag: 是否进行多图切分，默认 false（详见多图切分章节）
  • target_process: 目标处理类型，可选 classify 或 extract。
    Docflow 会默认会进行 解析->分类->抽取 完整流程。当target_process为classify时，流程执行至分类即结束

​
请求体参数

支持两种方式：
  1. 文件上传：使用 multipart/form-data 格式，字段名为 file（可重复多个）
  2. URL上传：使用 application/json 格式，包含 urls 数组（最多10个URL）

​
05 响应格式

同步上传接口返回的响应格式与 /file/fetch 接口相同，包含完整的处理结果： 
{
   "code": 200,
   "msg": "成功",
   "result": {
      "total": 1,
      "page": 1,
      "page_size": 20,
      "files": [
         {
            "id": "1955840505753140508",
            "task_id": "1955840505753140509",
            "task_type": 1,
            "batch_number": "202412190001",
            "name": "invoice.pdf",
            "format": "pdf",
            "recognition_status": 1,
            "verification_status": 0,
            "category": "invoice",
            "pages": [
               {
                  "page": 0,
                  "angle": 0,
                  "width": 1024,
                  "height": 1448,
                  "dpi": 144
               }
            ],
            "data": {
               "fields": [
                  {
                     "key": "发票代码",
                     "identifier": "发票代码标识",
                     "value": "3100231130",
                     "position": [
                        {
                           "page": 0,
                           "vertices": [100, 200, 300, 200, 300, 250, 100, 250]
                        }
                     ]
                  },
                  {
                     "key": "发票号码",
                     "identifier": "发票号码标识",
                     "value": "28737000",
                     "position": [
                        {
                           "page": 0,
                           "vertices": [350, 200, 500, 200, 500, 250, 350, 250]
                        }
                     ]
                  }
               ],
               "items": [],
               "tables": [],
               "stamps": [],
               "handwritings": []
            },
            "duration_ms": 5000
         }
      ]
   }
}
响应中的关键字段：
  • result.files[]: 文件列表，每个文件包含完整的处理结果
  • result.files[].data.fields[]: 抽取的字段列表
  • result.files[].data.items[]: 表格数据列表
  • result.files[].data.tables[]: 全部表格数据列表
  • result.files[].data.stamps[]: 印章信息
  • result.files[].data.handwritings[]: 手写体信息
  • result.files[].recognition_status: 识别状态（1表示成功）
  • result.files[].duration_ms: 处理耗时（毫秒）

​
06 使用场景

​
适合使用同步上传的场景

  • 需要立即获取处理结果的场景
  • 单文件或少量文件处理
  • 文件处理时间较短（通常几秒到几十秒）
  • 简化代码逻辑，避免轮询查询

​
不适合使用同步上传的场景

  • 批量处理大量文件
  • 文件处理时间较长（超过1分钟）
  • 需要异步处理的场景
  • 网络不稳定或需要断点续传的场景
对于不适合同步上传的场景，建议使用普通上传接口 /file/upload 配合 /file/fetch 查询接口，实现异步处理流程。

​
07 注意事项

  1. 超时设置：同步上传接口需要等待处理完成，建议设置较长的超时时间（至少300秒）
  2. 处理时间：处理时间取决于文件大小、页数和复杂度，大文件可能需要较长时间
  3. 错误处理：如果处理失败，响应中会包含错误信息，recognition_status 为 2 表示失败
  4. 批量处理：一次上传多个文件时，会等待所有文件处理完成，总耗时可能较长
  5. 网络稳定性：由于需要长时间保持连接，确保网络连接稳定