介绍
# SignNow
使用托管式 OAuth 认证访问 SignNow API。上传文档、发送签名邀请、管理模板，并自动化电子签名工作流。
## 快速开始
```bash # Get current user info python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://gateway.maton.ai/signnow/user') 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/signnow/{resource} ```
网关将请求代理至 `api.signnow.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` 管理您的 SignNow OAuth 连接。
### 列出连接
```bash python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://ctrl.maton.ai/connections?app=signnow&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': 'signnow'}).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": "5ff5474b-5f21-41ba-8bf3-afb33cce5a75", "status": "ACTIVE", "creation_time": "2026-02-08T20:47:23.019763Z", "last_updated_time": "2026-02-08T20:50:32.210896Z", "url": "https://connect.maton.ai/?session_token=...", "app": "signnow", "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 ```
### 指定连接
如果您有多个 SignNow 连接，请通过 `Maton-Connection` 标头指定要使用的连接：
```bash python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://gateway.maton.ai/signnow/user') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') req.add_header('Maton-Connection', '5ff5474b-5f21-41ba-8bf3-afb33cce5a75') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ```
如果省略，网关将使用默认（最早创建的）活动连接。
## API 参考
### 用户操作
#### 获取当前用户
```bash GET /signnow/user ```
**响应：** ```json { "id": "59cce130e93a4e9488522ca67e3a6779f3e48a72", "first_name": "Chris", "last_name": "Kim", "active": "1", "verified": true, "emails": ["[email protected]"], "primary_email": "[email protected]", "document_count": 0, "subscriptions": [...], "teams": [...], "organization": {...} } ```
#### 获取用户文档
```bash GET /signnow/user/documents ```
**响应：** ```json [ { "id": "c63a7bc73f03449c987bf0feaa36e96212408352", "document_name": "Contract", "page_count": "3", "created": "1770598603", "updated": "1770598603", "original_filename": "contract.pdf", "owner": "[email protected]", "template": false, "roles": [], "field_invites": [], "signatures": [] } ] ```
### 文档操作
#### 上传文档
文档必须作为包含 PDF 文件的多部分表单数据上传：
```bash python <<'EOF' import urllib.request, os, json
def encode_multipart_formdata(files): boundary = '----WebKitFormBoundary7MA4YWxkTrZu0gW' lines = [] for (key, filename, content) in files: lines.append(f'--{boundary}'.encode()) lines.append(f'Content-Disposition: form-data; name="{key}"; filename="{filename}"'.encode()) lines.append(b'Content-Type: application/pdf') lines.append(b'') lines.append(content) lines.append(f'--{boundary}--'.encode()) lines.append(b'') body = b'\r\n'.join(lines) content_type = f'multipart/form-data; boundary={boundary}' return content_type, body
with open('document.pdf', 'rb') as f: file_content = f.read()
content_type, body = encode_multipart_formdata([('file', 'document.pdf', file_content)]) req = urllib.request.Request('https://gateway.maton.ai/signnow/document', data=body, method='POST') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') req.add_header('Content-Type', content_type) print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ```
**响应：** ```json { "id": "c63a7bc73f03449c987bf0feaa36e96212408352" } ```
#### 获取文档
```bash GET /signnow/document/{document_id} ```
**响应：** ```json { "id": "c63a7bc73f03449c987bf0feaa36e96212408352", "document_name": "Contract", "page_count": "3", "created": "1770598603", "updated": "1770598603", "original_filename": "contract.pdf", "owner": "[email protected]", "template": false, "roles": [], "viewer_roles": [], "attachments": [], "fields": [], "signatures": [], "texts": [], "checks": [] } ```
#### 更新文档
```bash PUT /signnow/document/{document_id} Content-Type: application/json
{ "document_name": "Updated Contract Name" } ```
**响应：** ```json { "id": "c63a7bc73f03449c987bf0feaa36e96212408352", "signatures": [], "texts": [], "checks": [] } ```
#### 下载文档
```bash GET /signnow/document/{document_id}/download?type=collapsed ```
以二进制数据形式返回 PDF 文件。
查询参数： - `type` - 下载类型：`collapsed`（展平的 PDF），`zip`（所有页面作为图片）
#### 获取文档历史
```bash GET /signnow/document/{document_id}/historyfull ```
**响应：** ```json [ { "unique_id": "c4eb89d84b2b407ba8ec1cf4d25b8b435bcef69d", "user_id": "59cce130e93a4e9488522ca67e3a6779f3e48a72", "document_id": "c63a7bc73f03449c987bf0feaa36e96212408352", "email": "[email protected]", "created": 1770598603, "event": "created_document" } ] ```
#### 将文档移动到文件夹
```bash POST /signnow/document/{document_id}/move Content-Type: application/json
{ "folder_id": "5e2798bdd3d642c3aefebe333bb5b723d6db01a4" } ```
**响应：** ```json { "result": "success" } ```
#### 合并文档
将多个文档合并为一个 PDF：
```bash POST /signnow/document/merge Content-Type: application/json
{ "name": "Merged Document", "document_ids": ["doc_id_1", "doc_id_2"] } ```
以二进制数据形式返回合并后的 PDF。
#### 删除文档
```bash DELETE /signnow/document/{document_id} ```
**响应：** ```json { "status": "success" } ```
### 模板操作
#### 从文档创建模板
```bash POST /signnow/template Content-Type: application/json
{ "document_id": "c63a7bc73f03449c987bf0feaa36e96212408352", "document_name": "Contract Template" } ```
**响应：** ```json { "id": "47941baee4f74784bc1d37c25e88836fc38ed501" } ```
#### 从模板创建文档
```bash POST /signnow/template/{template_id}/copy Content-Type: application/json
{ "document_name": "New Contract from Template" } ```
**响应：** ```json { "id": "08f5f4a2cc1a4d6c8a986adbf90be2308807d4ae", "name": "New Contract from Template" } ```
### 签名邀请操作
#### 发送自由格式邀请
发送文档以供签名：
```bash POST /signnow/document/{document_id}/invite Content-Type: application/json
{ "to": "[email protected]", "from": "[email protected]" } ```
**响应：** ```json { "result": "success", "id": "c38a57f08f2e48d98b5de52f75f7b1dd0a074c00", "callback_url": "none" } ```
**注意：** 自定义主题和消息需要付费订阅计划。
#### 创建签名链接
创建可嵌入的签名链接（需要文档字段）：
```bash POST /signnow/link Content-Type: application/json
{ "document_id": "c63a7bc73f03449c987bf0feaa36e96212408352" } ```
**注意：** 文档必须先添加签名字段，然后才能创建签名链接。
### 文件夹操作
#### 获取所有文件夹
```bash GET /signnow/folder ```
**响应：** ```json { "id": "2ea71a3a9d06470d8e5ec0df6122971f47db7706", "name": "Root", "system_folder": true, "folders": [ { "id": "5e2798bdd3d642c3aefebe333bb5b723d6db01a4", "name": "Documents", "document_count": "5", "template_count": "2" }, { "id": "fafdef6de6d947fc84627e4ddeed6987bfeee02d", "name": "Templates", "document_count": "0", "template_count": "3" }, { "id": "6063688b1e724a25aa98befcc3f2cb7795be7da1", "name": "Trash Bin", "document_count": "0" } ], "total_documents": 0, "documents": [] } ```
#### 按 ID 获取文件夹
```bash GET /signnow/folder/{folder_id} ```
**响应：** ```json { "id": "5e2798bdd3d642c3aefebe333bb5b723d6db01a4", "name": "Documents", "user_id": "59cce130e93a4e9488522ca67e3a6779f3e48a72", "parent_id": "2ea71a3a9d06470d8e5ec0df6122971f47db7706", "system_folder": true, "folders": [], "total_documents": 5, "documents": [...] } ```
### Webhook（事件订阅）操作
#### 列出事件订阅
```bash GET /signnow/event_subscription ```
**响应：** ```json { "subscriptions": [ { "id": "b1d6700dfb0444ed9196e913b2515ae8d5f731a7", "event": "document.complete", "created": "1770598678", "callback_url": "https://example.com/webhook" } ] } ```
#### 创建事件订阅
```bash POST /signnow/event_subscription Content-Type: application/json
{ "event": "document.complete", "callback_url": "https://example.com/webhook" } ```
**响应：** ```json { "id": "b1d6700dfb0444ed9196e913b2515ae8d5f731a7", "created": 1770598678 } ```
**可用事件：** - `document.create` - 文档已创建 - `document.update` - 文档已更新 - `document.delete` - 文档已删除 - `document.complete` - 文档已由所有方签署 - `invite.create` - 邀请已发送 - `invite.update` - 邀请已更新
#### 删除事件订阅
```bash DELETE /signnow/event_subscription/{subscription_id} ```
**响应：** ```json { "id": "b1d6700dfb0444ed9196e913b2515ae8d5f731a7", "status": "deleted" } ```
## 代码示例
### JavaScript
```javascript const response = await fetch( 'https://gateway.maton.ai/signnow/user', { headers: { 'Authorization': `Bearer ${process.env.MATON_API_KEY}` } } ); const data = await response.json(); ```
### Python
```python import os import requests
response = requests.get( 'https://gateway.maton.ai/signnow/user', headers={'Authorization': f'Bearer {os.environ["MATON_API_KEY"]}'} ) data = response.json() ```
### Python (上传文档)
```python import os import requests
with open('document.pdf', 'rb') as f: response = requests.post( 'https://gateway.maton.ai/signnow/document', headers={'Authorization': f'Bearer {os.environ["MATON_API_KEY"]}'}, files={'file': ('document.pdf', f, 'application/pdf')} ) doc = response.json() print(f"Uploaded document: {doc['id']}") ```
### Python (发送邀请)
```python import os import requests
doc_id = "c63a7bc73f03449c987bf0feaa36e96212408352" response = requests.post( f'https://gateway.maton.ai/signnow/document/{doc_id}/invite', headers={ 'Authorization': f'Bearer {os.environ["MATON_API_KEY"]}', 'Content-Type': 'application/json' }, json={ 'to': '[email protected]', 'from': '[email protected]' } ) result = response.json() print(f"Invite sent: {result['id']}") ```
## 注意事项
- 上传的文档必须为 PDF 格式 - 支持的文件类型：PDF, DOC, DOCX, ODT, RTF, PNG, JPG - 系统文件夹（文档、模板、归档、回收站）无法重命名或删除 - 创建签名链接需要文档包含签名字段 - 自定义邀请主题/消息需要付费订阅 - 开发模式下的速率限制：每个应用每小时 500 次请求 - 重要提示：当将 curl 输出通过管道传递给 `jq` 或其他命令时，在某些 shell 环境中，像 `$MATON_API_KEY` 这样的环境变量可能无法正确展开
## 错误处理
| 状态 | 含义 | |--------|---------| | 400 | 缺少 SignNow 连接或请求错误 | | 401 | Maton API 密钥无效或缺失 | | 403 | 权限不足或需要订阅 | | 404 | 资源未找到 | | 405 | 不允许的方法 | | 429 | 请求频率受限 | | 4xx/5xx | 来自 SignNow API 的透传错误 |
SignNow 错误包含详细信息： ```json { "errors": [ { "code": 65578, "message": "Invalid file type." } ] } ```
### 故障排除：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 路径以 `signnow` 开头。例如：
- 正确：`https://gateway.maton.ai/signnow/user` - 错误：`https://gateway.maton.ai/user`
## 资源
- [SignNow API 参考](https://docs.signnow.com/docs/signnow/reference) - [SignNow 开发者门户](https://www.signnow.com/developers) - [SignNow Postman 集合](https://github.com/signnow/postman-collection) - [SignNow SDK](https://github.com/signnow) - [Maton 社区](https://discord.com/invite/dBfFAcefs2) - [Maton 支持](mailto:[email protected])