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

# 行政区划查询

> 行政区划查询
根据名称模糊匹配省/市/县三级行政区划，返回的 preferred_code 可作为
SearchSocialInsurance 接口的 zone_code 参数使用。


## OpenAPI

````yaml POST /doc-agent/api/v1/capability/division/lookup
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/division/lookup:
    post:
      tags:
        - CapabilityService
      description: |-
        行政区划查询
        根据名称模糊匹配省/市/县三级行政区划，返回的 preferred_code 可作为
        SearchSocialInsurance 接口的 zone_code 参数使用。
      operationId: CapabilityService_LookupDivision
      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:
            example:
              name: 成都
            schema:
              $ref: >-
                #/components/schemas/capability.v1.CapabilityLookupDivisionRequest
        required: true
      responses:
        '200':
          content:
            application/json:
              example:
                code: 200
                data:
                  divisions:
                    - city_code: '510100'
                      city_name: 成都市
                      code: '510100'
                      name: 成都市
                      preferred_code: '510100'
                      province_code: '510000'
                      province_name: 四川省
                message: OK
              schema:
                properties:
                  code:
                    description: 业务状态码
                    example: 200
                    type: integer
                  data:
                    $ref: >-
                      #/components/schemas/capability.v1.CapabilityLookupDivisionResponse
                  message:
                    description: 状态说明
                    example: OK
                    type: string
                type: object
          description: OK
components:
  schemas:
    capability.v1.CapabilityLookupDivisionRequest:
      properties:
        name:
          description: 行政区划名称(支持省/市/县模糊匹配，如 "成都"、"北京"、"南山区")
          type: string
      type: object
    capability.v1.CapabilityLookupDivisionResponse:
      properties:
        divisions:
          description: 匹配的行政区划列表
          items:
            $ref: '#/components/schemas/capability.v1.DivisionItem'
          type: array
      type: object
    capability.v1.DivisionItem:
      description: 行政区划信息
      properties:
        city_code:
          description: 所属地级市编码(省级条目为空)
          type: string
        city_name:
          description: 所属地级市名称(省级条目为空)
          type: string
        code:
          description: 该条目自身的 6 位行政区划编码
          type: string
        name:
          description: 该条目自身的名称
          type: string
        preferred_code:
          description: |-
            推荐使用的地区编码(有地级市返回地级市代码，否则返回省级代码)
             此值可直接作为 SearchSocialInsurance 的 zone_code 参数
          type: string
        province_code:
          description: 所属省级编码
          type: string
        province_name:
          description: 所属省级名称
          type: string
      type: object

````