push表单开放接口文档 V1.0

点击展开版本更新日志

1.0 接口更新日期：2026-08-06
首次发布：表单列表、创建、复制、保存设计、详情、发布差异、发布、停止收集、删除

点击查看目录

文档说明

    push表单是 pushplus 提供的表单收集能力。开放接口用于通过程序管理自己的表单（创建、设计、发布、停止、删除等），鉴权方式与 pushplus 开放接口 一致：先获取 AccessKey，再在请求头携带 access-key。

    AccessKey 的申请、安全 IP、secretKey 配置与主站开放接口相同，请先阅读 开放接口文档 - 获取AccessKey。

    表单开放接口的基础地址为：

https://www.pushplus.plus/push/api

填写页地址形如：https://www.pushplus.plus/push/form/{formCode}（接口返回的 fillUrl 字段）。

鉴权说明

调用本章节接口时，需在 HTTP Header 中携带：

Header 名称是否必填说明
access-key是通过主站 getAccessKey 接口获取的令牌

也可兼容 Header / Cookie 中的 pushToken（浏览器登录态），但程序调用请统一使用 access-key。

获取 AccessKey 示例（与主站相同）：

  • 请求地址：https://www.pushplus.plus/api/common/openApi/getAccessKey
  • 请求方式：POST
  • 请求参数：
{
  "token": "d90******c20",
  "secretKey": "qLc******gdk"
}

通用响应格式

{
  "code": 200,
  "msg": "请求成功",
  "data": {}
}
字段说明
code业务状态码，200 表示成功
msg提示信息
data业务数据，无数据时可能为空

表单状态说明

status说明
0草稿
1收集中
2已停止

题型 type 说明

保存表单设计时，items 中每道题通过 type 区分题型，常用取值如下：

type说明
input单行文本
textarea多行文本
radio单选题
checkbox多选题
select下拉选择
imageRadio图片单选
imageCheckbox图片多选
fillBlank多项填空
number数字
date日期
rate评分题
scale量表题
npsNPS
sort排序题
image图片上传
location地理位置
cascade多级联动
matrixRadio矩阵单选
matrixCheckbox矩阵多选
matrixRate矩阵评分
matrixScale矩阵量表
matrixFill矩阵填空
dynamicTable自增表格
paragraph文本描述（不收集数据）
section分段说明（不收集数据）
pagebreak分页（不收集数据）

一. 我的表单分页

1. 使用说明

分页查询当前用户的表单列表，支持按关键词、状态筛选。列表接口不返回完整题目明细。

2. 接口调用说明

  • 请求地址：https://www.pushplus.plus/push/api/open/form/list
  • 请求方式：GET
  • 请求 Header：
access-key: d7b******62f
  • 请求参数（Query）：
参数名称是否必填默认值说明
pageNum否1页码，从 1 开始
pageSize否10每页条数
keyword否无按标题关键词搜索
status否无表单状态：0草稿 / 1收集中 / 2已停止
  • 响应内容
{
  "code": 200,
  "msg": "请求成功",
  "data": {
    "list": [
      {
        "id": 10001,
        "formCode": "a1b2c3d4",
        "fillUrl": "https://www.pushplus.plus/push/form/a1b2c3d4",
        "title": "用户满意度调查",
        "description": "请花1分钟完成填写",
        "status": 1,
        "responseCount": 12,
        "publishTime": "2026-08-01 10:00:00",
        "createTime": "2026-07-28 09:00:00",
        "updateTime": "2026-08-01 10:00:00"
      }
    ],
    "total": 1,
    "pageNum": 1,
    "pageSize": 10
  }
}
  • 响应字段说明
参数名称说明
list表单列表
total总记录数
pageNum当前页
pageSize每页条数
list[].id表单 id
list[].formCode分享码
list[].fillUrl填写链接
list[].title标题
list[].description描述
list[].status状态
list[].responseCount答卷数
list[].publishTime发布时间
list[].createTime创建时间
list[].updateTime更新时间

二. 创建表单

1. 使用说明

创建一个空白表单（草稿状态）。创建后可通过「保存表单设计」写入题目，再调用「发布表单」开放收集。

2. 接口调用说明

  • 请求地址：https://www.pushplus.plus/push/api/open/form/create
  • 请求方式：POST
  • 请求 Header：
access-key: d7b******62f
Content-Type: application/json
  • 请求参数：
{
  "title": "用户满意度调查"
}
  • 请求参数说明
参数名称是否必填默认值说明
title是无表单标题，最长 100 字
  • 响应内容
{
  "code": 200,
  "msg": "请求成功",
  "data": {
    "id": 10001,
    "formCode": "a1b2c3d4",
    "fillUrl": "https://www.pushplus.plus/push/form/a1b2c3d4",
    "title": "用户满意度调查",
    "status": 0,
    "responseCount": 0,
    "createTime": "2026-08-06 12:00:00",
    "updateTime": "2026-08-06 12:00:00"
  }
}

三. 复制表单

1. 使用说明

基于已有表单复制一份新表单（草稿），便于复用题目设计。

2. 接口调用说明

  • 请求地址：https://www.pushplus.plus/push/api/open/form/copy
  • 请求方式：POST
  • 请求 Header：
access-key: d7b******62f
  • 请求参数（Query）：
参数名称是否必填默认值说明
id是无源表单 id
  • 响应内容：同「创建表单」，返回新表单信息。

四. 保存表单设计

1. 使用说明

保存表单标题、描述、题目列表、主题与收集设置。保存后仅更新草稿；若表单已发布，需再调用「发布表单」才会把最新题目同步到填写页。

2. 接口调用说明

  • 请求地址：https://www.pushplus.plus/push/api/open/form/save
  • 请求方式：POST
  • 请求 Header：
access-key: d7b******62f
Content-Type: application/json
  • 请求参数：
{
  "id": 10001,
  "title": "用户满意度调查",
  "description": "请花1分钟完成填写",
  "items": [
    {
      "id": "q_name",
      "type": "input",
      "label": "您的姓名",
      "description": "",
      "required": true,
      "placeholder": "请输入姓名"
    },
    {
      "id": "q_score",
      "type": "radio",
      "label": "整体满意度",
      "required": true,
      "options": ["非常满意", "满意", "一般", "不满意"],
      "allowOther": false
    }
  ],
  "theme": {
    "headerImage": "",
    "primaryColor": "#1677ff",
    "backgroundColor": "#f5f5f5"
  },
  "settings": {
    "endTime": null,
    "maxResponses": null,
    "oncePerUser": false,
    "password": ""
  }
}
  • 请求参数说明
参数名称是否必填默认值说明
id是无表单 id
title是无表单标题，最长 100 字
description否无表单描述，最长 2000 字
items否无题目列表（JSON 数组），每题至少含 id、type、label
theme否无主题外观：headerImage、primaryColor、backgroundColor
settings否无收集设置：endTime、maxResponses、oncePerUser、password

题目对象常用字段：

参数名称说明
id题目唯一标识（字符串）
type题型，见上文「题型 type 说明」
label题目标题
description题目说明
required是否必填
placeholder输入提示（文本类题型）
options选项列表（单选/多选/下拉等）
rows / columns矩阵类题目的行/列配置
  • 响应内容
{
  "code": 200,
  "msg": "请求成功"
}

五. 表单详情

1. 使用说明

获取表单完整信息，包含草稿题目、主题、设置，以及是否存在「未发布的题目改动」。

2. 接口调用说明

  • 请求地址：https://www.pushplus.plus/push/api/open/form/detail
  • 请求方式：GET
  • 请求 Header：
access-key: d7b******62f
  • 请求参数（Query）：
参数名称是否必填默认值说明
id是无表单 id
  • 响应内容
{
  "code": 200,
  "msg": "请求成功",
  "data": {
    "id": 10001,
    "formCode": "a1b2c3d4",
    "fillUrl": "https://www.pushplus.plus/push/form/a1b2c3d4",
    "title": "用户满意度调查",
    "description": "请花1分钟完成填写",
    "items": [],
    "theme": {
      "primaryColor": "#1677ff"
    },
    "settings": {
      "oncePerUser": false
    },
    "status": 1,
    "publishDirty": true,
    "responseCount": 12,
    "publishTime": "2026-08-01 10:00:00",
    "createTime": "2026-07-28 09:00:00",
    "updateTime": "2026-08-06 12:00:00"
  }
}
  • 响应字段说明（相对列表接口的补充字段）
参数名称说明
items草稿题目列表
theme主题外观
settings收集设置
publishDirty草稿题目与发布快照不一致（有未发布改动）时为 true

六. 草稿与发布快照差异

1. 使用说明

在更新发布前，对比草稿题目与当前发布快照，判断改动是否会影响已有答卷统计（删题、改题型、改选项等）。建议在已有答卷的表单上，发布前先调用本接口做提示。

2. 接口调用说明

  • 请求地址：https://www.pushplus.plus/push/api/open/form/publishDiff
  • 请求方式：GET
  • 请求 Header：
access-key: d7b******62f
  • 请求参数（Query）：
参数名称是否必填默认值说明
id是无表单 id
  • 响应内容
{
  "code": 200,
  "msg": "请求成功",
  "data": {
    "dirty": true,
    "breaking": true,
    "responseCount": 12,
    "added": ["您的建议"],
    "removed": ["旧题目A"],
    "typeChanged": ["整体满意度"],
    "optionChanged": ["您从哪里了解到我们"]
  }
}
  • 响应字段说明
参数名称说明
dirty草稿与发布快照是否不一致
breaking是否存在会影响历史答卷统计的破坏性变更
responseCount已有答卷数
added新增题目标题列表
removed删除题目标题列表
typeChanged题型变更的题目标题列表
optionChanged选项/行列变更的题目标题列表

七. 发布表单

1. 使用说明

将当前草稿题目发布为正式收集版本。草稿状态会变为「收集中」；若表单此前已停止，发布后会重新开放收集。

2. 接口调用说明

  • 请求地址：https://www.pushplus.plus/push/api/open/form/publish
  • 请求方式：POST
  • 请求 Header：
access-key: d7b******62f
  • 请求参数（Query）：
参数名称是否必填默认值说明
id是无表单 id
  • 响应内容
{
  "code": 200,
  "msg": "请求成功",
  "data": {
    "id": 10001,
    "formCode": "a1b2c3d4",
    "fillUrl": "https://www.pushplus.plus/push/form/a1b2c3d4",
    "title": "用户满意度调查",
    "status": 1,
    "previousStatus": 2,
    "publishDirty": false,
    "publishTime": "2026-08-06 12:30:00"
  }
}
  • 响应字段说明
参数名称说明
previousStatus发布前的状态（用于提示「已停止」的表单被重新开放）
status发布后状态，一般为 1（收集中）

八. 停止收集

1. 使用说明

停止表单收集。停止后填写页不可再提交，已有答卷保留。

2. 接口调用说明

  • 请求地址：https://www.pushplus.plus/push/api/open/form/stop
  • 请求方式：POST
  • 请求 Header：
access-key: d7b******62f
  • 请求参数（Query）：
参数名称是否必填默认值说明
id是无表单 id
  • 响应内容
{
  "code": 200,
  "msg": "请求成功"
}

九. 删除表单

1. 使用说明

删除指定表单。删除后不可恢复，请谨慎调用。

2. 接口调用说明

  • 请求地址：https://www.pushplus.plus/push/api/open/form/delete
  • 请求方式：POST
  • 请求 Header：
access-key: d7b******62f
  • 请求参数（Query）：
参数名称是否必填默认值说明
id是无表单 id
  • 响应内容
{
  "code": 200,
  "msg": "请求成功"
}

典型调用流程

  1. 调用主站接口获取 AccessKey
  2. POST /open/form/create 创建表单，拿到 id
  3. POST /open/form/save 写入题目与设置
  4. （可选）GET /open/form/publishDiff 检查差异
  5. POST /open/form/publish 发布并开始收集
  6. 将返回的 fillUrl 分享给填写者
  7. 需要时调用 stop 停止，或 delete 删除
更新时间: