> ## 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.

# 快速启动

> 参考示例，快速用API集成文件类别管理功能

> [!TIP]
>
> 文件类别（File Category）是 DocFlow 中用于组织和定义文档类型的核心概念。每个文件类别可以配置字段、表格、样本等，用于文档分类和智能抽取。

## 核心概念

在开始使用文件类别 API 之前，了解以下核心概念将帮助你更好地理解系统的工作原理：

### 样本文件

样本文件是该文件类别的典型示例文档。DocFlow 使用这些样本来：

* **训练分类模型**：帮助系统识别和区分不同类型的文档
* **优化抽取效果**：通过学习样本的格式和布局特征，提高字段抽取的准确度
* **建立识别模板**：为自动识别同类文档提供参考基准

**要求**：每个文件类别至少需要 1 个样本文件，最多 20 个，建议上传 3-5 个具有代表性的样本以获得最佳效果。

### 基本信息字段

基本信息字段是指在文档中以**非表格形式**存在的关键信息，每个字段包含字段名（key）和对应的值（value）。字段可能跨页或跨行显示。

**抽取结果位置**：字段信息在抽取结果中位于 `result.files[].data.fields[]`，每个字段包含：

* `key`：字段名称（如"发票代码"、"开票日期"等）
* `value`：字段值（识别出的文本内容）
* `position[]`：字段在文档中的位置坐标信息

**典型应用场景**：

* 发票类别：发票代码、发票号码、开票日期、购买方名称、金额合计
* 合同类别：合同编号、甲方名称、乙方名称、签订日期、合同金额
* 身份证类别：姓名、性别、民族、出生日期、身份证号码

**配置字段的作用**：

* 明确告诉系统需要从文档中抽取哪些信息
* 通过字段描述和提示词指导 AI 模型进行精准抽取
* 定义字段的数据格式和验证规则

### 表格字段

表格字段是指以**表格形式**存在的结构化数据。DocFlow 能够识别文档中的表格结构，将表格内容转换为结构化的数据格式。表格由多行多列组成，每个表格可以配置多个字段（列）。

**抽取结果位置**：表格信息在抽取结果中位于 `result.files[].data.items[][]`，采用二维数组结构：

* 外层数组：表示表格的行
* 内层数组：表示行中的单元格
* 每个单元格包含 `key`（列名）、`value`（单元格值）和 `position`（位置坐标）

**典型应用场景**：

* 发票类别：货物明细表（货物劳务名称、规格型号、单位、数量、单价、金额）
* 报销单类别：费用明细表（费用项目、日期、金额、备注）
* 订单类别：订单明细表（商品名称、数量、单价、小计）

**表格字段与基本字段的区别**：

* **基本字段**：非表格形式的键值对，在 `result.files[].data.fields[]` 中返回，通常是文档的单个信息点
* **表格字段**：表格形式的结构化数据，在 `result.files[].data.items[][]` 中返回，支持一次抽取多行数据
* **使用场景**：基本字段适用于文档头部、尾部的固定信息；表格字段适用于明细、列表类的重复性结构化信息

## 快速开始

本文介绍如何使用文件类别相关接口：创建、查看、更新与删除文件类别。

## 创建文件类别

创建一个新的文件类别，需要上传至少一个样本文件并配置至少一个字段：

```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>" \
  -F "workspace_id=<your-workspace-id>" \
  -F "name=发票" \
  -F "category_prompt=增值税发票，包含发票代码、发票号码等字段" \
  -F "extract_model=Acgpt" \
  -F "sample_files=@/path/to/invoice_sample.pdf" \
  -F 'category_keyword_rules={"positive_rules":[{"group_name":"发票关键字","min_hit":2,"words":["发票代码","发票号码"]}],"negative_rules":[]}' \
  -F 'fields=[{"name":"发票代码","description":"发票代码描述","prompt":"请抽取发票代码"}]' \
  "https://docflow.textin.com/api/app-api/sip/platform/v2/category/create"
```

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

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/category/create"

# 准备样本文件
files = {
    'sample_files': open('/path/to/invoice_sample.pdf', 'rb')
}

# 准备表单数据
data = {
    'workspace_id': workspace_id,
    'name': '发票',
    'category_prompt': '增值税发票，包含发票代码、发票号码等字段',
    'extract_model': 'Acgpt',
    'fields': '[{"name":"发票代码","description":"发票代码描述","prompt":"请抽取发票代码"}]',
    'category_keyword_rules': json.dumps({
        'positive_rules': [
            {
                'group_name': '发票关键字',
                'min_hit': 2,
                'words': ['发票代码', '发票号码'],
            }
        ],
        'negative_rules': [],
    }, ensure_ascii=False),
}

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

result = resp.json()
if result.get("code") == 200:
    category_id = result.get("result", {}).get("category_id")
    print(f"文件类别创建成功，ID: {category_id}")
else:
    print(f"创建失败: {result.get('msg')}")
```

**请求参数：**

* `workspace_id` (必填): 工作空间 ID
* `name` (必填): 文件类别名称，最大长度 50
* `category_prompt` (选填): 用于分类的提示词，最大长度 500
* `extract_model` (必填): 抽取模型，可选值：`Auto`、`Acgpt`、`Acgpt-VL`、`DF-M1`
* `sample_files` (必填): 样本文件列表，至少上传一个样本文件；每个类别最多拥有20个样本文件
* `fields` (必填): 字段配置列表（JSON 字符串），至少配置一个字段，表格字段仅允许配置默认表格中的字段（table\_id=-1）
* `category_keyword_rules` (选填): 用于分类的关键字规则（JSON 字符串），正向规则用于匹配，负向规则用于过滤。正向规则最多配置 10 组，负向规则最多配置 1 组，每组最多支持配置 20 个关键字

> [!NOTE]
>
> 同一规则组中至少命中 **min\_hit** 个关键字时，该规则组命中。多个正向规则组之间是 OR 关系；命中反向规则组时排除该类别。创建时不传或传入两个空数组表示不配置规则。

**响应示例：**

```json theme={null}
{
  "code": 200,
  "msg": "success",
  "result": {
    "category_id": "1234567890"
  }
}
```

## 获取文件类别列表

获取工作空间下的所有文件类别列表：

```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/category/list?workspace_id=<your-workspace-id>&page=1&page_size=20&enabled=1"
```

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

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/category/list"

resp = requests.get(
    url=f"{host}{url}",
    params={
        "workspace_id": workspace_id,
        "page": 1,
        "page_size": 20,
        "enabled": "1"  # all: 所有, 1: 启用, 0: 禁用, 2: 草稿
    },
    headers={
        "x-ti-app-id": ti_app_id,
        "x-ti-secret-code": ti_secret_code,
    },
    timeout=30,
)

result = resp.json()
if result.get("code") == 200:
    categories = result.get("result", {}).get("categories", [])
    total = result.get("result", {}).get("total", 0)
    print(f"共找到 {total} 个文件类别")
    for category in categories:
        print(f"类别ID: {category.get('id')}, 名称: {category.get('name')}")
        print(f"分类关键字规则: {category.get('category_keyword_rules')}")
else:
    print(f"获取失败: {result.get('msg')}")
```

**请求参数：**

* `workspace_id` (必填): 工作空间 ID
* `page` (选填): 页码，默认为 1
* `page_size` (选填): 每页数量，默认为 1000
* `enabled` (选填): 启用状态，可选值：`all`(所有)、`1`(启用)、`0`(禁用)、`2`(草稿)，默认为 `1`

**响应示例：**

```json theme={null}
{
  "code": 200,
  "msg": "success",
  "result": {
    "total": 10,
    "page": 1,
    "page_size": 20,
    "categories": [
      {
        "id": "1234567890",
        "name": "发票",
        "category_prompt": "增值税发票，包含发票代码、发票号码等字段",
        "category_keyword_rules": {
          "positive_rules": [
            {
              "group_name": "发票关键字",
              "min_hit": 2,
              "words": ["发票代码", "发票号码"]
            }
          ],
          "negative_rules": []
        },
        "extract_model": "Acgpt",
        "enabled": 1
      }
    ]
  }
}
```

已配置分类关键字的类别会在 `category_keyword_rules` 中返回完整规则对象，可用于后续展示或更新。

## 更新文件类别

更新指定文件类别的信息：

```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 '{
    "workspace_id": "<your-workspace-id>",
    "category_id": "1234567890",
    "name": "更新后的类别名称",
    "category_prompt": "更新后的提示词",
    "category_keyword_rules": {
      "positive_rules": [
        {
          "group_name": "发票关键字",
          "min_hit": 1,
          "words": ["增值税发票", "发票号码"]
        }
      ],
      "negative_rules": []
    },
    "enabled": 1
  }' \
  "https://docflow.textin.com/api/app-api/sip/platform/v2/category/update"
```

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

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

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

payload = {
    "workspace_id": workspace_id,
    "category_id": category_id,
    "name": "更新后的类别名称",
    "category_prompt": "更新后的提示词",
    "category_keyword_rules": {
        "positive_rules": [
            {
                "group_name": "发票关键字",
                "min_hit": 1,
                "words": ["增值税发票", "发票号码"],
            }
        ],
        "negative_rules": [],
    },
    "enabled": 1  # 0: 禁用, 1: 启用, 2: 草稿
}

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

result = resp.json()
if result.get("code") == 200:
    print("文件类别更新成功")
else:
    print(f"更新失败: {result.get('msg')}")
```

**请求参数：**

* `workspace_id` (必填): 工作空间 ID
* `category_id` (必填): 文件类别 ID
* `name` (选填): 文件类别名称，最大长度 50
* `category_prompt` (选填): 用于分类的提示词，最大长度 500
* `category_keyword_rules` (选填): 用于分类的关键字规则，正向规则用于匹配，负向规则用于过滤。正向规则最多配置 10 组，负向规则最多配置 1 组，每组最多支持配置 20 个关键字。不传或传 `null` 时不修改，传有效对象时全量替换，传 `{"positive_rules":[],"negative_rules":[]}` 时清空规则
* `enabled` (选填): 启用状态，0: 禁用, 1: 启用, 2: 草稿

## 删除文件类别

删除指定的文件类别（可以批量删除）：

```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 '{
    "workspace_id": "<your-workspace-id>",
    "category_ids": ["1234567890", "0987654321"]
  }' \
  "https://docflow.textin.com/api/app-api/sip/platform/v2/category/delete"
```

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

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/category/delete"

payload = {
    "workspace_id": workspace_id,
    "category_ids": ["1234567890", "0987654321"]
}

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

result = resp.json()
if result.get("code") == 200:
    print("文件类别删除成功")
else:
    print(f"删除失败: {result.get('msg')}")
```

**请求参数：**

* `workspace_id` (必填): 工作空间 ID
* `category_ids` (必填): 要删除的文件类别 ID 数组

> [!WARNING]
>
> 删除文件类别会同时删除其下的所有字段、表格和样本，请谨慎操作。

## 下一步

* 学习[字段管理](https://docs-docflow.textin.com/docflow/cn/10-category-management/fields_management.md) - 管理文件类别下的字段
* 学习[表格管理](https://docs-docflow.textin.com/docflow/cn/10-category-management/tables_management.md) - 管理文件类别下的表格
* 学习[样本管理](https://docs-docflow.textin.com/docflow/cn/10-category-management/samples_management.md) - 管理文件类别的样本文件


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