首先注册应用获取App ID和App Secret，然后通过OAuth 2.0授权流程用code换取access_token，最后携带token调用文档创建、读取、更新等API实现自动化操作。
石墨文档开放平台为开发者提供了便捷的 API 接口，可用于实现文档创建、读取、更新、权限管理等自动化操作。要实现 API 调用，需完成注册、授权、获取凭证和发起请求几个关键步骤。
注册并创建应用
使用石墨文档 API 的第一步是在石墨开放平台注册账号并创建应用：
- 登录后进入“我的应用”页面，点击“创建应用”
- 填写应用名称、描述和回调地址（用于 OAuth2 授权）
- 创建成功后，系统会生成 App ID 和 App Secret，这是后续调用接口的身份凭证
获取访问令牌（Access Token）
石墨 API 使用 OAuth 2.0 协议进行授权。你需要通过以下流程获取用户的访问权限：
- 构造授权 URL，引导用户跳转：
https://account.shimo.im/oauth/authorize?client_id=YOUR_APP_ID&redirect_uri=YOUR_REDIRECT_URI&response_type=code - 用户授权后，石墨会重定向到你设定的回调地址，并附带一个临时的 code
- 使用该 code 向 token 接口发起 POST 请求，换取 access_token：
请求示例：
POST https://account.shimo.im/oauth/tokenContent-Type: application/json
{ "client_id": "your_app_id", "client_secret": "your_app_secret", "grant_type": "authorization_code", "code": "received_code", "redirect_uri": "your_redirect_uri" }
成功后将返回包含 access_token 的 JSON 数据，有效期通常为 2 小时。
调用文档相关 API
拿到 access_token 后，即可调用具体的文档操作接口。例如创建一个新文档：
POST https://api.shimo.im/docs
Authorization: Bearer YOUR_ACCESS_TOKEN
Content-Type: application/json
{ "title": "我的自动化文档", "folder_id": "optional_folder_id" }
常见接口包括：
- GET /docs：获取用户文档列表
- GET /docs/{docId}：获取文档元信息
- PATCH /docs/{docId}：修改文档标题或位置
- PUT /docs/{docId}/content：写入文档内容（支持 Markdown 或 JSON 格式）
- POST /shares：设置文档分享权限
处理响应与错误
API 返回标准 JSON 格式数据。成功时状态码为 200 或 201，结构类似：
{ "id": "abc123xyz", "title": "我的自动化文档", "created_at": "2023-07-01T10:00:00Z" }出错时会返回错误码和提示，如：
- 401 Unauthorized：access_token 无效或过期，需重新授权
- 403 Forbidden：无权访问目标文档
- 429 Too Many Requests：请求频率超限，建议增加间隔
基本上就这些。只要正确配置应用、获取 token 并按文档格式调用接口，就能实现对石墨文档的程序化控制。建议在测试环境先用个人账号验证流程，再集成到正式系统中。
