# 获取表单列表

获取当前账号下的表单列表，支持按 `search_key` 对表单标题、备注、编号做模糊搜索，也支持按 `number` 做表单编号精确查询。

该接口返回两层核心数据：

- `data.list`：当前页的表单列表
- `data.page`：当前分页状态，可用于判断是否还有下一页

## 请求示例



```python [Python + requests]
import requests

url = "https://open.cli.im/api/v2/rpc/record/getFormList"
data = {
    "page": 1,
    "page_size": 10,
    "search_key": "记录",
    "number": "D100"
}
headers = {
    "Authorization": "Bearer <你的API Key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=data, headers=headers)
print(response.text)
```

```bash [curl]
curl -X POST 'https://open.cli.im/api/v2/rpc/record/getFormList' \
  -H 'Authorization: Bearer <你的API Key>' \
  -H 'Content-Type: application/json' \
  -d '{"page":1,"page_size":10,"search_key":"记录","number":"D100"}'
```



## 请求参数

| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `page` | integer | 否 | 页码，默认 `1` |
| `page_size` | integer | 否 | 每页条数，默认 `10`，最大 `20` |
| `search_key` | string | 否 | 模糊搜索关键字，匹配表单标题、表单备注、表单编号 |
| `number` | string | 否 | 表单编号精确查询，例如 `D100` |

补充说明：

- `search_key` 与 `number` 可单独使用，也可同时传入。
- 若同时传入，服务端会按组合条件返回结果。
- 该接口使用页码分页，是否继续翻页建议根据 `data.page.current_page` 与 `data.page.last_page` 判断。

## 请求体示例

```json
{
  "page": 1,
  "page_size": 10,
  "search_key": "记录",
    "number": "D100"
}
```

## 完整返回示例

```json
{
  "code": 0,
  "message": "",
  "data": {
    "version": "v1",
    "list": [
      {
        "id": 10001,
        "name": "日常记录",
        "type": 0,
        "type_text": "普通表单",
        "number": "D100",
        "note": "每日填写记录",
        "created_at": 1740623881,
        "created_at_iso": "2025-02-27 10:38:01(UTC+08:00)",
        "updated_at": 1740710281,
        "updated_at_iso": "2025-02-28 10:38:01(UTC+08:00)",
        "active_at": 1740796681,
        "active_at_iso": "2025-03-01 10:38:01(UTC+08:00)",
        "project": {
          "id": 100,
          "name": "示例分区",
          "number": "F1"
        }
      },
      {
        "id": 10002,
        "name": "定期检查",
        "type": 0,
        "type_text": "普通表单",
        "number": "D101",
        "note": "",
        "created_at": 1740710281,
        "created_at_iso": "2025-02-28 10:38:01(UTC+08:00)",
        "updated_at": 1740710281,
        "updated_at_iso": "2025-02-28 10:38:01(UTC+08:00)",
        "active_at": 0,
        "active_at_iso": "",
        "project": null
      }
    ],
    "page": {
      "current_page": 1,
      "last_page": 3,
      "per_page": 10,
      "total": 42
    }
  }
}
```

## 响应结构总览

| 路径 | 类型 | 说明 |
| --- | --- | --- |
| `code` | integer | 平台状态码，`0` 表示成功 |
| `message` | string | 状态消息；成功时通常为空字符串 |
| `data` | object | 业务响应包装层 |
| `data.version` | string | 当前返回结构版本，当前为 `v1` |
| `data.list` | array | 表单列表 |
| `data.page` | object | 分页信息 |

### `data.list` 元素字段

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `id` | integer | 表单 ID |
| `name` | string | 表单名称 |
| `type` | integer | 表单类型 |
| `type_text` | string | 表单类型说明 |
| `number` | string | 表单编号（企业内唯一序号，如 `D100`） |
| `note` | string | 表单备注 |
| `created_at` | integer | 创建时间（Unix 时间戳，秒） |
| `created_at_iso` | string | 创建时间的格式化字符串，示例：`2025-02-27 10:38:01(UTC+08:00)` |
| `updated_at` | integer | 更新时间（Unix 时间戳，秒） |
| `updated_at_iso` | string | 更新时间的格式化字符串 |
| `active_at` | integer | 活跃时间（Unix 时间戳，秒；无则为 0） |
| `active_at_iso` | string | 活跃时间的格式化字符串；无值时通常为空字符串 |
| `project` | object|null | 所属分区信息；未关联分区时为 `null` |

### `data.list[].project` 字段

当 `data.list[].project` 不为 `null` 时，包含以下字段：

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `id` | integer | 分区 ID |
| `name` | string | 分区名称 |
| `number` | string | 分区编号 |

### `data.page` 对象

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `current_page` | integer | 当前页码 |
| `last_page` | integer | 最后一页页码 |
| `per_page` | integer | 每页条数 |
| `total` | integer | 表单总数 |

## 分页说明

| 场景 | 说明 |
| --- | --- |
| 首次请求 | 可不传 `page`，默认从第 `1` 页开始 |
| 翻到下一页 | 将 `page` 递增后再次请求 |
| 是否还有下一页 | 建议比较 `data.page.current_page` 与 `data.page.last_page` |
| 空结果页 | `data.list` 为空数组，`data.page.total` 可能为 `0` |

当 `data.page.current_page >= data.page.last_page` 时，通常表示已经到达最后一页。

## 空列表示例

```json
{
  "code": 0,
  "message": "",
  "data": {
    "version": "v1",
    "list": [],
    "page": {
      "current_page": 1,
      "last_page": 1,
      "per_page": 10,
      "total": 0
    }
  }
}
```

## 错误响应

失败时通常返回非成功状态，响应体可能包含以下字段：

```json
{
  "code": 400,
  "error_code": 100300,
  "message": "System error",
  "message_detail": ""
}
```

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `code` | integer | HTTP 状态码或平台错误状态 |
| `error_code` | integer | 业务错误码 |
| `message` | string | 错误摘要 |
| `message_detail` | string | 详细错误信息，可能为空字符串 |

具体错误码定义见：[错误码与调用额度](https://cli.im/open-api/openapi/v2/error-codes.md)。
