MobyformMobyform文档
MobyformMobyform文档
首页

快速开始

快速开始创建表单表单编辑器

表单配置

字段类型条件逻辑表单设置主题定制

发布与数据

发布与分享数据管理

功能模块

考试测评模板团队协作订单表单集成

高级功能

高级功能

实用指南

实用指南
如何创建问卷调查如何创建报名表单如何创建在线考试如何创建订单表单如何保存表单模板如何复用主题如何嵌入表单到网站如何使用打印模板离线表单收集自定义域名设置GDPR 控制配置API 快速入门

常见问题

常见问题
实用指南

API 快速入门

几分钟内完成你的第一个 Mobyform API 调用。

API 快速入门

本指南将引导你完成第一个 Mobyform API 调用。几分钟内，你将学会列出表单、创建新表单、读取提交数据和设置 Webhook。

需要 Pro 及以上套餐

第一步：生成 API 密钥

  1. 登录 Mobyform
  2. 进入 「设置」 → 「开发者」
  3. 点击 「生成 API 密钥」
  4. 为密钥起一个描述性名称（如 "后端集成"）
  5. 立即复制密钥 — 之后将不再显示

请妥善保管 API 密钥。不要将其暴露在前端代码、公共仓库或客户端应用中。

第二步：发起第一个请求

使用 API 密钥列出你的表单。所有请求使用基础 URL https://api.mobyform.com，并需要 Authorization 请求头。

cURL

curl -X GET https://api.mobyform.com/api/forms \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

JavaScript / Node.js

const response = await fetch('https://api.mobyform.com/api/forms', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
});

const data = await response.json();
console.log(data);

Python

import requests

response = requests.get(
    'https://api.mobyform.com/api/forms',
    headers={
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json',
    }
)

data = response.json()
print(data)

响应示例

{
  "data": [
    {
      "key": "abc123",
      "title": "客户反馈",
      "status": "published",
      "createdAt": "2024-06-01T08:00:00Z",
      "submissions": 142
    },
    {
      "key": "def456",
      "title": "活动报名",
      "status": "draft",
      "createdAt": "2024-06-10T14:30:00Z",
      "submissions": 0
    }
  ],
  "total": 2,
  "page": 1,
  "size": 20
}

第三步：通过 API 创建表单

发送 POST 请求并附带表单结构来创建新表单。

cURL

curl -X POST https://api.mobyform.com/api/forms \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "联系表单",
    "fields": [
      {
        "type": "input",
        "label": "姓名",
        "required": true
      },
      {
        "type": "email",
        "label": "邮箱地址",
        "required": true
      },
      {
        "type": "textarea",
        "label": "留言内容",
        "required": true,
        "placeholder": "我们能为您做什么？"
      }
    ]
  }'

JavaScript / Node.js

const response = await fetch('https://api.mobyform.com/api/forms', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    title: '联系表单',
    fields: [
      { type: 'input', label: '姓名', required: true },
      { type: 'email', label: '邮箱地址', required: true },
      { type: 'textarea', label: '留言内容', required: true, placeholder: '我们能为您做什么？' },
    ],
  }),
});

const form = await response.json();
console.log('创建的表单:', form.key);

Python

import requests
import json

response = requests.post(
    'https://api.mobyform.com/api/forms',
    headers={
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json',
    },
    data=json.dumps({
        'title': '联系表单',
        'fields': [
            {'type': 'input', 'label': '姓名', 'required': True},
            {'type': 'email', 'label': '邮箱地址', 'required': True},
            {'type': 'textarea', 'label': '留言内容', 'required': True, 'placeholder': '我们能为您做什么？'},
        ],
    })
)

form = response.json()
print('创建的表单:', form['key'])

响应示例

{
  "key": "ghi789",
  "title": "联系表单",
  "status": "draft",
  "createdAt": "2024-06-15T10:00:00Z",
  "fields": [
    { "id": "field_1", "type": "input", "label": "姓名", "required": true },
    { "id": "field_2", "type": "email", "label": "邮箱地址", "required": true },
    { "id": "field_3", "type": "textarea", "label": "留言内容", "required": true }
  ]
}

第四步：读取表单提交数据

获取指定表单的提交数据，支持分页。

cURL

curl -X GET "https://api.mobyform.com/api/forms/abc123/data?page=1&size=10" \
  -H "Authorization: Bearer YOUR_API_KEY"

JavaScript / Node.js

const formKey = 'abc123';
const response = await fetch(
  `https://api.mobyform.com/api/forms/${formKey}/data?page=1&size=10`,
  {
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY',
    },
  }
);

const submissions = await response.json();
console.log(`共计: ${submissions.total} 条提交`);

for (const item of submissions.data) {
  console.log(item.id, item.fields);
}

Python

import requests

form_key = 'abc123'
response = requests.get(
    f'https://api.mobyform.com/api/forms/{form_key}/data',
    headers={'Authorization': 'Bearer YOUR_API_KEY'},
    params={'page': 1, 'size': 10}
)

submissions = response.json()
print(f"共计: {submissions['total']} 条提交")

for item in submissions['data']:
    print(item['id'], item['fields'])

响应示例

{
  "data": [
    {
      "id": "data_001",
      "fields": {
        "姓名": "张三",
        "邮箱地址": "zhangsan@example.com",
        "留言内容": "我想了解一下定价方案。"
      },
      "createdAt": "2024-06-15T12:00:00Z"
    }
  ],
  "total": 1,
  "page": 1,
  "size": 10
}

分页参数

参数类型默认值说明
pagenumber1页码
sizenumber20每页数量（最大 100）
sortstringcreatedAt排序字段
orderstringdesc排序方向（asc 或 desc）

第五步：设置 Webhook

Webhook 在表单事件发生时实时通知你的服务器，无需轮询 API。

注册 Webhook

curl -X POST https://api.mobyform.com/api/webhooks \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-server.com/webhook/mobyform",
    "events": ["form_data_add", "form_data_update", "form_data_delete"],
    "headers": {
      "X-Webhook-Secret": "your-secret-value"
    }
  }'

Webhook 事件

事件触发时机
form_data_add收到新的提交
form_data_update提交数据被修改
form_data_delete提交数据被删除

处理 Webhook 事件

以下是一个简单的 Node.js/Express 处理传入 Webhook 事件的示例：

const express = require('express');
const app = express();

app.use(express.json());

app.post('/webhook/mobyform', (req, res) => {
  const secret = req.headers['x-webhook-secret'];
  if (secret !== 'your-secret-value') {
    return res.status(401).send('Unauthorized');
  }

  const { event, formKey, data } = req.body;

  switch (event) {
    case 'form_data_add':
      console.log(`表单 ${formKey} 收到新提交:`, data.fields);
      break;
    case 'form_data_update':
      console.log(`表单 ${formKey} 的提交 ${data.id} 已更新`);
      break;
    case 'form_data_delete':
      console.log(`表单 ${formKey} 的提交 ${data.id} 已删除`);
      break;
  }

  res.status(200).send('OK');
});

app.listen(3000);

错误处理

请求出错时，API 返回标准错误响应：

{
  "error": {
    "code": "INVALID_REQUEST",
    "message": "错误描述信息"
  }
}

常见错误码

HTTP 状态码错误码含义解决方法
400INVALID_REQUEST请求体格式错误或缺少必填字段检查 JSON 结构和必填参数
401UNAUTHORIZEDAPI 密钥缺失或无效检查 Authorization 请求头和密钥
403FORBIDDENAPI 密钥权限不足在设置中检查密钥的权限范围
404NOT_FOUND表单或提交数据不存在确认表单 key 或数据 ID
429RATE_LIMITED请求过于频繁降低请求频率；参见下方速率限制
500INTERNAL_ERROR服务器内部错误稍后重试；持续出现请联系支持

速率限制

套餐月度限制
Pro1,000 次请求
Business10,000 次请求
Enterprise自定义

超过限制后，API 返回 429 Too Many Requests。响应中包含 Retry-After 头，指示何时可以再次请求。

下一步

  • API 接口参考 — 包含所有端点的完整 API 文档
  • 集成 — 无需编码使用内置集成

GDPR 控制配置

为表单配置面向 GDPR 的控制能力的分步指南。

常见问题

Mobyform 表单平台常见问题解答，帮助你快速解决使用中的疑问。

目录

API 快速入门
第一步：生成 API 密钥
第二步：发起第一个请求
cURL
JavaScript / Node.js
Python
响应示例
第三步：通过 API 创建表单
cURL
JavaScript / Node.js
Python
响应示例
第四步：读取表单提交数据
cURL
JavaScript / Node.js
Python
响应示例
分页参数
第五步：设置 Webhook
注册 Webhook
Webhook 事件
处理 Webhook 事件
错误处理
常见错误码
速率限制
下一步