> ## Documentation Index > Fetch the complete documentation index at: https://docs-claimagent.textin.com/llms.txt > Use this file to discover all available pages before exploring further. # 材料抽取 > 材料抽取(幂等) 传入 material_id 列表，按需创建抽取任务： - 未处理的材料：创建抽取任务，返回 PENDING 状态 - 处理中/失败的材料：直接返回当前状态，不重复处理 - 已完成的材料：直接返回抽取结果 支持重复调用直到所有材料终态(COMPLETED/FAILED)，或等待 callback_url 回调 ## OpenAPI ````yaml POST /doc-agent/api/v1/capability/material/extract openapi: 3.0.3 info: description: |- CapabilityService 独立子能力服务 提供文件上传、图像质检、材料分类、材料抽取等独立能力，不依赖案件流程。 通过 batch_id 和 material_id 串联各能力调用。 ## 典型调用流程 1. 上传文件 → UploadFiles，获得 batch_id 和 material_id 列表 2. (可选)图像质检 → CheckImageQuality，可独立调用，也可用上传返回的 material_id 3. (可选)材料分类 → ClassifyMaterial，可独立调用，也可用上传返回的 material_id 4. 材料抽取 → ExtractMaterial，传入 material_id 列表，返回每个材料的状态和结果 5. 轮询 → 重复调用 ExtractMaterial 直到所有材料完成，或等待 callback_url 回调 注: 质检和分类可独立调用，不依赖抽取流程；抽取接口的 material_ids 必须来自上传接口。 注: ExtractMaterial 幂等，已完成的材料不会重新抽取，失败的材料会自动重试。 ## 错误响应 所有接口错误均返回 HTTP 非 200 状态码，body 格式: {"code": 400, "msg": "错误描述"} 常见错误码: 400 — 参数校验失败(缺少必填字段、文件数超限等) 403 — 认证失败(x-ti-app-id 或 x-ti-secret-code 缺失/无效) 404 — 资源不存在(material_id / batch_id 无效) 500 — 内部处理异常 错误响应示例: {"code": 404, "msg": "material not found"} {"code": 404, "msg": "batch not found"} {"code": 400, "msg": "material_ids or batch_id is required"} {"code": 400, "msg": "material does not belong to the specified batch"} {"code": 400, "msg": "files or file_urls is required"} {"code": 400, "msg": "所有材料必须属于同一批次"} {"code": 403, "msg": "x-api-key 或 x-ti-app-id/x-ti-secret-code 不能为空"} title: CapabilityService API version: 0.0.1 servers: - url: https://agents.textin.com/ security: [] tags: - name: CapabilityService paths: /doc-agent/api/v1/capability/material/extract: post: tags: - CapabilityService description: |- 材料抽取(幂等) 传入 material_id 列表，按需创建抽取任务： - 未处理的材料：创建抽取任务，返回 PENDING 状态 - 处理中/失败的材料：直接返回当前状态，不重复处理 - 已完成的材料：直接返回抽取结果 支持重复调用直到所有材料终态(COMPLETED/FAILED)，或等待 callback_url 回调 operationId: CapabilityService_ExtractMaterial parameters: - in: header name: x-ti-app-id required: true schema: type: string - in: header name: x-ti-secret-code required: true schema: type: string requestBody: content: application/json: examples: 含验真: value: material_ids: - c0b6cdaa-ab06-4d67-bef2-3ea14de665be with_verification: true 指定分类: value: category_hints: - category: 费用与结算 material_id: c0b6cdaa-ab06-4d67-bef2-3ea14de665be material_type: 医疗门诊收费票据（电子） material_ids: - c0b6cdaa-ab06-4d67-bef2-3ea14de665be 指定材料: value: material_ids: - c0b6cdaa-ab06-4d67-bef2-3ea14de665be 按批次: value: batch_id: 661be601-65c7-4025-af0f-20d357dfb090 schema: $ref: '#/components/schemas/capability.v1.CapabilityExtractRequest' required: true responses: '200': content: application/json: examples: 已完成, 含抽取结果和验真 — 仅展示部分字段: value: code: 200 data: materials: - category: 费用与结算 extract_result: extract_fields: - key: 单据标题名称 position: - page: 0 vertices: - 702 - 73 - 1597 - 73 - 1597 - 156 - 702 - 156 value: 上海市医疗门诊收费票据（电子） - key: 票据代码 position: - page: 0 vertices: - 305 - 241 - 457 - 241 - 457 - 280 - 305 - 280 value: '31060125' - key: 票据号码 position: - page: 0 vertices: - 1632 - 239 - 1818 - 239 - 1818 - 278 - 1632 - 278 value: '0290479045' - key: 开票日期 position: - page: 0 vertices: - 1629 - 349 - 1818 - 349 - 1818 - 388 - 1629 - 388 value: '2025-08-04' - key: 发票金额合计 position: - page: 0 vertices: - 1402 - 987 - 1629 - 987 - 1629 - 1033 - 1402 - 1033 value: '250.00' - key: 收款单位 position: - page: 0 vertices: - 126 - 1450 - 1042 - 1450 - 1042 - 1510 - 126 - 1510 value: XX中医药大学附属XX医院 - key: 交款人 position: - page: 0 vertices: - 135 - 344 - 305 - 344 - 305 - 388 - 135 - 388 value: 张* tables: - items: - values: - key: 项目名称 value: 诊察费 - key: 金额 value: '250.00' - key: 数量 value: '1.00' table_name: Table1 table_type: '' fiscal_verify_result: bill_code: '31060125' bill_date: '20250804' bill_name: 上海市医疗门诊收费票据（电子） bill_no: '0290479045' check_code: 519d23 code: 1000 message: 处理成功 payee: XX中医药大学附属XX医院 payer: 张* query_count: 1 time: '2026-05-07 10:03:40' total_amount: '250.00' material_id: c0b6cdaa-ab06-4d67-bef2-3ea14de665be material_type: 医疗门诊收费票据（电子） status: 3 message: OK 首次提交, 状态为 CLASSIFYING: value: code: 200 data: materials: - category: '' extract_result: extract_fields: [] tables: [] material_id: c0b6cdaa-ab06-4d67-bef2-3ea14de665be status: 1 message: OK schema: properties: code: description: 业务状态码 example: 200 type: integer data: $ref: >- #/components/schemas/capability.v1.CapabilityExtractResponse message: description: 状态说明 example: OK type: string type: object description: OK components: schemas: capability.v1.CapabilityExtractRequest: properties: batch_id: description: 批次ID(material_ids 为空时必传；material_ids 非空时可选，不传则自动从材料关联) type: string callback_url: description: |- 结果回调 URL(所有材料处理完成后，系统会向该 URL 发送 POST 请求) body 为 JSON：{"material_ids": ["id1", "id2"], "status": 3}，status=3 表示已完成 type: string category_hints: description: 手动指定分类(非空时自动跳过分类步骤，每个元素通过 material_id 与 material_ids 中的材料对应) items: $ref: '#/components/schemas/capability.v1.MaterialCategoryHint' type: array material_ids: description: |- 材料 ID 列表(与 batch_id 二选一) 传 material_ids：处理指定材料，所有材料必须属于同一批次 不传 material_ids：必须传 batch_id，处理该批次下所有材料 items: type: string type: array with_verification: description: |- 是否对发票类材料执行验真(支持增值税发票、医疗门诊/住院电子发票) 为 true 时，抽取完成后根据分类结果自动判断是否需要验真 type: boolean type: object capability.v1.CapabilityExtractResponse: properties: materials: description: 每个材料的处理状态和结果 items: $ref: '#/components/schemas/capability.v1.CapabilityMaterialResult' type: array type: object capability.v1.MaterialCategoryHint: properties: category: description: 大类名称 type: string material_id: description: 材料 ID type: string material_type: description: 小类名称 type: string type: object capability.v1.CapabilityMaterialResult: properties: category: description: 分类结果 - 大类 type: string error: description: 错误信息(处理失败时返回) type: string extract_result: allOf: - $ref: '#/components/schemas/common.ExtractResult' description: 抽取结果(处理完成后返回) fiscal_verify_result: allOf: - $ref: '#/components/schemas/common.FiscalBillVerifyResult' description: 财政票据验真结果(with_verification=true 且验真完成后返回，医疗门诊/住院电子票据) material_id: description: 材料 ID type: string material_type: description: 分类结果 - 小类 type: string status: description: '该材料的处理状态(0: 待处理, 1: 分类中, 2: 抽取中, 3: 已完成, 4: 失败)' format: enum type: integer timing: allOf: - $ref: '#/components/schemas/capability.v1.MaterialTiming' description: 各阶段处理耗时(毫秒，处理完成后返回) vat_verify_result: allOf: - $ref: '#/components/schemas/common.VatInvoiceVerifyResult' description: 增值税发票验真结果(with_verification=true 且验真完成后返回) type: object common.ExtractResult: properties: document: allOf: - $ref: '#/components/schemas/common.Document' description: 文档原文内容 extract_fields: description: 抽取的字段列表 items: $ref: '#/components/schemas/common.Field' type: array tables: description: 抽取的表格列表 items: $ref: '#/components/schemas/common.Table' type: array type: object common.FiscalBillVerifyResult: description: |- 财政电子票据验真结果 错误码说明： 1000 成功 999 其它错误 1001 网站访问异常 1002 超出该张票据最大查验次数 1003 验证码错误 1006 未查询到当前发票数据 1007 当前地区维护中，请稍后 1008 开票日期超出范围，仅可查验最近一年内开具的电子票据 1009 局端请求异常 1010 税局服务异常，建议 15-20 分钟后重试 properties: accounting_status: description: 入账状态("01"=未入账，"02"=已入账) type: string bill_code: description: 票据代码 type: string bill_date: description: 开票日期(格式 YYYYMMDD) type: string bill_name: description: 票据名称 type: string bill_no: description: 票据号码 type: string bill_status: description: 票据状态("01"=正常，"02"=冲红) type: string check_code: description: 校验码 type: string code: description: 验真返回码(1000=成功，详见错误码说明) format: int32 type: integer collector: description: 收款人(与收款单位不同，指具体经办人) type: string file_type: description: 文件类型(如 "pdf") type: string file_url: description: 文件 URL(票据 PDF 下载链接) type: string fiscal_seal: description: 财政编码印章 type: string fiscal_seal_no: description: 财政编码印章编号 type: string item_details: description: 项目明细 items: $ref: '#/components/schemas/common.FiscalBillItem' type: array item_list: description: 项目清单 items: $ref: '#/components/schemas/common.FiscalBillItem' type: array message: description: 返回信息 type: string other_info: description: 其它信息(业务流水号、门诊号、就诊日期、医疗机构类型、医保类型等) items: $ref: '#/components/schemas/common.FiscalBillExtraInfo' type: array payee: description: 收款单位 type: string payer: description: 缴款人 type: string payer_tax_id: description: 缴款人纳税人识别号 type: string print_status: description: 打印状态("01"=未打印，"02"=已打印) type: string query_count: description: 查验次数 format: int32 type: integer remark: description: 备注 type: string reviewer: description: 复核人 type: string supplementary_info: description: 票据左上角补充信息(如"门特慢") type: string time: description: 查验时间 type: string total_amount: description: 金额合计 type: string total_amount_cn: description: 金额合计大写 type: string void_date: description: 冲红日期 type: string void_reason: description: 冲红原因 type: string void_time: description: 冲红时间 type: string type: object capability.v1.MaterialTiming: description: 材料各阶段处理耗时(毫秒) properties: classify_ms: description: 材料分类耗时(毫秒) type: string extract_ms: description: 信息抽取耗时(毫秒) type: string parse_ms: description: 文件解析耗时(毫秒) type: string type: object common.VatInvoiceVerifyResult: description: 增值税发票验真结果 properties: code: description: 验真返回码(001=成功) type: string data: allOf: - $ref: '#/components/schemas/common.VatInvoiceData' description: 发票详细信息 invalid_mark: description: 作废标志(N=正常, Y=作废, H=红冲, 7=部分红冲, 8=全额红冲) type: string invoice_code: description: 发票代码 type: string invoice_date: description: 开票日期 type: string invoice_number: description: 发票号码 type: string invoice_type: description: 发票类型代码 type: string message: description: 返回信息 type: string purchaser_taxpayer_number: description: 购方税号 type: string type: object common.Document: properties: pages: description: 文档页面列表 items: $ref: '#/components/schemas/common.Page' type: array type: object common.Field: properties: confidence: description: 综合置信度（0~1） format: double type: number dimensions: allOf: - $ref: '#/components/schemas/common.FieldDimensions' description: 多维度评分 is_confirmed: description: 是否人工确认 type: boolean is_deleted: description: 是否已删除 type: boolean key: description: 字段名称 type: string not_consistence_reason: description: 一致性异常原因列表 items: type: string type: array not_normalized_reason: description: 归一化异常原因 type: string position: description: 字段在文档中的位置 items: $ref: '#/components/schemas/common.Position' type: array value: description: 字段值 type: string type: object common.Table: description: |- Table（表格）相关结构： - Table.items 对应你的 JSON 中 "items": [ [ {...}, {...} ], [ ... ] ] - Row 表示一行，Row.cells 表示该行的多个单元格（每个单元格复用 Field properties: items: description: 表格的行数组（每行是一个 Row） items: $ref: '#/components/schemas/common.Row' type: array table_name: description: 表名，例如 "Table1" type: string table_type: description: 表类型（字符串，和原 JSON 的 "type" 对应） type: string type: object common.FiscalBillItem: description: 财政票据项目明细/清单条目(xmmx 和 xmqd 结构相同) properties: amount: description: 金额 type: string code: description: 项目编号 type: string index: description: 项目序号 format: int32 type: integer name: description: 项目名称 type: string paid_amount: description: 支付金额 type: string paid_amount_rate: description: 支付金额税率 type: string quantity: description: 数量 type: string remark: description: 备注 type: string standard: description: 规格标准 type: string type: description: 类型(如"甲") type: string unit: description: 单位 type: string type: object common.FiscalBillExtraInfo: description: 财政票据其它信息条目 properties: en_value: description: 英文值 type: string key: description: 字段英文名(如 "ywlsh"、"mzh"、"jzrq") type: string label: description: 字段中文名(如 "业务流水号"、"门诊号"、"就诊日期") type: string value: description: 值 type: string type: object common.VatInvoiceData: description: 增值税发票详细数据 properties: after_tax_code: description: 完税凭证号码 type: string all_tax: description: 税额 type: string all_valorem_tax: description: 价税合计 type: string blue_invoice_code: description: 蓝字发票代码(红冲时) type: string blue_invoice_no: description: 蓝字发票号码(红冲时) type: string brand_version: description: 厂牌型号 type: string business_unit: description: 经营/拍卖单位 type: string business_unit_tax_no: description: 经营/拍卖单位纳税人识别号 type: string busmess_unit_address: description: 经营/拍卖单位地址 type: string busmess_unit_bank_and_account: description: 经营/拍卖单位开户行及账号 type: string busmess_unit_phone: description: 经营/拍卖单位电话 type: string car_price: description: 车价合计 type: string car_type: description: 车辆类型 type: string car_type_and_number: description: 车种车号 type: string carframe_code: description: 车辆识别代号/车架号 type: string carrier_name: description: |- ===== 货物运输发票专用 ===== 承运人名称 type: string carrier_tax_no: description: 承运人识别号 type: string check_code: description: 校验码 type: string consignor_name: description: 发货人名称 type: string consignor_tax_no: description: 发货人识别号 type: string cyjgxx: description: 查验结果描述 type: string detail_list: description: '===== 明细列表 =====' items: $ref: '#/components/schemas/common.VatInvoiceDetailItem' type: array drawee_name: description: 受票方名称 type: string drawee_tax_no: description: 受票方识别号 type: string elec_ticket_num: description: 电子客票号码 type: string engine_code: description: 发动机号 type: string id_card: description: |- ===== 机动车销售发票专用 ===== 身份证号/组织机构代码 type: string import_license: description: 进口证明书号 type: string inspection_amount: description: 查验次数 type: string inspection_number: description: 商检单号 type: string invalid_mark: description: 作废标志 type: string invoice_code: description: 发票代码 type: string invoice_date: description: 开票日期(YYYYMMDD) type: string invoice_money: description: 不含税金额 type: string invoice_number: description: 发票号码 type: string invoice_type: description: |- ===== 基本信息 ===== 发票类型代码 type: string lemon_market: description: 二手车市场 type: string lemon_market_address: description: 二手车市场地址 type: string lemon_market_bank_and_account: description: 二手车市场开户行及账号 type: string lemon_market_phone: description: 二手车市场电话 type: string lemon_market_tax_no: description: 二手车市场纳税人识别号 type: string license_code: description: 合格证号 type: string license_plate: description: |- ===== 二手车发票专用 ===== 车牌照号 type: string limit_amount: description: 限乘人数 type: string machine_code: description: 机器编号 type: string note: description: |- ===== 其他基本字段 ===== 备注 type: string producing_area: description: 产地 type: string purchaser_address_or_phone: description: 购方地址电话 type: string purchaser_bank_and_number: description: 购方开户行及账号 type: string purchaser_name: description: |- ===== 购方信息 ===== 购方名称 type: string purchaser_phone: description: 买方电话 type: string purchaser_taxpayer_number: description: 购方纳税人识别号 type: string purchaser_unit_or_individual: description: 买方单位/个人 type: string purchaser_unit_or_individual_address: description: 买方单位/个人住址 type: string purchaser_unitcode_or_id_no: description: 买方单位代码/身份证号 type: string receive_name: description: 收货人名称 type: string receive_tax_no: description: 收货人识别号 type: string registration_no: description: 登记证号 type: string saler_address: description: 销方地址 type: string saler_address_or_phone: description: 销方地址电话 type: string saler_bank_account: description: 销方银行账号 type: string saler_bank_and_number: description: 销方开户行及账号 type: string saler_bank_name: description: 销方银行名称 type: string saler_name: description: |- ===== 销方信息 ===== 销方名称 type: string saler_phone: description: 销方电话 type: string saler_taxpayer_number: description: 销方纳税人识别号 type: string seller_phone: description: 卖方电话 type: string seller_unit_code_or_idno: description: 卖方单位代码/身份证号 type: string seller_unit_or_individual: description: 卖方单位/个人 type: string seller_unit_or_individual_address: description: 卖方单位/个人住址 type: string tax_disk_number: description: 税控盘号 type: string tax_rate: description: 税率 type: string tax_unit_code: description: 主管税务机关代码 type: string tax_unit_name: description: 主管税务机关名称 type: string through_address: description: 起运地、经由、到达地 type: string traffic_fee_flag: description: |- ===== 通行费专用 ===== 通行费标志(Y/N) type: string transferred_vehicle_office: description: 转入地车辆管理所名称 type: string transport_goods_info: description: 运输货物信息 type: string unit: description: 吨位 type: string vehicle_tonnage: description: 车辆吨位 type: string zero_tax_rate_flag: description: 零税率标识 type: string type: object common.Page: properties: angle: description: 页面的旋转角度 format: int32 type: integer height: description: 页面的高度（像素） format: int32 type: integer image_id: description: 页面图片ID type: string lines: description: 页面的文本行数组 items: $ref: '#/components/schemas/common.Line' type: array width: description: 页面的宽度（像素） format: int32 type: integer type: object common.FieldDimensions: description: 多维度评分集合 properties: contextual_consistency: allOf: - $ref: '#/components/schemas/common.ScoreDetail' description: 上下文一致性评分 cross_field_consistency: allOf: - $ref: '#/components/schemas/common.ScoreDetail' description: 跨字段一致性评分 field_cue_proximity: allOf: - $ref: '#/components/schemas/common.ScoreDetail' description: 字段线索邻近性评分 numerical_plausibility: allOf: - $ref: '#/components/schemas/common.ScoreDetail' description: 数值合理性评分 traceability: allOf: - $ref: '#/components/schemas/common.ScoreDetail' description: 可溯源性评分 uniqueness_ambiguity: allOf: - $ref: '#/components/schemas/common.ScoreDetail' description: 唯一性/歧义性评分 type: object common.Position: properties: page: description: 页码（从0开始） format: int32 type: integer vertices: description: 坐标顶点数组（x1,y1,x2,y2...） items: format: int32 type: integer type: array type: object common.Row: description: 一行，包含多个单元格（单元格复用 Field properties: values: items: $ref: '#/components/schemas/common.Field' type: array type: object common.VatInvoiceDetailItem: description: 增值税发票明细行 properties: all_tax: description: 税额 type: string board_date: description: 乘车日期 type: string business_type: description: |- ===== 其他 ===== 业务类型(0=销售, 1=退货) type: string carriage: description: 车厢 type: string carrier: description: 承运人 type: string carrier_date: description: |- ===== 航空电子客票专用 ===== 承运日期 type: string detail_amount: description: 金额 type: string detail_no: description: 明细序号 type: string document_num: description: |- ===== 铁路电子客票专用 ===== 单据号 type: string end_station: description: 到达站 type: string expense_item: description: |- ===== 货物运输专用 ===== 费用项目 type: string flight_number: description: 航班号 type: string flight_time: description: 起飞时间 type: string goods_name: description: 货物或应税劳务名称 type: string kttz: description: 空调特征 type: string leg: description: 航段 type: string name: description: 乘车人姓名 type: string net_value: description: 不含税单价 type: string num: description: 数量 type: string plate_no: description: 车牌号 type: string row_no: description: |- ===== 通用字段 ===== 行号 type: string seat_level: description: 座位等级 type: string standard: description: 规格型号 type: string start_station: description: 出发站 type: string start_time: description: 开车时间 type: string tax_classify_code: description: 税收分类编码 type: string tax_detail_amount: description: 含税金额 type: string tax_rate: description: 税率 type: string tax_unit_price: description: 含税单价 type: string ticked_level: description: 客票级别 type: string traffic_date_end: description: 通行日期止 type: string traffic_date_start: description: 通行日期起 type: string train_num: description: 车次 type: string type: description: |- ===== 通行费专用 ===== 类型 type: string unit: description: 单位 type: string xb: description: 席别 type: string xw: description: 席位 type: string type: object common.Line: properties: char_pos: description: 字符位置二维数组（与char_positions等价，兼容不同数据源） items: $ref: '#/components/schemas/common.IntArray' type: array char_positions: description: 字符位置二维数组 items: $ref: '#/components/schemas/common.IntArray' type: array position: description: 文本行位置坐标 items: format: int32 type: integer type: array text: description: 行文本 type: string type: object common.ScoreDetail: description: 单项评分及文字说明 properties: explanation: description: 解释说明 type: string score: description: 0~1 format: double type: number type: object common.IntArray: properties: values: description: 整数数组值 items: format: int32 type: integer type: array type: object ````