> ## 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-reference/文件类别/新增文件类别字段) 接口替代。




## OpenAPI

````yaml /docflow/cn/rest-api/openapi.bundle.yaml post /api/app-api/sip/platform/v2/category/fields/add
openapi: 3.0.0
info:
  title: DocFlow API
  description: DocFlow REST API，提供文件上传和获取文件处理结果能力
  version: 2.8.4
servers:
  - url: https://docflow.textin.com
security:
  - ApiId: []
    SecretCode: []
paths:
  /api/app-api/sip/platform/v2/category/fields/add:
    post:
      tags:
        - 已废弃
      summary: 新增单个文件类别字段
      description: >
        在指定文件类别下新增一个字段，支持新增普通字段和表格字段


        > ⚠️ 该接口目前仍在提供服务，但后续将停止维护。推荐使用 [新增文件类别字段](/api-reference/文件类别/新增文件类别字段)
        接口替代。
      operationId: addCategoryField
      requestBody:
        required: true
        content:
          application/json:
            schema:
              allOf:
                - $ref: '#/components/schemas/CategoryFieldConfig'
              type: object
              properties:
                workspace_id:
                  type: string
                  description: 空间ID
                  example: '1234567890'
                category_id:
                  type: string
                  description: 文件类别ID
                  example: '1234567890'
                table_id:
                  type: string
                  description: |
                    表格ID
                    - 不传或为空：创建普通字段，结果会出现在 result.fields 中
                    - 传入表格ID：创建对应表格下的表格字段，结果会出现在 result.tables[].fields 中
                  example: '1234567890'
                extract_model:
                  type: string
                  description: >
                    选填，字段级抽取模型，仅普通字段（非表格字段）支持，不填则跟随分类级配置（分类级为 mixed 或 null 时默认
                    Auto）

                    - Auto: 智能匹配抽取模型

                    - Acgpt: 速度快，抽取结果稳定

                    - Acgpt-VL: 多模态，适用简单抽取（≤10 页）

                    - DF-M1: 适用复杂文档理解
                  example: Acgpt
                  enum:
                    - Auto
                    - Acgpt
                    - Acgpt-VL
                    - DF-M1
                with_detail:
                  type: boolean
                  description: |
                    是否返回完整详情。传 true 时响应包含新建字段的完整信息。
                    不传或为 false 时仅返回 field_id。
              required:
                - workspace_id
                - category_id
                - name
      responses:
        '200':
          description: 成功新增文件类别字段
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/CodeMessage'
                  - type: object
                    properties:
                      result:
                        type: object
                        properties:
                          field_id:
                            type: string
                            description: 新创建的字段ID
                            example: '1234567890'
                          name:
                            type: string
                            description: 字段名称（with_detail=true 时返回）
                          description:
                            type: string
                            description: 字段描述（with_detail=true 时返回）
                          prompt:
                            type: string
                            description: 语义抽取提示词（with_detail=true 时返回）
                          use_prompt:
                            type: boolean
                            description: 是否使用语义提示词（with_detail=true 时返回）
                          alias:
                            type: array
                            items:
                              type: string
                            description: 字段别名（with_detail=true 时返回）
                          identity:
                            type: string
                            description: 导出字段名（with_detail=true 时返回）
                          multi_value:
                            type: boolean
                            description: 是否多值抽取（with_detail=true 时返回）
                          duplicate_value_distinct:
                            type: boolean
                            description: 是否重复值去重（with_detail=true 时返回）
                          transform_settings:
                            $ref: '#/components/schemas/TransformSettings'
                          extract_model:
                            type: string
                            description: 字段抽取模型（with_detail=true 时返回）
                          enabled:
                            type: integer
                            description: 启用状态（with_detail=true 时返回）
                        required:
                          - field_id
components:
  schemas:
    CategoryFieldConfig:
      type: object
      properties:
        name:
          type: string
          description: 字段名称
          example: 发票代码
        description:
          type: string
          description: 字段描述
          example: 发票代码描述
        prompt:
          type: string
          description: 语义抽取提示词
        use_prompt:
          type: boolean
          description: 是否使用语义提示词
        alias:
          type: array
          description: 字段别名。更新时：不传=不修改，传空数组[]=清空别名，传非空数组=覆盖
          items:
            type: string
          example:
            - 发票号
            - 票号
            - Invoice No.
        identity:
          type: string
          description: 导出字段名。更新时：不传=不修改，传空字符串""=清空，传非空值=覆盖
          example: invoice_number
        multi_value:
          type: boolean
          description: 是否多值抽取
        duplicate_value_distinct:
          type: boolean
          description: 是否重复值去重，仅当 multi_value 为 true 时有效
        transform_settings:
          $ref: '#/components/schemas/TransformSettings'
    CodeMessage:
      type: object
      properties:
        code:
          type: integer
          description: 状态码
          example: 200
        msg:
          type: string
          description: 状态描述
      required:
        - code
        - msg
    TransformSettings:
      type: object
      description: 字段输出转换配置，对抽取结果进行格式化处理后再输出。
      properties:
        type:
          type: string
          description: |
            转换类型，决定使用哪种转换规则：
            - `datetime`：将抽取结果标准化为指定日期格式
            - `enumerate`：限定抽取结果必须是预设枚举值之一
            - `regex`：用正则表达式对抽取结果进行匹配和替换
          enum:
            - datetime
            - enumerate
            - regex
        datetime_settings:
          type: object
          description: 时间格式化配置，type=datetime 时必填
          properties:
            format:
              type: string
              description: 目标日期格式，抽取结果将被标准化为此格式输出
              example: yyyy-MM-dd
        enumerate_settings:
          type: object
          description: 枚举限定配置，type=enumerate 时必填
          properties:
            items:
              type: array
              description: 允许的枚举值列表。抽取结果不在列表中时，按 mismatch_action 处理
              items:
                type: string
              example:
                - 增值税专用发票
                - 增值税普通发票
                - 电子发票
        regex_settings:
          type: object
          description: 正则转换配置，type=regex 时必填
          properties:
            match:
              type: string
              description: 匹配正则表达式，用于校验或捕获抽取结果
              example: ^(\d{4})-(\d{2})-(\d{2})$
            replace:
              type: string
              description: 替换表达式，支持 $1、$2 等捕获组引用
              example: $1/$2/$3
        mismatch_action:
          type: object
          description: 抽取结果不匹配转换规则时的处理方式（适用于所有转换类型，选填）
          properties:
            mode:
              type: string
              description: |
                处理模式：
                - `default`：输出指定的默认值（需配合 default_value）
                - `warning`：保留原始抽取结果，仅标记告警提醒人工复核
              enum:
                - default
                - warning
            default_value:
              type: string
              description: mode=default 时输出的默认值
              example: N/A
  securitySchemes:
    ApiId:
      type: apiKey
      in: header
      name: x-ti-app-id
    SecretCode:
      type: apiKey
      in: header
      name: x-ti-secret-code

````