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

# 表格管理

> 管理文件类别下的表格配置

> [!TIP]
>
> 表格是文件类别中用于抽取结构化表格数据的配置。每个表格可以包含多个字段，用于定义表格的列。本文介绍如何通过 API 管理文件类别下的表格。

## 获取表格列表

获取指定文件类别下的所有表格列表：

```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/tables/list?workspace_id=<your-workspace-id>&category_id=<category-id>"
```

```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 = "<category-id>"

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

resp = requests.get(
    url=f"{host}{url}",
    params={
        "workspace_id": workspace_id,
        "category_id": category_id
    },
    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:
    tables = result.get("result", {}).get("tables", [])
    print(f"共找到 {len(tables)} 个表格")
    for table in tables:
        print(f"表格ID: {table.get('id')}, 名称: {table.get('name')}")
        print(f"  提示词: {table.get('prompt')}")
        print(f"  多表合并: {table.get('collect_from_multi_table')}")
else:
    print(f"获取失败: {result.get('msg')}")
```

**请求参数：**

* `workspace_id` (必填): 工作空间 ID
* `category_id` (必填): 文件类别 ID

**响应示例：**

```json theme={null}
{
  "code": 200,
  "msg": "success",
  "result": {
    "tables": [
      {
        "id": "table_123",
        "name": "货物明细",
        "prompt": "请抽取每行的品名、数量和金额",
        "collect_from_multi_table": true
      },
      {
        "id": "table_456",
        "name": "费用明细",
        "prompt": "请抽取每行的费用项目和金额",
        "collect_from_multi_table": false
      }
    ]
  }
}
```

## 新增表格

在指定文件类别下批量新增表格：

```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": "<category-id>",
    "tables": [
      {
        "name": "货物明细",
        "prompt": "请抽取每行的品名、数量和金额",
        "collect_from_multi_table": true,
        "fields": [
          {"name": "货物名称", "description": "货物或服务名称"},
          {"name": "数量", "description": "货物数量"},
          {"name": "单价", "description": "货物单价"},
          {"name": "金额", "description": "货物金额"}
        ]
      }
    ]
  }' \
  "https://docflow.textin.com/api/app-api/sip/platform/v2/category/tables/batch_add"
```

```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 = "<category-id>"

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

payload = {
    "workspace_id": workspace_id,
    "category_id": category_id,
    "tables": [
        {
            "name": "货物明细",
            "prompt": "请抽取每行的品名、数量和金额",
            "collect_from_multi_table": True,  # 是否合并文档中的多个表格
            "fields": [
                {"name": "货物名称", "description": "货物或服务名称"},
                {"name": "数量", "description": "货物数量"},
                {"name": "单价", "description": "货物单价"},
                {"name": "金额", "description": "货物金额"}
            ]
        }
    ]
}

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:
    table_ids = result.get("result", {}).get("table_ids", [])
    print(f"表格创建成功，IDs: {table_ids}")
else:
    print(f"创建失败: {result.get('msg')}")
```

**请求参数：**

* `workspace_id` (必填): 工作空间 ID
* `category_id` (必填): 文件类别 ID
* `tables` (必填): 表格数组，每个元素包含以下属性：
  * `name` (必填): 表格名称，最大长度 50
  * `prompt` (选填): 表格语义抽取提示词，最大长度 200
  * `collect_from_multi_table` (选填): 是否多表合并，默认为 false
  * `fields` (选填): 表格字段数组，可在创建表格时直接内嵌字段定义

**响应示例：**

```json theme={null}
{
  "code": 200,
  "msg": "success",
  "result": {
    "table_ids": ["table_new_789"]
  }
}
```

> [!NOTE]
>
> **多表合并说明**：当文档中存在多个结构相同的表格时，开启 `collect_from_multi_table` 可以将它们合并为一个表格结果。例如，发票明细表格可能跨页显示，开启多表合并后会将所有页的明细合并到一起。

## 更新表格

批量更新指定表格的信息：

```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": "<category-id>",
    "tables": [
      {
        "table_id": "<table-id>",
        "name": "更新后的表格名称",
        "prompt": "更新后的提示词",
        "collect_from_multi_table": true
      }
    ]
  }' \
  "https://docflow.textin.com/api/app-api/sip/platform/v2/category/tables/batch_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 = "<category-id>"
table_id = "<table-id>"

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

payload = {
    "workspace_id": workspace_id,
    "category_id": category_id,
    "tables": [
        {
            "table_id": table_id,
            "name": "更新后的表格名称",
            "prompt": "更新后的提示词",
            "collect_from_multi_table": True
        }
    ]
}

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
* `tables` (必填): 表格数组，每个元素包含以下属性：
  * `table_id` (必填): 表格 ID
  * `name` (选填): 表格名称，最大长度 50
  * `prompt` (选填): 表格语义抽取提示词，最大长度 200
  * `collect_from_multi_table` (必填): 是否多表合并

## 删除表格

删除指定的表格，支持批量删除：

```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": "<category-id>",
    "table_ids": ["table_123", "table_456"]
  }' \
  "https://docflow.textin.com/api/app-api/sip/platform/v2/category/tables/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>"
category_id = "<category-id>"

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

payload = {
    "workspace_id": workspace_id,
    "category_id": category_id,
    "table_ids": ["table_123", "table_456"]
}

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
* `table_ids` (必填): 要删除的表格 ID 数组

> [!WARNING]
>
> 删除表格会同时删除该表格下的所有字段，请谨慎操作。

## 表格字段管理

使用 `tables/batch_add` 接口可以在创建表格时直接内嵌字段定义，无需分步调用。也可以单独通过[字段管理](https://docs-docflow.textin.com/docflow/cn/10-category-management/fields_management.md)的批量接口为已有表格添加字段。

### 示例：一次性创建表格及其字段

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

ti_app_id = "<your-app-id>"
ti_secret_code = "<your-secret-code>"
workspace_id = "<your-workspace-id>"
category_id = "<category-id>"
host = "https://docflow.textin.com"

# 创建表格并内嵌字段（一次调用完成）
resp = requests.post(
    url=f"{host}/api/app-api/sip/platform/v2/category/tables/batch_add",
    json={
        "workspace_id": workspace_id,
        "category_id": category_id,
        "tables": [
            {
                "name": "货物明细",
                "prompt": "请抽取每行的品名、数量和金额",
                "collect_from_multi_table": True,
                "fields": [
                    {"name": "货物名称", "description": "货物或服务名称"},
                    {"name": "数量", "description": "货物数量"},
                    {"name": "单价", "description": "货物单价"},
                    {"name": "金额", "description": "货物金额"}
                ]
            }
        ]
    },
    headers={
        "x-ti-app-id": ti_app_id,
        "x-ti-secret-code": ti_secret_code,
    },
)

result = resp.json()
if result.get("code") == 200:
    table_ids = result.get("result", {}).get("table_ids", [])
    print(f"表格及字段创建完成，表格IDs: {table_ids}")
else:
    print(f"创建失败: {result.get('msg')}")
```

## 表格配置说明

### 表格属性

* **name**: 表格名称，必填
* **prompt**: 表格语义抽取提示词，用于指导 AI 进行表格抽取
* **collect\_from\_multi\_table**: 是否多表合并

### 多表合并场景

以下场景适合开启多表合并：

1. **跨页表格**：表格内容跨越多页显示
2. **重复表格**：文档中存在多个结构相同的表格
3. **分段表格**：表格被其他内容分隔成多段

示例：发票货物明细表格如果跨越多页，开启多表合并后，所有页的货物明细会合并成一个完整的表格结果。

## 下一步

* 学习[字段管理](https://docs-docflow.textin.com/docflow/cn/10-category-management/fields_management.md) - 为表格添加字段
* 学习[样本管理](https://docs-docflow.textin.com/docflow/cn/10-category-management/samples_management.md) - 管理文件类别的样本文件
* 返回[文件类别快速启动](https://docs-docflow.textin.com/docflow/cn/10-category-management/quickstart.md) - 查看文件类别基础操作


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