介绍
# Zoho CRM
通过托管的 OAuth 身份验证访问 Zoho CRM API。使用完整的 CRUD 操作（包括搜索和批量操作）管理线索、联系人、客户、交易和其他 CRM 模块。还支持组织详细信息、用户管理和模块元数据检索。
## 快速开始
```bash # List leads python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://gateway.maton.ai/zoho-crm/crm/v8/Leads?fields=First_Name,Last_Name,Email') 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/zoho-crm/crm/v8/{endpoint} ```
网关将请求代理到 `www.zohoapis.com/crm/v8` 并自动注入您的 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` 管理您的 Zoho CRM OAuth 连接。
### 列出连接
```bash python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://ctrl.maton.ai/connections?app=zoho-crm&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': 'zoho-crm'}).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": "e55c5bac-241a-4cc8-9db5-50d2cad09136", "status": "ACTIVE", "creation_time": "2025-12-08T07:20:53.488460Z", "last_updated_time": "2026-01-31T20:03:32.593153Z", "url": "https://connect.maton.ai/?session_token=...", "app": "zoho-crm", "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 ```
### 指定连接
如果您有多个 Zoho CRM 连接，请使用 `Maton-Connection` 请求头指定要使用的连接：
```bash python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://gateway.maton.ai/zoho-crm/crm/v8/Leads?fields=First_Name,Last_Name,Email') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') req.add_header('Maton-Connection', 'e55c5bac-241a-4cc8-9db5-50d2cad09136') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ```
如果省略，网关将使用默认（最早）的活动连接。
## API 参考
### 模块
Zoho CRM 将数据组织成模块。核心模块包括：
| 模块 | API 名称 | 描述 | |--------|----------|-------------| | Leads | `Leads` | 潜在客户 | | Contacts | `Contacts` | 个人联系人 | | Accounts | `Accounts` | 组织/公司 | | Deals | `Deals` | 销售机会 | | Campaigns | `Campaigns` | 营销活动 | | Tasks | `Tasks` | 待办事项 | | Calls | `Calls` | 电话记录 | | Events | `Events` | 日历约会 | | Products | `Products` | 您销售的产品 |
### 列出记录
```bash GET /zoho-crm/crm/v8/{module_api_name}?fields={field1},{field2} ```
**查询参数：**
| 参数 | 类型 | 描述 | |-----------|------|-------------| | `fields` | string | **必填。** 逗号分隔的字段 API 名称（最多 50 个） | | `page` | integer | 页码（默认：1） | | `per_page` | integer | 每页记录数（默认/最大：200） | | `sort_by` | string | 排序依据：`id`、`Created_Time` 或 `Modified_Time` | | `sort_order` | string | `asc` 或 `desc`（默认） | | `cvid` | long | 自定义视图 ID | | `page_token` | string | 用于超过 2000 条记录的分页 |
**示例 - 列出线索：**
```bash python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://gateway.maton.ai/zoho-crm/crm/v8/Leads?fields=First_Name,Last_Name,Email,Phone,Company') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ```
**响应：** ```json { "data": [ { "First_Name": "Christopher", "Email": "[email protected]", "Last_Name": "Maclead (Sample)", "Phone": "555-555-5555", "Company": "Rangoni Of Florence", "id": "7243485000000597000" } ], "info": { "per_page": 200, "count": 1, "page": 1, "sort_by": "id", "sort_order": "desc", "more_records": false, "next_page_token": null } } ```
**示例 - 列出联系人：**
```bash python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://gateway.maton.ai/zoho-crm/crm/v8/Contacts?fields=First_Name,Last_Name,Email,Phone') 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 req = urllib.request.Request('https://gateway.maton.ai/zoho-crm/crm/v8/Accounts?fields=Account_Name,Website,Phone') 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 req = urllib.request.Request('https://gateway.maton.ai/zoho-crm/crm/v8/Deals?fields=Deal_Name,Stage,Amount') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ```
### 获取记录
```bash GET /zoho-crm/crm/v8/{module_api_name}/{record_id} ```
**示例：**
```bash python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://gateway.maton.ai/zoho-crm/crm/v8/Leads/7243485000000597000') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ```
### 创建记录
```bash POST /zoho-crm/crm/v8/{module_api_name} Content-Type: application/json
{ "data": [ { "field_api_name": "value" } ] } ```
**按模块划分的必填字段：**
| 模块 | 必填字段 | |--------|-----------------| | Leads | `Last_Name` | | Contacts | `Last_Name` | | Accounts | `Account_Name` | | Deals | `Deal_Name`, `Stage` | | Tasks | `Subject` | | Calls | `Subject`, `Call_Type`, `Call_Start_Time`, `Call_Duration` | | Events | `Event_Title`, `Start_DateTime`, `End_DateTime` |
**示例 - 创建线索：**
```bash python <<'EOF' import urllib.request, os, json data = json.dumps({ "data": [{ "Last_Name": "Smith", "First_Name": "John", "Email": "[email protected]", "Company": "Acme Corp", "Phone": "+1-555-0123" }] }).encode() req = urllib.request.Request('https://gateway.maton.ai/zoho-crm/crm/v8/Leads', 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 ```
**响应：** ```json { "data": [ { "code": "SUCCESS", "details": { "Modified_Time": "2026-02-06T01:10:56-08:00", "Modified_By": { "name": "User Name", "id": "7243485000000590001" }, "Created_Time": "2026-02-06T01:10:56-08:00", "id": "7243485000000619001", "Created_By": { "name": "User Name", "id": "7243485000000590001" } }, "message": "record added", "status": "success" } ] } ```
**示例 - 创建联系人：**
```bash python <<'EOF' import urllib.request, os, json data = json.dumps({ "data": [{ "Last_Name": "Doe", "First_Name": "Jane", "Email": "[email protected]", "Phone": "+1-555-9876" }] }).encode() req = urllib.request.Request('https://gateway.maton.ai/zoho-crm/crm/v8/Contacts', 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 data = json.dumps({ "data": [{ "Account_Name": "Acme Corporation", "Website": "https://acme.com", "Phone": "+1-555-1234" }] }).encode() req = urllib.request.Request('https://gateway.maton.ai/zoho-crm/crm/v8/Accounts', 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 PUT /zoho-crm/crm/v8/{module_api_name} Content-Type: application/json
{ "data": [ { "id": "record_id", "field_api_name": "updated_value" } ] } ```
**示例：**
```bash python <<'EOF' import urllib.request, os, json data = json.dumps({ "data": [{ "id": "7243485000000619001", "Phone": "+1-555-9999", "Company": "Updated Company Name" }] }).encode() req = urllib.request.Request('https://gateway.maton.ai/zoho-crm/crm/v8/Leads', data=data, method='PUT') 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 ```
**响应：** ```json { "data": [ { "code": "SUCCESS", "details": { "Modified_Time": "2026-02-06T01:11:01-08:00", "Modified_By": { "name": "User Name", "id": "7243485000000590001" }, "Created_Time": "2026-02-06T01:10:56-08:00", "id": "7243485000000619001", "Created_By": { "name": "User Name", "id": "7243485000000590001" } }, "message": "record updated", "status": "success" } ] } ```
### 删除记录
```bash DELETE /zoho-crm/crm/v8/{module_api_name}?ids={record_id1},{record_id2} ```
**查询参数：**
| 参数 | 类型 | 描述 | |-----------|------|-------------| | `ids` | string | 逗号分隔的记录 ID（必填，最多 100 个） | | `wf_trigger` | boolean | 执行工作流（默认：true） |
**示例：**
```bash python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://gateway.maton.ai/zoho-crm/crm/v8/Leads?ids=7243485000000619001', 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 ```
**响应：** ```json { "data": [ { "code": "SUCCESS", "details": { "id": "7243485000000619001" }, "message": "record deleted", "status": "success" } ] } ```
### 搜索记录
```bash GET /zoho-crm/crm/v8/{module_api_name}/search ```
**查询参数（必填其一）：**
| 参数 | 类型 | 描述 | |-----------|------|-------------| | `criteria` | string | 搜索条件（例如 `(Last_Name:equals:Smith)`） | | `email` | string | 按电子邮件地址搜索 | | `phone` | string | 按电话号码搜索 | | `word` | string | 全局文本搜索 | | `page` | integer | 页码 | | `per_page` | integer | 每页记录数（最多 200） |
**条件格式：** `((field_api_name:operator:value) and/or (...))`
**运算符：** - 文本字段：`equals`、`not_equal`、`starts_with`、`in` - 日期/数字字段：`equals`、`not_equal`、`greater_than`、`less_than`、`between`、`in` - 布尔字段：`equals`、`not_equal`
**示例 - 按电子邮件搜索：**
```bash python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://gateway.maton.ai/zoho-crm/crm/v8/Leads/[email protected]') 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 import urllib.parse criteria = urllib.parse.quote('(Last_Name:starts_with:Smith)') req = urllib.request.Request(f'https://gateway.maton.ai/zoho-crm/crm/v8/Leads/search?criteria={criteria}') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ```
**响应：** ```json { "data": [ { "First_Name": "Christopher", "Email": "[email protected]", "Last_Name": "Maclead (Sample)", "id": "7243485000000597000" } ], "info": { "per_page": 200, "count": 1, "page": 1, "more_records": false } } ```
### 组织详情
检索您的 Zoho CRM 组织详细信息。
```bash GET /zoho-crm/crm/v8/org ```
**示例：**
```bash python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://gateway.maton.ai/zoho-crm/crm/v8/org') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ```
**响应：** ```json { "org": [ { "id": "7243485000000020005", "company_name": "Acme Corp", "domain_name": "org123456789", "primary_email": "[email protected]", "phone": "555-555-5555", "currency": "US Dollar - USD", "currency_symbol": "$", "iso_code": "USD", "time_zone": "PST", "country_code": "US", "zgid": "123456789", "type": "production", "mc_status": false, "license_details": { "paid": true, "paid_type": "enterprise", "users_license_purchased": 10, "trial_expiry": null } } ] } ```
### 用户
检索您 Zoho CRM 组织中的用户。
```bash GET /zoho-crm/crm/v8/users ```
**查询参数：**
| 参数 | 类型 | 描述 | |-----------|------|-------------| | `type` | string | 按用户类型筛选：`AllUsers`、`ActiveUsers`、`DeactiveUsers`、`ConfirmedUsers`、`NotConfirmedUsers`、`DeletedUsers`、`ActiveConfirmedUsers`、`AdminUsers`、`ActiveConfirmedAdmins`、`CurrentUser` | | `page` | integer | 页码（默认：1） | | `per_page` | integer | 每页记录数（默认/最大：200） | | `ids` | string | 逗号分隔的用户 ID（最多 100 个） |
**示例 - 列出所有用户：**
```bash python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://gateway.maton.ai/zoho-crm/crm/v8/users?type=AllUsers') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ```
**响应：** ```json { "users": [ { "id": "7243485000000590001", "first_name": "John", "last_name": "Doe", "full_name": "John Doe", "email": "[email protected]", "status": "active", "confirm": true, "role": { "name": "CEO", "id": "7243485000000026005" }, "profile": { "name": "Administrator", "id": "7243485000000026011" }, "time_zone": "PST", "country": "US", "locale": "en_US" } ], "info": { "per_page": 200, "count": 1, "page": 1, "more_records": false } } ```
**示例 - 获取特定用户：**
```bash python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://gateway.maton.ai/zoho-crm/crm/v8/users/7243485000000590001') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ```
### 模块元数据
检索所有可用 CRM 模块的元数据。
```bash GET /zoho-crm/crm/v8/settings/modules ```
**查询参数：**
| 参数 | 类型 | 描述 | |-----------|------|-------------| | `status` | string | 按状态筛选：`user_hidden`、`system_hidden`、`scheduled_for_deletion`、`visible` |
**示例：**
```bash python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://gateway.maton.ai/zoho-crm/crm/v8/settings/modules') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ```
**响应：** ```json { "modules": [ { "api_name": "Leads", "module_name": "Leads", "singular_label": "Lead", "plural_label": "Leads", "api_supported": true, "creatable": true, "editable": true, "deletable": true, "viewable": true, "status": "visible", "generated_type": "default", "id": "7243485000000002175", "profiles": [ {"name": "Administrator", "id": "7243485000000026011"} ] } ] } ```
### 字段元数据
检索特定模块的字段元数据。
```bash GET /zoho-crm/crm/v8/settings/fields?module={module_api_name} ```
**查询参数：**
| 参数 | 类型 | 描述 | |-----------|------|-------------| | `module` | string | **必填。** 模块的 API 名称（例如 `Leads`、`Contacts`） | | `type` | string | `all` 表示所有字段，`unused` 表示仅未使用的字段 |
**示例：**
```bash python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://gateway.maton.ai/zoho-crm/crm/v8/settings/fields?module=Leads') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ```
**响应：** ```json { "fields": [ { "api_name": "Last_Name", "field_label": "Last Name", "data_type": "text", "system_mandatory": true, "custom_field": false, "visible": true, "searchable": true, "sortable": true, "id": "7243485000000002613" } ] } ```
### 布局元数据
检索特定模块的布局元数据。
```bash GET /zoho-crm/crm/v8/settings/layouts?module={module_api_name} ```
**查询参数：**
| 参数 | 类型 | 描述 | |-----------|------|-------------| | `module` | string | **必填。** 模块的 API 名称（例如 `Leads`、`Contacts`） |
**示例：**
```bash python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://gateway.maton.ai/zoho-crm/crm/v8/settings/layouts?module=Leads') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ```
**响应：** ```json { "layouts": [ { "id": "7243485000000091055", "name": "Standard", "api_name": "Standard", "status": "active", "visible": true, "profiles": [ {"name": "Administrator", "id": "7243485000000026011"} ], "sections": [ { "display_label": "Lead Information", "api_name": "Lead_Information", "sequence_number": 1, "fields": [...] } ] } ] } ```
### 角色
检索您 Zoho CRM 组织中的角色。
```bash GET /zoho-crm/crm/v8/settings/roles ```
**示例：**
```bash python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://gateway.maton.ai/zoho-crm/crm/v8/settings/roles') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ```
**响应：** ```json { "roles": [ { "id": "7243485000000026005", "name": "CEO", "display_label": "CEO", "share_with_peers": true, "description": null, "reporting_to": null }, { "id": "7243485000000026008", "name": "Manager", "display_label": "Manager", "share_with_peers": false, "reporting_to": { "name": "CEO", "id": "7243485000000026005" } } ] } ```
**示例 - 获取特定角色：**
```bash python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://gateway.maton.ai/zoho-crm/crm/v8/settings/roles/7243485000000026005') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ```
### 权限配置文件
检索您 Zoho CRM 组织中的权限配置文件（权限集）。
```bash GET /zoho-crm/crm/v8/settings/profiles ```
**示例：**
```bash python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://gateway.maton.ai/zoho-crm/crm/v8/settings/profiles') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ```
**响应：** ```json { "profiles": [ { "id": "7243485000000026011", "name": "Administrator", "display_label": "Administrator", "type": "normal_profile", "custom": false, "description": null }, { "id": "7243485000000026014", "name": "Standard", "display_label": "Standard", "type": "normal_profile", "custom": false, "description": null } ] } ```
**示例 - 获取特定权限配置文件：**
```bash python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://gateway.maton.ai/zoho-crm/crm/v8/settings/profiles/7243485000000026011') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ```
## 分页
Zoho CRM 使用基于页码的分页，对于大型数据集可选使用分页令牌：
```bash GET /zoho-crm/crm/v8/{module_api_name}?fields=First_Name,Last_Name&page=1&per_page=50 ```
响应包含分页信息：
```json { "data": [...], "info": { "per_page": 50, "count": 50, "page": 1, "sort_by": "id", "sort_order": "desc", "more_records": true, "next_page_token": "token_value", "page_token_expiry": "2026-02-07T01:10:56-08:00" } } ```
- 对于多达 2,000 条记录：使用 `page` 参数（每次请求递增） - 对于 2,000 条以上记录：使用上一次响应中的 `page_token` - 分页令牌在 24 小时后过期
## 代码示例
### JavaScript
```javascript const response = await fetch( 'https://gateway.maton.ai/zoho-crm/crm/v8/Leads?fields=First_Name,Last_Name,Email', { 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/zoho-crm/crm/v8/Leads', headers={'Authorization': f'Bearer {os.environ["MATON_API_KEY"]}'}, params={'fields': 'First_Name,Last_Name,Email'} ) data = response.json() ```
## 注意事项
- `fields` 参数对于列表操作是**必填**的（最多 50 个字段） - 模块 API 名称区分大小写（例如 `Leads`，而不是 `leads`） - 每次创建/更新请求最多 100 条记录 - 每次删除请求最多 100 条记录 - 每次 GET 请求最多返回 200 条记录 - 没有 `page_token` 最多 2,000 条记录；使用 `page_token` 最多可达 100,000 条记录 - 在请求中使用字段 API 名称（而不是显示名称） - 如果您收到范围错误，请联系 Maton 支持团队 [email protected]，提供您需要的具体操作/API 以及您的用例 - 空数据集返回 HTTP 204（无内容），且 body 为空 - **重要**：使用 curl 命令时，如果 URL 包含括号，请使用 `curl -g` 以禁用 glob 解析 - **重要**：将 curl 输出通过管道传递给 `jq` 或其他命令时，在某些 shell 环境中，`$MATON_API_KEY` 等环境变量可能无法正确展开
## 错误处理
| 状态 | 含义 | |--------|---------| | 400 | 缺少 Zoho CRM 连接、缺少必填参数或请求无效 | | 401 | Maton API 密钥无效或缺失，或 OAuth 范围不匹配 | | 404 | 资源未找到 | | 429 | 请求频率受限 | | 4xx/5xx | 来自 Zoho CRM API 的透传错误 |
### 常见错误代码
| 代码 | 描述 | |------|-------------| | `OAUTH_SCOPE_MISMATCH` | OAuth 令牌缺少端点所需的权限 | | `MANDATORY_NOT_FOUND` | 缺少必填字段 | | `INVALID_DATA` | 数据类型不匹配或格式错误 | | `DUPLICATE_DATA` | 记录违反了唯一字段约束 | | `RECORD_NOT_FOUND` | 指定的记录 ID 不存在 |
### 故障排除：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 路径以 `zoho-crm` 开头。例如：
- 正确：`https://gateway.maton.ai/zoho-crm/crm/v8/Leads` - 错误：`https://gateway.maton.ai/crm/v8/Leads`
## 资源
- [Zoho CRM API v8 文档](https://www.zoho.com/crm/developer/docs/api/v8/) - [获取记录 API](https://www.zoho.com/crm/developer/docs/api/v8/get-records.html) - [插入记录 API](https://www.zoho.com/crm/developer/docs/api/v8/insert-records.html) - [更新记录 API](https://www.zoho.com/crm/developer/docs/api/v8/update-records.html) - [删除记录 API](https://www.zoho.com/crm/developer/docs/api/v8/delete-records.html) - [搜索记录 API](https://www.zoho.com/crm/developer/docs/api/v8/search-records.html) - [组织 API](https://www.zoho.com/crm/developer/docs/api/v8/get-org-data.html) - [用户 API](https://www.zoho.com/crm/developer/docs/api/v8/get-users.html) - [模块 API](https://www.zoho.com/crm/developer/docs/api/v8/modules-api.html) - [字段 API](https://www.zoho.com/crm/developer/docs/api/v8/field-meta.html) - [布局 API](https://www.zoho.com/crm/developer/docs/api/v8/layouts-meta.html) - [角色 API](https://www.zoho.com/crm/developer/docs/api/v8/get-roles.html) - [权限配置 API](https://www.zoho.com/crm/developer/docs/api/v8/get-profiles.html) - [Maton 社区](https://discord.com/invite/dBfFAcefs2) - [Maton 支持](mailto:[email protected])