zoho

用途

本工具用于通过命令行与 Zoho CRM、Zoho Projects 和 Zoho Meeting 的 API 进行交互，适合管理商机、联系人、线索、任务、项目、里程碑、会议录制等数据，或执行任何 Zoho 相关操作。其 zoho CLI 封装会自动处理 OAuth 令牌刷新和缓存。

主要能力

CRM

• 支持模块：Leads、Contacts、Accounts、Deals、Tasks、Events、Calls、Notes、Products、Quotes、Sales_Orders、Purchase_Orders、Invoices。
• 命令包括：列出记录（list）、获取记录（get）、按条件搜索（search）、创建（create）、更新（update）、删除（delete）。
• 搜索运算符：equals、not_equal、starts_with、contains、not_contains、in、not_in、between、greater_than、less_than。

Projects

• 支持列出所有项目、获取项目详情、查看任务、创建/更新任务、查看里程碑、任务列表、缺陷和工时日志。
• 任务字段：name、start_date（MM-DD-YYYY）、end_date、priority（None/Low/Medium/High）、owner、description、tasklist_id、percent_complete。

Meeting

• 支持列出所有录制、下载录制、列出会议/会话、获取会议详情。
• 录制响应字段包括：erecordingId、topic、sDate、sTime、startTimeinMs、durationInMins、downloadUrl / publicDownloadUrl、transcriptionDownloadUrl、summaryDownloadUrl、fileSize / fileSizeInMB、status、meetingKey、creatorName。
• 可结合 ffmpeg 等工具实现会议录制自动摘要流水线，脚本见 scripts/standup-summarizer.sh。

原始 API 调用

可通过 zoho raw GET <path> 调用未覆盖的子命令，例如获取 CRM 字段定义、自定义模块或 Meeting 端点。

使用方式

认证设置

1. 在 Zoho API Console 注册应用，选择 Server-based Applications，填写 Client Name、Homepage URL、Redirect URI，获取 Client ID 和 Client Secret。
2. 生成授权码：构建包含 client_id、scope、redirect_uri、access_type=offline、prompt=consent 的 URL 并在浏览器打开。需使用与数据中心匹配的 accounts URL（美国、欧盟、印度、澳大利亚、日本、英国、加拿大、沙特等各有不同）。授权码有效期仅 2 分钟。
3. 用 curl 将授权码交换为刷新令牌，保存返回的 refresh_token。
4. 查找组织 ID：CRM/Projects 通过 zoho raw GET /crm/v7/org | jq '.org[0].id' 获取；Meeting 组织 ID 需登录 Zoho Meeting 后台设置查看，与 CRM 组织 ID 不同。
5. 配置 .env 文件，包含 ZOHO_CLIENT_ID、ZOHO_CLIENT_SECRET、ZOHO_REFRESH_TOKEN、ZOHO_ORG_ID、ZOHO_MEETING_ORG_ID 以及各域名 URL（CRM、Projects、Meeting、Accounts）。非美国数据中心需调整域名。

OAuth 权限范围

• ZohoCRM.modules.ALL：读写 CRM 记录
• ZohoCRM.settings.ALL：读取字段定义和组织设置
• ZohoProjects.projects.ALL：读写项目
• ZohoProjects.tasks.ALL：读写任务、里程碑、缺陷、工时日志
• ZohoMeeting.recording.READ：列出和访问会议录制
• ZohoMeeting.meeting.READ：列出会议和会话详情
• ZohoMeeting.meetinguds.READ：下载录制文件
• ZohoFiles.files.READ：下载文件（录制、转录）

可按需请求更少权限范围，授权 URL 中 scope 参数以逗号分隔。

常用命令示例

• zoho help 显示所有命令，zoho token 打印当前访问令牌（自动刷新）。
• CRM 示例：zoho crm list Deals、zoho crm search Deals "(Stage:equals:Closed Won)"、zoho crm create Contacts '{"data":[{"Last_Name":"Smith","First_Name":"John","Email":"j@co.com"}]}'。
• Projects 示例：zoho proj list、zoho proj tasks 12345678、zoho proj create-task 12345678 "name=Fix+login+bug&priority=High&start_date=01-27-2026"。
• Meeting 示例：zoho meeting recordings、zoho meeting download "<url>" output.mp4、zoho meeting list、zoho meeting get 1066944216。

认证问题排查

• invalid_code：授权码过期（2 分钟寿命），需重做步骤 2。
• invalid_client：客户端 ID 错误或 accounts-server URL 与数据中心不匹配。
• invalid_redirect_uri：curl 中的 redirect_uri 必须与注册时完全一致。
• 令牌刷新失败：刷新令牌可能被撤销，需重新获取。
• Given URL is wrong：使用了错误数据中心对应的 API 域名。

适用场景

• 查询和更新 CRM 中的销售管道、联系人、线索等数据。
• 查看和管理项目进度、创建任务、跟踪里程碑与缺陷。
• 列出、下载会议录制，并构建自动化会议摘要流水线（例如每日站会总结）。
• 通过原始 API 调用处理未覆盖的端点或自定义模块。

限制

• CRM 速率限制为 100 请求/分钟；Projects 限制因套餐而异；Meeting 遵循标准 API 限制。
• 令牌刷新应避免过度调用（已自动缓存）。
• 授权码有效期仅 2 分钟，需及时交换。
• 非美国数据中心必须调整域名 URL 与 accounts URL。
• 刷新令牌可能被撤销，需重新生成。
• Meeting 组织 ID 与 CRM 组织 ID 不同，需单独获取。

参考链接

• CRM API Fields
• Projects API Endpoints
• Meeting API Reference