← 返回首页

QuickForm CLI 接口说明

供命令行、扣子编程、OpenClaw 等工具自动化创建与查看数据任务，无需打开网页。

1. 基础信息

说明：本文档涵盖两类能力
- CLI 接口（/cli/*)：给“校园版/教师版迁移、脚本、大模型工具”调用的账号密码接口（无需 Cookie）。
- 网页端「任务导出 / 导入」：站内按钮触发的导出 ZIP / 导入 ZIP|JSON（需要网页登录）。

2. 增加数据任务 POST /cli/add

创建一条新的数据任务，并返回用于提交数据的 apiid。

请求参数

参数 必填 说明
username 是 用户名
password 是 密码
task_name 是 任务名称
task_intro 否 任务介绍/描述

（兼容字段：title 等同 task_name，description 等同 task_intro。）

成功响应（200）

{
  "success": true,
  "apiid": "a1b2c3d4ef"
}

apiid 即该任务的 API 标识，后续提交数据、拉取数据都使用此 id。

错误响应

示例（curl）

# JSON
curl -X POST "https://quickform.cn/cli/add" \
  -H "Content-Type: application/json" \
  -d '{"username":"teacher1","password":"your_password","task_name":"课堂签到表","task_intro":"本周签到"}'

# 表单
curl -X POST "https://quickform.cn/cli/add" \
  -d "username=teacher1&password=your_password&task_name=课堂签到表&task_intro=本周签到"

3. 查看数据任务列表 POST /cli/list

获取当前账号下所有数据任务及其 apiid 与名称。

请求参数

参数 必填 说明
username 是 用户名
password 是 密码

成功响应（200）

{
  "success": true,
  "tasks": [
    { "apiid": "a1b2c3d4ef", "name": "课堂签到表" },
    { "apiid": "x9y8z7w6vu", "name": "问卷回收" }
  ]
}

错误响应

示例（curl）

curl -X POST "https://quickform.cn/cli/list" \
  -H "Content-Type: application/json" \
  -d '{"username":"teacher1","password":"your_password"}'

4. 查看单个任务详情（用于迁移导出端）POST /cli/show

通过 apiid 获取任务的基本信息与附件（用于“校园版/教师版”从在线版拉取任务并下载 HTML 附件）。

请求参数

参数 必填 说明
username 是 用户名
password 是 密码
apiid 是 任务 API 标识

成功响应（200）

{
  "success": true,
  "apiid": "a1b2c3d4ef",
  "name": "课堂签到表",
  "intro": "任务描述（可空）",
  "tutorial": "教程链接（可空）",
  "share_url": "分享链接（可空）",
  "attachments": [
    { "name": "index.html", "url": "https://quickform.cn/static/uploads/xxxxxxxx.html" }
  ]
}

attachments 重要要求（迁移导出端必读）

错误响应

示例（curl）

curl -X POST "https://quickform.cn/cli/show" \
  -H "Content-Type: application/json" \
  -d '{"username":"teacher1","password":"your_password","apiid":"a1b2c3d4ef"}'

5. 上传 HTML 文件 POST /cli/upload

上传单个 HTML/HTM 文件，并绑定到某个已创建的任务（用于迁移导入端：后续需要带 taskid 的可访问页面）。

说明：CLI 上传时必须指定目标任务（apiid 推荐 / task_id 或 taskid / id）。否则会出现“未走教师认证/任务权限校验就拿到可访问公网 HTML”的问题。

请求方式

成功响应（200）

{
  "success": true,
  "url": "https://quickform.cn/uploads/xxxxxxxx.html?taskid=a1b2c3d4ef",
  "filename": "xxxxxxxx.html"
}

若你需要该上传结果马上用于迁移导入/展示，请确保当前账号已满足“教师认证通过/任务 HTML 可访问”条件。

错误响应

示例（curl）

curl -X POST "https://quickform.cn/cli/upload" \
  -F "username=teacher1" \
  -F "password=your_password" \
  -F "apiid=a1b2c3d4ef" \
  -F "file=@/path/to/your/page.html"

6. 使用 apiid 提交与获取数据

拿到 apiid 后，与网页端一致：

完整提交地址示例：https://quickform.cn/api/a1b2c3d4ef

7. 与扣子 / OpenClaw 的自动化流程

  1. 创建任务：调用 POST /cli/add，传入用户名、密码、任务名称（及可选介绍），得到 apiid。
  2. 配置提交地址：在扣子/OpenClaw 应用中将「数据提交接口」配置为：
    https://quickform.cn/api/<apiid>
    例如：https://quickform.cn/api/a1b2c3d4ef
  3. 应用内提交：用户在前端填写的数据以 JSON 形式 POST 到上述地址即可写入 QuickForm。
  4. 查询任务列表：需要展示或选择「往哪个任务提交」时，可调用 POST /cli/list 获取当前用户下所有 apiid 与名称。

这样即可在不打开 QuickForm 网页的情况下，完成任务的创建、列表查看与数据提交地址的配置。

8. 网页端「任务导出 / 导入」（站内功能）

如果你是在网页里操作（不是脚本/CLI），请看这里。

8.1 开关

管理员可用环境变量控制是否启用：

8.2 导出任务（ZIP）

注意：导出通常仅任务创建者/管理员可用。

8.3 导入任务（ZIP 或 JSON）

9. 返回数据格式小结

接口 成功时返回字段 说明
POST /cli/add success: true, apiid 新任务的 API 标识
POST /cli/list success: true, tasks tasks 为 [{ apiid, name }, ...]
POST /cli/show success: true, attachments 迁移导出端：返回 HTML 附件直链
POST /cli/upload success: true, url, filename 上传并绑定到任务的可访问页面地址与保存文件名（未认证时返回审核提示页）

所有错误均为 success: false 且带 message 字段，便于 CLI 或技能内统一处理。