Zoho CRM API 配置和使用

---

✅ 步骤总览：

1. 注册 OAuth 应用
2. 生成授权链接并获取授权码（Authorization Code）
3. 使用授权码换取 Access Token 和 Refresh Token
4. 使用 Refresh Token 刷新 Access Token
5. 使用 Access Token 对 CRM 数据进行增删改查

---

🔧 1. 注册 OAuth 应用（创建 client_id 和 client_secret）

1. 访问 Zoho API Console:
   👉 https://api-console.zoho.com.cn/
2. 点击「Add Client」，选择 Server-based Applications（或根据你的场景选择）
3. 填写以下信息：
   o Client Name：例如 MyApp
   o Homepage URL：随便填写一个有效网址，如 https://example.com
   o Authorized Redirect URIs：填写你的回调地址（OAuth 回调使用）
    如：https://example.com/oauth/callback
4. 创建后你会获得：
   o client_id
   o client_secret

---

🔗 2. 获取 Authorization Code（授权码）
构造授权链接：
https://accounts.zoho.com.cn/oauth/v2/auth?response_type=code
&client_id=YOUR_CLIENT_ID
&scope=ZohoCRM.modules.ALL
&redirect_uri=YOUR_REDIRECT_URI
&access_type=offline
&prompt=consent
替换以下部分：
• YOUR_CLIENT_ID：你的 client_id
• YOUR_REDIRECT_URI：与 API Console 中设置的一致
🧪 示例链接：
https://accounts.zoho.com.cn/oauth/v2/auth?response_type=code
&client_id=1000.XXXXXXX
&scope=ZohoCRM.modules.ALL
&redirect_uri=https://example.com/oauth/callback
&access_type=offline
&prompt=consent
访问此链接会跳转到 Zoho 授权页面，用户登录并点击允许授权后，Zoho 会重定向到你的 redirect_uri，并带上一个 code=XXXXX 的参数 —— 这就是 Authorization Code。

---

🔁 3. 用授权码获取 Access Token 和 Refresh Token
使用授权码进行 POST 请求：
请求地址：
https://accounts.zoho.com.cn/oauth/v2/token
请求参数（application/x-www-form-urlencoded）：
参数 示例值
grant_type authorization_code
client_id 你的 client_id
client_secret 你的 client_secret
redirect_uri 你的 redirect_uri
code 第2步中获取的授权码
示例 CURL：
curl --location --request POST ‘https://accounts.zoho.com.cn/oauth/v2/token’
–header ‘Content-Type: application/x-www-form-urlencoded’
–data-urlencode ‘code=1000.xxxx’
–data-urlencode ‘client_id=1000.xxxx’
–data-urlencode ‘client_secret=xxxxxx’
–data-urlencode ‘redirect_uri=https://example.com/oauth/callback’
–data-urlencode ‘grant_type=authorization_code’
返回示例：
{
“access_token”: “1000.xxxx”,
“refresh_token”: “1000.xxxx”,
“expires_in”: 3600,
“api_domain”: “https://www.zohoapis.com”,
“token_type”: “Bearer”
}

---

♻️ 4. 用 Refresh Token 刷新 Access Token
当 Access Token 过期后（默认 1 小时），可以通过 Refresh Token 刷新：
请求地址：
https://accounts.zoho.com.cn/oauth/v2/token
请求参数：
参数 示例值
grant_type refresh_token
client_id 你的 client_id
client_secret 你的 client_secret
refresh_token 你的 refresh_token
示例 CURL：
curl --location --request POST ‘https://accounts.zoho.com.cn/oauth/v2/token’
–header ‘Content-Type: application/x-www-form-urlencoded’
–data-urlencode ‘refresh_token=1000.xxxx’
–data-urlencode ‘client_id=1000.xxxx’
–data-urlencode ‘client_secret=xxxxxx’
–data-urlencode ‘grant_type=refresh_token’

---

🔐 常见 scope 列表（授权范围）
scope 名称 权限描述
ZohoCRM.modules.ALL 所有模块的读写权限
ZohoCRM.modules.READ 所有模块的只读权限
ZohoCRM.settings.ALL 设置相关权限（字段、布局）
ZohoCRM.users.READ 用户信息读取权限

---

5. 用api或sdk访问和修改 Zoho CRM 的数据

API官方文档地址：Zoho CRM API | Online Help - Zoho CRM
SDK官方文档地址：Server SDK - Java | Online Help - Zoho CRM

下面是account的示例：

🔧 API 地址
PUT https://www.zohoapis.com.cn/crm/v2/Accounts

---

🧾 请求要求
✅ Headers：
Authorization: Zoho-oauthtoken YOUR_ACCESS_TOKEN
Content-Type: application/json

---

✅ 请求体（JSON 格式）：
你需要传入包含记录 ID 的对象数组，格式如下：
{
“data”: [
{
“id”: “ACCOUNT_RECORD_ID”,
“Account_Name”: “新的客户名称”,
“Phone”: “1234567890”,
“Website”: “https://example.com”
// 其他你要更新的字段…
}
],
“trigger”: [“workflow”]
}
⚠️ 注意：你必须提供 id，它是你要更新的 Account 的记录 ID，而不是 Account 名称。

---

示例：Python 请求代码
import requests

url = “https://www.zohoapis.com.cn/crm/v2/Accounts”
access_token = “YOUR_ACCESS_TOKEN”
account_id = “1234567890000001234” # 要修改的记录 ID

headers = {
“Authorization”: f"Zoho-oauthtoken {access_token}",
“Content-Type”: “application/json”
}

data = {
“data”: [
{
“id”: account_id,
“Account_Name”: “新客户名称”,
“Website”: “https://newwebsite.com”
}
],
“trigger”: [“workflow”] # 是否触发工作流，可选：[“workflow”, “approval”, “blueprint”]
}

response = requests.put(url, headers=headers, json=data)

print(response.status_code)
print(response.json())

---

🔍 如何获取 account_id
你可以使用以下 API 获取：
GET https://www.zohoapis.com.cn/crm/v2/Accounts?criteria=(Account_Name:equals:xxx)
或者直接查列表分页：
GET https://www.zohoapis.com.cn/crm/v2/Accounts?page=1&per_page=10

---

✅ 成功响应（示例）
{
“data”: [
{
“code”: “SUCCESS”,
“details”: {
“id”: “1234567890000001234”
},
“message”: “record updated”,
“status”: “success”
}
]
}

---

✅ 总结
操作 说明
修改 Account 记录 使用 PUT /crm/v2/Accounts 接口
必填字段 id（记录 ID），以及你要修改的字段
是否触发工作流 可设置 “trigger”: [“workflow”]
API 响应成功码 “status”: “success”