API 集成 #

┌─────────────────────────────────────────────────────────────┐
│                    API 功能概览                              │
├─────────────────────────────────────────────────────────────┤
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐         │
│  │  文档管理    │  │  内容编辑    │  │  协作功能    │         │
│  └─────────────┘  └─────────────┘  └─────────────┘         │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐         │
│  │  邮件合并    │  │  模板操作    │  │  导出功能    │         │
│  └─────────────┘  └─────────────┘  └─────────────┘         │
└─────────────────────────────────────────────────────────────┘

步骤：
1. 登录 Zoho 账号
2. 访问 https://api-console.zoho.com
3. 点击"添加客户端"
4. 选择客户端类型
5. 输入客户端信息
6. 获取 Client ID 和 Client Secret

OAuth 2.0 认证流程：

1. 获取授权码
GET https://accounts.zoho.com/oauth/v2/auth
?response_type=code
&client_id={client_id}
&redirect_uri={redirect_uri}
&scope=ZohoWriter.documents.ALL

2. 获取访问令牌
POST https://accounts.zoho.com/oauth/v2/token
?code={code}
&client_id={client_id}
&client_secret={client_secret}
&redirect_uri={redirect_uri}
&grant_type=authorization_code

3. 使用令牌访问 API
Authorization: Zoho-oauthtoken {access_token}

基础 URL：
https://writer.zoho.com/api/v1

主要端点：
- /documents：文档管理
- /templates：模板管理
- /merge：邮件合并
- /export：文档导出

POST /api/v1/documents

请求示例：
{
  "name": "新文档",
  "content": "<p>文档内容</p>",
  "folder_id": "folder_123"
}

响应示例：
{
  "document_id": "doc_123456",
  "name": "新文档",
  "created_time": "2024-01-15T10:30:00Z",
  "modified_time": "2024-01-15T10:30:00Z"
}

GET /api/v1/documents/{document_id}

响应示例：
{
  "document_id": "doc_123456",
  "name": "我的文档",
  "content": "<p>文档内容</p>",
  "created_by": "user_123",
  "created_time": "2024-01-15T10:30:00Z",
  "modified_time": "2024-01-15T11:00:00Z",
  "version": 5
}

PUT /api/v1/documents/{document_id}

请求示例：
{
  "name": "更新的文档名",
  "content": "<p>更新的内容</p>"
}

响应示例：
{
  "document_id": "doc_123456",
  "name": "更新的文档名",
  "modified_time": "2024-01-15T12:00:00Z"
}

DELETE /api/v1/documents/{document_id}

响应示例：
{
  "status": "success",
  "message": "文档已删除"
}

GET /api/v1/documents

查询参数：
- limit：返回数量限制
- offset：偏移量
- folder_id：文件夹 ID
- sort_by：排序字段
- sort_order：排序方向

响应示例：
{
  "documents": [
    {
      "document_id": "doc_1",
      "name": "文档1",
      "created_time": "2024-01-15T10:00:00Z"
    },
    {
      "document_id": "doc_2",
      "name": "文档2",
      "created_time": "2024-01-15T11:00:00Z"
    }
  ],
  "total_count": 50,
  "limit": 10,
  "offset": 0
}

POST /api/v1/documents/{document_id}/content

请求示例：
{
  "content": "<p>新段落</p>",
  "position": {
    "type": "end"
  }
}

位置类型：
- start：文档开头
- end：文档末尾
- after：指定元素后
- before：指定元素前

PUT /api/v1/documents/{document_id}/content

请求示例：
{
  "find": "旧文本",
  "replace": "新文本",
  "match_case": true,
  "match_whole_word": false
}

GET /api/v1/documents/{document_id}/content

查询参数：
- format：html 或 plain

响应示例：
{
  "content": "<p>文档内容</p>",
  "format": "html"
}

POST /api/v1/documents/fromtemplate

请求示例：
{
  "template_id": "template_123",
  "name": "从模板创建的文档",
  "folder_id": "folder_456"
}

响应示例：
{
  "document_id": "doc_789",
  "name": "从模板创建的文档",
  "template_id": "template_123"
}

GET /api/v1/templates

响应示例：
{
  "templates": [
    {
      "template_id": "template_1",
      "name": "商业计划书",
      "category": "商业",
      "created_time": "2024-01-01T00:00:00Z"
    }
  ]
}

POST /api/v1/documents/{document_id}/merge

请求示例：
{
  "data": [
    {
      "name": "张三",
      "email": "zhang@example.com",
      "company": "ABC公司"
    },
    {
      "name": "李四",
      "email": "li@example.com",
      "company": "XYZ公司"
    }
  ],
  "output_format": "pdf",
  "filename_prefix": "邀请函_"
}

响应示例：
{
  "merge_id": "merge_123",
  "status": "processing",
  "total_records": 2
}

GET /api/v1/merge/{merge_id}/status

响应示例：
{
  "merge_id": "merge_123",
  "status": "completed",
  "processed_records": 2,
  "failed_records": 0,
  "download_url": "https://..."
}

GET /api/v1/merge/{merge_id}/download

响应：合并后的文件

POST /api/v1/documents/{document_id}/export

请求示例：
{
  "format": "pdf",
  "options": {
    "quality": "high",
    "include_comments": false,
    "page_range": "1-10"
  }
}

响应示例：
{
  "export_id": "export_123",
  "status": "processing"
}

GET /api/v1/export/{export_id}/download

响应：导出的文件

POST /api/v1/documents/{document_id}/share

请求示例：
{
  "recipients": [
    {
      "email": "user1@example.com",
      "permission": "write"
    },
    {
      "email": "user2@example.com",
      "permission": "read"
    }
  ],
  "message": "请查看此文档"
}

权限类型：
- read：只读
- comment：评论
- write：编辑
- share：分享

GET /api/v1/documents/{document_id}/collaborators

响应示例：
{
  "collaborators": [
    {
      "user_id": "user_1",
      "name": "张三",
      "email": "zhang@example.com",
      "permission": "write"
    }
  ]
}

POST /api/v1/documents/{document_id}/comments

请求示例：
{
  "content": "这段需要修改",
  "position": {
    "start": 100,
    "end": 150
  }
}

响应示例：
{
  "comment_id": "comment_123",
  "content": "这段需要修改",
  "created_by": "user_123",
  "created_time": "2024-01-15T10:00:00Z"
}

POST /api/v1/webhooks

请求示例：
{
  "url": "https://your-server.com/webhook",
  "events": [
    "document.created",
    "document.updated",
    "document.deleted"
  ],
  "secret": "your_webhook_secret"
}

支持的事件：
- document.created
- document.updated
- document.deleted
- document.shared
- comment.added
- merge.completed

POST https://your-server.com/webhook

请求头：
X-Zoho-Signature: sha256签名
X-Zoho-Event: document.updated

请求体：
{
  "event": "document.updated",
  "timestamp": "2024-01-15T10:00:00Z",
  "data": {
    "document_id": "doc_123",
    "name": "更新的文档",
    "modified_by": "user_456"
  }
}

// 安装
npm install zoho-writer-sdk

// 初始化
const ZohoWriter = require('zoho-writer-sdk');
const client = new ZohoWriter({
  clientId: 'your_client_id',
  clientSecret: 'your_client_secret',
  refreshToken: 'your_refresh_token'
});

// 创建文档
const doc = await client.documents.create({
  name: '新文档',
  content: '<p>内容</p>'
});

console.log(doc.document_id);

# 安装
pip install zoho-writer

# 初始化
from zoho_writer import ZohoWriter

client = ZohoWriter(
    client_id='your_client_id',
    client_secret='your_client_secret',
    refresh_token='your_refresh_token'
)

# 创建文档
doc = client.documents.create(
    name='新文档',
    content='<p>内容</p>'
)

print(doc['document_id'])

限制规则：
- 每分钟 100 次请求
- 每小时 2000 次请求
- 每天 50000 次请求

响应头：
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1640000000

HTTP 429 响应：
{
  "error": "rate_limit_exceeded",
  "message": "已超出速率限制",
  "retry_after": 60
}

建议：
1. 实现指数退避
2. 缓存 API 响应
3. 批量处理请求

常见错误码：
- 400：请求参数错误
- 401：认证失败
- 403：权限不足
- 404：资源不存在
- 429：超出速率限制
- 500：服务器错误

处理建议：
1. 检查错误响应
2. 实现重试逻辑
3. 记录错误日志
4. 提供用户反馈

优化建议：
1. 批量操作
2. 异步处理
3. 缓存结果
4. 压缩请求
5. 使用 Webhook 代替轮询

任务：使用 API 创建文档

要求：
1. 获取 API 凭证
2. 编写代码创建文档
3. 添加内容
4. 获取文档列表

任务：使用 API 执行邮件合并

要求：
1. 准备数据
2. 调用合并 API
3. 查询合并状态
4. 下载结果

任务：配置 Webhook 接收事件

要求：
1. 创建 Webhook 端点
2. 配置 Webhook
3. 处理接收的事件
4. 验证签名

检查步骤：
1. 确认 Client ID 和 Secret 正确
2. 检查访问令牌是否过期
3. 确认权限范围正确
4. 检查重定向 URI

解决方法：
1. 增加超时时间
2. 优化请求大小
3. 使用异步处理
4. 检查网络连接

解决方法：
1. 检查 OAuth 权限范围
2. 确认文档分享权限
3. 联系管理员授权