OpnForm API 接口详解与使用指南

概述

OpnForm 提供了一套完整的 RESTful API 接口，主要用于与 Zapier 等自动化工具集成，同时也支持开发者直接调用以管理表单、工作区和提交数据。本文将详细介绍 OpnForm API 的核心功能和使用方法。

认证方式

OpnForm API 使用 Bearer Token 进行认证，所有请求都需要在 Header 中包含有效的访问令牌：

Authorization: Bearer <your_access_token>

主要功能模块

1. 工作区管理

工作区是 OpnForm 中组织表单和用户的基本单位，API 提供了完整的工作区管理功能：

• 获取工作区列表：GET /open/workspaces
• 创建工作区：POST /open/workspaces/create
• 更新工作区：PUT /open/workspaces/{workspaceId}
• 删除工作区：DELETE /open/workspaces/{workspaceId}

创建工作区时需要提供名称和可选的表情符号标识：

{
  "name": "我的工作区",
  "emoji": "🚀"
}

2. 工作区用户管理

API 支持对工作区成员进行精细化管理：

• 获取成员列表：GET /open/workspaces/{workspaceId}/users
• 添加成员：POST /open/workspaces/{workspaceId}/users/add
• 移除成员：DELETE /open/workspaces/{workspaceId}/users/{userId}/remove
• 更新成员角色：PUT /open/workspaces/{workspaceId}/users/{userId}/update-role
• 离开工作区：POST /open/workspaces/{workspaceId}/leave

成员角色分为三种：

• admin：管理员，拥有全部权限
• user：普通用户，可以创建和管理表单
• readonly：只读用户，仅能查看内容

3. 工作区邀请管理

对于通过邮件邀请的用户，API 提供了邀请管理功能：

• 获取邀请列表：GET /open/workspaces/{workspaceId}/invites
• 重新发送邀请：POST /open/workspaces/{workspaceId}/invites/{inviteId}/resend
• 取消邀请：DELETE /open/workspaces/{workspaceId}/invites/{inviteId}/cancel

4. 表单管理

表单是 OpnForm 的核心功能，API 提供了完整的 CRUD 操作：

• 获取表单列表：GET /open/forms
• 创建表单：POST /open/forms
• 获取单个表单：GET /open/forms/{slug}
• 更新表单：PUT /open/forms/{id}
• 删除表单：DELETE /open/forms/{id}

5. 提交数据管理

对于表单收集的数据，API 提供了访问接口：

• 获取提交列表：GET /open/forms/{id}/submissions

支持分页查询，可通过 page 参数指定页码。

权限说明

OpnForm API 采用细粒度的权限控制，主要权限包括：

• workspaces-read：读取工作区信息
• workspaces-write：修改工作区信息
• workspace-users-read：读取工作区成员
• workspace-users-write：管理工作区成员
• forms-read：读取表单
• forms-write：创建和修改表单

最佳实践

1. 错误处理：所有 API 调用都应检查响应状态码，特别是 403 表示权限不足，404 表示资源不存在。

2. 分页处理：获取提交数据时，建议实现分页逻辑以避免一次性加载过多数据。

3. 权限管理：在分配 API 令牌时，应根据最小权限原则只授予必要的权限。

4. 批量操作：目前 API 不支持批量操作，需要逐个处理工作区或表单。

示例代码

以下是一个使用 Python 调用 OpnForm API 的示例：

import requests

# 配置API访问
API_BASE = "https://api.opnform.com"
API_TOKEN = "your_bearer_token"

headers = {
    "Authorization": f"Bearer {API_TOKEN}",
    "Content-Type": "application/json"
}

# 获取工作区列表
response = requests.get(f"{API_BASE}/open/workspaces", headers=headers)
if response.status_code == 200:
    workspaces = response.json()
    print("工作区列表:", workspaces)
else:
    print("获取工作区失败:", response.status_code)

总结

OpnForm API 提供了完整的功能接口，使开发者能够将表单功能集成到自己的应用中或实现自动化工作流。通过合理使用这些接口，可以实现表单的创建、数据收集和团队协作的全流程管理。

对于需要与 Zapier 等自动化工具集成的场景，可以直接使用专门的 Zapier 集成端点，简化集成过程。