快速启动 - Docflow API

本文演示如何通过 REST API 上传文件到 DocFlow。更多支持的文件格式见文件格式支持。

Docflow 的业务处理流程是异步流程，上传接口可以上传一个或多个文件至Docflow，一旦上传成功，将会获得一个批次编码(batch_number)和若干文件标识(file_id)，用于后续业务流程查询业务处理结果。 Docflow 支持常见图片格式、PDF和Office文件格式，多页文档最大支持1000页。可以参考更详细的文件格式支持和限制页面。

01 上传单个文件

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?workspace_id=<your-workspace-id>"

import requests
import os
from requests_toolbelt.multipart.encoder import MultipartEncoder

ti_app_id = "<your-app-id>"
ti_secret_code = "<your-secret-code>"
workspace_id = "<your-workspace-id>"
filepath = "/path/to/your/file.pdf"

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

mime_type = "application/pdf"
if filepath.lower().endswith((".jpg", ".jpeg", ".png")):
    mime_type = "image/jpeg"

payload = MultipartEncoder(fields={
    "file": (os.path.basename(filepath), open(filepath, "rb"), mime_type)
})

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

print(resp.status_code, resp.text)

参数说明

必填参数

workspace_id: 空间ID。可以参考获取工作空间ID文档。

选填参数

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

category: 文件类别（例如：invoice）
batch_number: 批次编号，未提供时系统自动生成（推荐：同批多文件共用一个批次号，便于一起查询）
auto_verify_vat: 是否开启发票验真，默认 false
split_flag: 是否进行文件拆分，默认 false（详见文件拆分章节）
crop_flag: 是否进行多图切分，默认 false（详见多图切分章节）
target_process: 目标处理类型，可选 classify 或 extract。
Docflow 会默认会进行解析->分类->抽取完整流程。当target_process为classify时，流程执行至分类即结束，以此实现仅分类的需求

示例：

curl

curl -X POST \
  -H "x-ti-app-id: <your-app-id>" \
  -H "x-ti-secret-code: <your-secret-code>" \
  -F "file=@/path/to/invoice.pdf" \
  "https://docflow.textin.com/api/app-api/sip/platform/v2/file/upload?workspace_id=<your-workspace-id>&category=invoice"

02 批量上传

当想要多份文件关联到一个批次时，可以采用批量上传。批量上传有两种方式

在一个请求中上传多个文件。该方案相对简单，同一次请求可重复附带多个 file 字段实现批量上传：

示例:

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?workspace_id=<your-workspace-id>"

import requests
import json
from requests_toolbelt.multipart.encoder import MultipartEncoder
import time

ti_app_id = "your_app_id"
ti_secret_code = "your_app_secret"
workspace_id = "your_workspace_id"

host = "https://docflow.textin.com"
epoch_time = int(time.time())
http_method = "POST"
url = "/api/app-api/sip/platform/v2/file/upload"
params = {
    "workspace_id":workspace_id, 
    }

payload = MultipartEncoder(
    fields=[
        ("file", ("file1.jpg", open("/path/to/file1.jpg", "rb"), "image/jpeg")),
        ("file", ("file2.jpg", open(filepath, "rb"), "image/jpeg")),
    ]
)

resp = requests.post(url=f"{host}{url}", 
                     params=params, 
                     data=payload_raw, 
                     headers={"Content-Type": payload.content_type,
                              "x-ti-app-id": ti_app_id,
                              "x-ti-secret-code": ti_secret_code,
                              })

print(resp.text)
resp_json = json.loads(resp.text)

响应中会返回 result.batch_number 和上传成功的 files 列表。

多个请求上传，通过batch_number关联这些文件。
当多个文件的总大小体积太大时，可以通过这种方式关联多个文件。第一次请求会返回batch_number，后续请求复用这个batch_number来关联剩余的文件。

示例：

import requests
import json
from requests_toolbelt.multipart.encoder import MultipartEncoder
import time
import os

ti_app_id = "your_app_id"
ti_secret_code = "your_app_secret"
workspace_id = "your_workspace_id"
filepaths = ["/path/to/your/file1.png", "/path/to/your/file2.png"]

host = "https://docflow.textin.com"
url = "/api/app-api/sip/platform/v2/file/upload"
params = {
    "workspace_id":workspace_id, 
    }

payload = MultipartEncoder(
    fields=[
        ("file", (os.path.basename(filepaths[0]), open(filepaths[0], "rb"), "image/png")),
    ]
)

resp = requests.post(url=f"{host}{url}", 
                     params=params, 
                     data=payload.to_string(), 
                     headers={"Content-Type": payload.content_type,
                              "x-ti-app-id": ti_app_id,
                              "x-ti-secret-code": ti_secret_code,
                              })

print(resp.text)
resp_json = json.loads(resp.text)

# get and reuse `batch_number`
batch_number = resp_json["result"]["batch_number"]
params["batch_number"] = batch_number
payload = MultipartEncoder(
    fields=[
        ("file", (os.path.basename(filepaths[1]), open(filepaths[1], "rb"), "image/png")),
    ]
)

resp = requests.post(url=f"{host}{url}", 
                     params=params, 
                     data=payload.to_string(), 
                     headers={"Content-Type": payload.content_type,
                              "x-ti-app-id": ti_app_id,
                              "x-ti-secret-code": ti_secret_code,
                              })

print(resp.text)
resp_json = json.loads(resp.text)

03 使用批次号查询处理结果

上传完成后，可使用 batch_number 查询该批次下的处理结果：

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>"

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.get("name"), f.get("recognition_status"), f.get("category"))

​01 上传单个文件

​参数说明

​必填参数

​选填参数

​02 批量上传

​03 使用批次号查询处理结果

01 上传单个文件

参数说明

必填参数

选填参数

02 批量上传

03 使用批次号查询处理结果