> ## 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 中用于组织和定义文档类型的核心概念。每个文件类别可以配置字段、表格、样本等，用于文档分类和智能抽取。
</Tip>

## 核心概念

在开始使用文件类别 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[][]` 中返回，支持一次抽取多行数据
* **使用场景**：基本字段适用于文档头部、尾部的固定信息；表格字段适用于明细、列表类的重复性结构化信息

## 快速开始

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

## 创建文件类别

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

<CodeGroup>
  ```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 '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 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":"请抽取发票代码"}]'
  }

  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')}")
  ```
</CodeGroup>

**请求参数：**

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

**响应示例：**

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

## 获取文件类别列表

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

<CodeGroup>
  ```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')}")
  else:
      print(f"获取失败: {result.get('msg')}")
  ```
</CodeGroup>

**请求参数：**

* `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": "增值税发票，包含发票代码、发票号码等字段",
        "extract_model": "Acgpt",
        "enabled": 1
      }
    ]
  }
}
```

## 更新文件类别

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

<CodeGroup>
  ```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": "更新后的提示词",
      "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": "更新后的提示词",
      "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')}")
  ```
</CodeGroup>

**请求参数：**

* `workspace_id` (必填): 工作空间 ID
* `category_id` (必填): 文件类别 ID
* `name` (选填): 文件类别名称，最大长度 50
* `category_prompt` (选填): 用于分类的提示词，最大长度 500
* `enabled` (选填): 启用状态，0: 禁用, 1: 启用, 2: 草稿

## 删除文件类别

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

<CodeGroup>
  ```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')}")
  ```
</CodeGroup>

**请求参数：**

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

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

## 下一步

* 学习[字段管理](./fields_management) - 管理文件类别下的字段
* 学习[表格管理](./tables_management) - 管理文件类别下的表格
* 学习[样本管理](./samples_management) - 管理文件类别的样本文件