介绍
# Cognito Forms
通过托管的 OAuth 身份验证访问 Cognito Forms API。列出表单、管理条目（创建、读取、更新、删除）并检索文档。
## 快速开始
```bash # List all forms python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://gateway.maton.ai/cognito-forms/api/forms') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ```
## 基础 URL
``` https://gateway.maton.ai/cognito-forms/{native-api-path} ```
将 `{native-api-path}` 替换为实际的 Cognito Forms API 端点路径（以 `api/` 开头）。网关将请求代理到 `www.cognitoforms.com` 并自动注入您的 OAuth 令牌。
## 身份验证
所有请求都需要在 Authorization 标头中提供 Maton API 密钥：
``` Authorization: Bearer $MATON_API_KEY ```
**环境变量：** 将您的 API 密钥设置为 `MATON_API_KEY`：
```bash export MATON_API_KEY="YOUR_API_KEY" ```
### 获取 API 密钥
1. 在 [maton.ai](https://maton.ai) 登录或创建账户 2. 前往 [maton.ai/settings](https://maton.ai/settings) 3. 复制您的 API 密钥
## 连接管理
在 `https://ctrl.maton.ai` 管理您的 Cognito Forms OAuth 连接。
### 列出连接
```bash python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://ctrl.maton.ai/connections?app=cognito-forms&status=ACTIVE') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ```
### 创建连接
```bash python <<'EOF' import urllib.request, os, json data = json.dumps({'app': 'cognito-forms'}).encode() req = urllib.request.Request('https://ctrl.maton.ai/connections', data=data, method='POST') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') req.add_header('Content-Type', 'application/json') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ```
### 获取连接
```bash python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://ctrl.maton.ai/connections/{connection_id}') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ```
**响应：** ```json { "connection": { "connection_id": "77de1a60-5f69-45fc-977c-9dfffe7a64d4", "status": "ACTIVE", "creation_time": "2026-02-08T10:39:10.245446Z", "last_updated_time": "2026-02-09T04:11:08.342101Z", "url": "https://connect.maton.ai/?session_token=...", "app": "cognito-forms", "metadata": {} } } ```
在浏览器中打开返回的 `url` 以完成 OAuth 授权。
### 删除连接
```bash python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://ctrl.maton.ai/connections/{connection_id}', method='DELETE') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ```
### 指定连接
如果您有多个 Cognito Forms 连接，请使用 `Maton-Connection` 标头指定要使用的连接：
```bash python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://gateway.maton.ai/cognito-forms/api/forms') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') req.add_header('Maton-Connection', '77de1a60-5f69-45fc-977c-9dfffe7a64d4') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ```
如果省略，网关将使用默认（最旧的）活动连接。
## API 参考
### 表单
#### 列出表单
```bash GET /cognito-forms/api/forms ```
返回组织中的所有表单。
### 条目
#### 获取条目
```bash GET /cognito-forms/api/forms/{formId}/entries/{entryId} ```
根据 ID 或条目编号返回特定条目。
#### 创建条目
```bash POST /cognito-forms/api/forms/{formId}/entries Content-Type: application/json
{ "Name": { "First": "John", "Last": "Doe" }, "Email": "[email protected]", "Phone": "555-1234" } ```
字段名称必须与您的表单字段名称匹配。像姓名和地址这样的复杂字段使用嵌套对象。
#### 更新条目
```bash PATCH /cognito-forms/api/forms/{formId}/entries/{entryId} Content-Type: application/json
{ "Name": { "First": "Jane", "Last": "Doe" }, "Email": "[email protected]" } ```
更新现有条目。使用 PATCH 方法（而非 PUT）。如果条目包含付费订单，则操作失败。
#### 删除条目
```bash DELETE /cognito-forms/api/forms/{formId}/entries/{entryId} ```
删除条目。需要读取/写入/删除 API 权限范围。
### 文档
#### 获取文档
```bash GET /cognito-forms/api/forms/{formId}/entries/{entryId}/documents/{templateNumber} ```
使用指定的模板编号从条目生成并返回文档。
**响应：** ```json { "Id": "abc123", "Name": "Entry-Document.pdf", "ContentType": "application/pdf", "Size": 12345, "File": "https://temporary-download-url..." } ```
### 文件
#### 获取文件
```bash GET /cognito-forms/api/files/{fileId} ```
检索上传到表单条目的文件。
**响应：** ```json { "Id": "file-id", "Name": "upload.pdf", "ContentType": "application/pdf", "Size": 54321, "File": "https://temporary-download-url..." } ```
## 字段格式示例
### 姓名字段
```json { "Name": { "First": "John", "Last": "Doe" } } ```
### 地址字段
```json { "Address": { "Line1": "123 Main St", "Line2": "Suite 100", "City": "San Francisco", "State": "CA", "PostalCode": "94105" } } ```
### 选择字段
单选： ```json { "PreferredContact": "Email" } ```
多选： ```json { "Interests": ["Sports", "Music", "Travel"] } ```
## 代码示例
### JavaScript
```javascript const response = await fetch( 'https://gateway.maton.ai/cognito-forms/api/forms', { headers: { 'Authorization': `Bearer ${process.env.MATON_API_KEY}` } } ); const forms = await response.json(); ```
### Python
```python import os import requests
response = requests.get( 'https://gateway.maton.ai/cognito-forms/api/forms', headers={'Authorization': f'Bearer {os.environ["MATON_API_KEY"]}'} ) forms = response.json() ```
### 创建条目示例 (Python)
```python import os import requests
entry_data = { "Name": {"First": "John", "Last": "Doe"}, "Email": "[email protected]", "Message": "Hello from the API!" }
response = requests.post( 'https://gateway.maton.ai/cognito-forms/api/forms/ContactForm/entries', headers={ 'Authorization': f'Bearer {os.environ["MATON_API_KEY"]}', 'Content-Type': 'application/json' }, json=entry_data ) ```
## 注意事项
- 列出条目：Cognito Forms API 不支持批量列出所有条目。请使用 Webhook 或 OData 来同步条目。 - 获取表单：返回 404 - 请改用“列出表单”来获取表单信息。 - 表单可用性：根据您的 Cognito Forms 计划，此端点可能不可用。 - 条目 ID 可以是条目编号或条目 ID（格式：`{formId}-{entryNumber}`） - 复杂字段（姓名、地址）使用嵌套的 JSON 对象 - 文件上传返回临时下载 URL - 文档生成根据表单模板创建 PDF - API 权限范围控制访问：读取、读取/写入 或 读取/写入/删除 - 重要提示：使用 curl 命令时，如果 URL 包含括号，请使用 `curl -g` 以禁用 glob 解析 - 重要提示：将 curl 输出通过管道传递给 `jq` 或其他命令时，在某些 shell 环境中，`$MATON_API_KEY` 等环境变量可能无法正确展开
## 错误处理
| 状态 | 含义 | |--------|---------| | 400 | 缺少 Cognito Forms 连接 | | 401 | Maton API 密钥无效或缺失 | | 404 | 未找到表单或条目 | | 429 | 请求受限（每 60 秒 100 次请求） | | 4xx/5xx | 来自 Cognito Forms API 的透传错误 |
### 故障排除：API 密钥问题
1. 检查 `MATON_API_KEY` 环境变量是否已设置：
```bash echo $MATON_API_KEY ```
2. 通过列出连接来验证 API 密钥是否有效：
```bash python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://ctrl.maton.ai/connections') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ```
### 故障排除：无效的应用名称
1. 确保您的 URL 路径以 `cognito-forms` 开头。例如：
- 正确：`https://gateway.maton.ai/cognito-forms/api/forms` - 错误：`https://gateway.maton.ai/api/forms`
## 资源
- [Cognito Forms API 概览](https://www.cognitoforms.com/support/475/data-integration/cognito-forms-api) - [REST API 参考](https://www.cognitoforms.com/support/476/data-integration/cognito-forms-api/rest-api-reference) - [API 参考](https://www.cognitoforms.com/support/476/data-integration/cognito-forms-api/api-reference) - [Maton 社区](https://discord.com/invite/dBfFAcefs2) - [Maton 支持](mailto:[email protected])