介绍
# Zoho Bigin
通过托管的 OAuth 身份验证访问 Zoho Bigin API。使用完整的 CRUD 操作管理联系人、公司、管道和产品。
## 快速开始
```bash # List contacts python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://gateway.maton.ai/zoho-bigin/bigin/v2/Contacts?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-bigin/bigin/v2/{endpoint} ```
网关将请求代理到 `www.zohoapis.com/bigin/v2`，并自动注入您的 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 Bigin OAuth 连接。
### 列出连接
```bash python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://ctrl.maton.ai/connections?app=zoho-bigin&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-bigin'}).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": "21fd90f9-5935-43cd-b6c8-bde9d915ca80", "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-bigin", "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 Bigin 连接，请使用 `Maton-Connection` 标头指定要使用的连接：
```bash python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://gateway.maton.ai/zoho-bigin/bigin/v2/Contacts?fields=First_Name,Last_Name,Email') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') req.add_header('Maton-Connection', '21fd90f9-5935-43cd-b6c8-bde9d915ca80') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ```
如果省略，网关将使用默认（最旧的）活动连接。
## API 参考
### 模块
Zoho Bigin 将数据组织成模块。可用模块包括：
| 模块 | API 名称 | 描述 | |--------|----------|-------------| | 联系人 | `Contacts` | 个人 | | 公司 | `Accounts` | 组织/企业 | | 管道 | `Pipelines` | 销售机会/交易 | | 产品 | `Products` | 您销售的商品 | | 任务 | `Tasks` | 待办事项（需要额外的 OAuth 范围） | | 活动 | `Events` | 日历约会（需要额外的 OAuth 范围） | | 呼叫 | `Calls` | 电话通话记录（需要额外的 OAuth 范围） | | 备注 | `Notes` | 附加到记录的备注（需要额外的 OAuth 范围） |
### 列出记录
```bash GET /zoho-bigin/bigin/v2/{module_api_name}?fields={field1},{field2} ```
**查询参数：**
| 参数 | 类型 | 描述 | |-----------|------|-------------| | `fields` | string | **必需。** 要检索的以逗号分隔的字段 API 名称 | | `sort_order` | string | `asc` 或 `desc` | | `sort_by` | string | 排序依据的字段 API 名称 | | `page` | integer | 页码（默认：1） | | `per_page` | integer | 每页记录数（默认：200，最大：200） | | `cvid` | string | 用于过滤结果的自定义视图 ID |
**示例 - 列出联系人：**
```bash python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://gateway.maton.ai/zoho-bigin/bigin/v2/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 ```
**响应：** ```json { "data": [ { "First_Name": "Ted", "Email": "[email protected]", "Last_Name": "Watson", "id": "7255024000000596045" } ], "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-bigin/bigin/v2/Accounts?fields=Account_Name,Website') 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-bigin/bigin/v2/{module_api_name}/{record_id} ```
**示例：**
```bash python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://gateway.maton.ai/zoho-bigin/bigin/v2/Contacts/7255024000000596045') 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-bigin/bigin/v2/{module_api_name} Content-Type: application/json
{ "data": [ { "field_api_name": "value" } ] } ```
**按模块分类的必填字段：**
| 模块 | 必填字段 | |--------|-----------------| | 联系人 | `Last_Name` | | 公司 | `Account_Name` | | 管道 | `Pipeline_Name`, `Stage` | | 产品 | `Product_Name` |
**示例 - 创建联系人：**
```bash python <<'EOF' import urllib.request, os, json data = json.dumps({ "data": [{ "Last_Name": "Smith", "First_Name": "John", "Email": "[email protected]", "Phone": "+1-555-0123" }] }).encode() req = urllib.request.Request('https://gateway.maton.ai/zoho-bigin/bigin/v2/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 ```
**响应：** ```json { "data": [ { "code": "SUCCESS", "details": { "Modified_Time": "2026-02-06T00:28:53-08:00", "Modified_By": { "name": "User Name", "id": "7255024000000590001" }, "Created_Time": "2026-02-06T00:28:53-08:00", "id": "7255024000000605002", "Created_By": { "name": "User Name", "id": "7255024000000590001" } }, "message": "record added", "status": "success" } ] } ```
**示例 - 创建公司：**
```bash python <<'EOF' import urllib.request, os, json data = json.dumps({ "data": [{ "Account_Name": "Acme Corporation", "Website": "https://acme.com" }] }).encode() req = urllib.request.Request('https://gateway.maton.ai/zoho-bigin/bigin/v2/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-bigin/bigin/v2/{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": "7255024000000605002", "Phone": "+1-555-9999" }] }).encode() req = urllib.request.Request('https://gateway.maton.ai/zoho-bigin/bigin/v2/Contacts', 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-06T00:29:07-08:00", "id": "7255024000000605002" }, "message": "record updated", "status": "success" } ] } ```
### 删除记录
```bash DELETE /zoho-bigin/bigin/v2/{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-bigin/bigin/v2/Contacts?ids=7255024000000605002', 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": "7255024000000605002" }, "message": "record deleted", "status": "success" } ] } ```
### 搜索记录
```bash GET /zoho-bigin/bigin/v2/{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`、`starts_with`
**示例 - 按电子邮件搜索：**
```bash python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://gateway.maton.ai/zoho-bigin/bigin/v2/Contacts/[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:equals:Watson)') req = urllib.request.Request(f'https://gateway.maton.ai/zoho-bigin/bigin/v2/Contacts/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 ```
### 元数据 API
#### 获取模块
```bash GET /zoho-bigin/bigin/v2/settings/modules ```
**示例：**
```bash python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://gateway.maton.ai/zoho-bigin/bigin/v2/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 ```
#### 获取用户
```bash GET /zoho-bigin/bigin/v2/users ```
**查询参数：**
| 参数 | 类型 | 描述 | |-----------|------|-------------| | `type` | string | `AllUsers`、`ActiveUsers`、`AdminUsers`、`CurrentUser` | | `page` | integer | 页码 | | `per_page` | integer | 每页用户数（最大 200） |
**示例：**
```bash python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://gateway.maton.ai/zoho-bigin/bigin/v2/users?type=ActiveUsers') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ```
## 分页
Zoho Bigin 使用基于页面的分页，包含 `page` 和 `per_page` 参数：
```bash GET /zoho-bigin/bigin/v2/{module_api_name}?fields=First_Name,Last_Name&page=1&per_page=50 ```
响应包含分页信息：
```json { "data": [...], "info": { "per_page": 50, "count": 50, "page": 1, "more_records": true } } ```
当 `more_records` 为 `true` 时继续获取，每次递增 `page`。
## 代码示例
### JavaScript
```javascript const response = await fetch( 'https://gateway.maton.ai/zoho-bigin/bigin/v2/Contacts?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-bigin/bigin/v2/Contacts', headers={'Authorization': f'Bearer {os.environ["MATON_API_KEY"]}'}, params={'fields': 'First_Name,Last_Name,Email'} ) data = response.json() ```
## 注意事项
- 列表操作**必需** `fields` 参数 - 模块 API 名称区分大小写（例如，`Contacts`，而不是 `contacts`） - 公司通过 `Accounts` 模块 API 名称访问 - 销售机会通过 `Pipelines` 模块访问（而不是 `Deals`） - 每个创建/更新请求最多 100 条记录 - 每个删除请求最多 100 条记录 - 每个 GET 请求最多返回 200 条记录 - 在请求中使用字段 API 名称（而不是显示名称） - 某些模块（Tasks、Events、Calls、Notes）需要额外的 OAuth 范围。如果您收到范围错误，请联系 Maton 支持部门 [email protected]，说明您需要的具体操作/API 以及您的用例 - 重要：使用 curl 命令时，如果 URL 包含方括号，请使用 `curl -g` 以禁用 glob 解析 - 重要：将 curl 输出通过管道传输到 `jq` 或其他命令时，在某些 shell 环境中，像 `$MATON_API_KEY` 这样的环境变量可能无法正确展开
## 错误处理
| 状态 | 含义 | |--------|---------| | 400 | 缺少 Zoho Bigin 连接、缺少必填参数或请求无效 | | 401 | Maton API 密钥无效或缺失，或 OAuth 范围不匹配 | | 404 | URL 模式无效或未找到资源 | | 429 | 速率受限 | | 4xx/5xx | 来自 Zoho Bigin API 的透传错误 |
### 常见错误代码
| 代码 | 描述 | |------|-------------| | `REQUIRED_PARAM_MISSING` | 缺少必填参数（如 `fields`） | | `INVALID_URL_PATTERN` | API 端点路径无效 | | `INVALID_MODULE` | 模块不存在或不受 API 支持 | | `OAUTH_SCOPE_MISMATCH` | OAuth 令牌缺少端点所需的权限 | | `NO_PERMISSION` | 操作权限不足 | | `MANDATORY_NOT_FOUND` | 缺少必填字段 | | `INVALID_DATA` | 数据类型不匹配或格式错误 | | `DUPLICATE_DATA` | 记录违反唯一字段约束 |
### 故障排除：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-bigin` 开头。例如：
- 正确：`https://gateway.maton.ai/zoho-bigin/bigin/v2/Contacts` - 错误：`https://gateway.maton.ai/bigin/v2/Contacts`
## 资源
- [Bigin API 概述](https://www.bigin.com/developer/docs/apis/v2/) - [Bigin REST API 文档](https://www.bigin.com/developer/docs/apis/) - [模块 API](https://www.bigin.com/developer/docs/apis/modules-api.html) - [Maton 社区](https://discord.com/invite/dBfFAcefs2) - [Maton 支持](mailto:[email protected])