基础URL

https://gateway.maton.ai/zoho-bigin/bigin/v2/{endpoint}

该网关将请求代理到 www.zohoapis.com/bigin/v2，并自动注入您的OAuth令牌。

认证

所有请求都需要在Authorization头中包含Maton API密钥：

Authorization: Bearer $MATONAPIKEY

环境变量： 将您的API密钥设置为 MATONAPIKEY：

bash
export MATONAPIKEY=YOURAPIKEY

获取您的API密钥

1. 1. 登录或创建账户：maton.ai
2. 前往 maton.ai/settings
3. 复制您的API密钥

连接管理

在 https://ctrl.maton.ai 管理您的Zoho Bigin OAuth连接。

列出连接

bash
python < import urllib.request, os, json
req = urllib.request.Request(https://ctrl.maton.ai/connections?app=zoho-bigin&status=ACTIVE)
req.addheader(Authorization, fBearer {os.environ[MATONAPI_KEY]})
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

创建连接

bash
python < 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.addheader(Authorization, fBearer {os.environ[MATONAPI_KEY]})
req.add_header(Content-Type, application/json)
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

获取连接

bash
python < import urllib.request, os, json
req = urllib.request.Request(https://ctrl.maton.ai/connections/{connection_id})
req.addheader(Authorization, fBearer {os.environ[MATONAPI_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,
lastupdatedtime: 2026-01-31T20:03:32.593153Z,
url: https://connect.maton.ai/?session_token=...,
app: zoho-bigin,
metadata: {}
}
}

在浏览器中打开返回的 url 以完成OAuth授权。

删除连接

bash
python < import urllib.request, os, json
req = urllib.request.Request(https://ctrl.maton.ai/connections/{connection_id}, method=DELETE)
req.addheader(Authorization, fBearer {os.environ[MATONAPI_KEY]})
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

指定连接

如果您有多个Zoho Bigin连接，请使用 Maton-Connection 头指定使用哪个连接：

bash
python < import urllib.request, os, json
req = urllib.request.Request(https://gateway.maton.ai/zoho-bigin/bigin/v2/Contacts?fields=FirstName,LastName,Email)
req.addheader(Authorization, fBearer {os.environ[MATONAPI_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将数据组织成模块。可用的模块包括：

列出记录

bash
GET /zoho-bigin/bigin/v2/{moduleapiname}?fields={field1},{field2}

查询参数：

示例 - 列出联系人：

bash
python < import urllib.request, os, json
req = urllib.request.Request(https://gateway.maton.ai/zoho-bigin/bigin/v2/Contacts?fields=FirstName,LastName,Email,Phone)
req.addheader(Authorization, fBearer {os.environ[MATONAPI_KEY]})
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

响应：
json
{
data: [
{
First_Name: Ted,
Email: support@bigin.com,
Last_Name: Watson,
id: 7255024000000596045
}
],
info: {
per_page: 200,
count: 1,
page: 1,
more_records: false
}
}

示例 - 列出公司（账户）：

bash
python < import urllib.request, os, json
req = urllib.request.Request(https://gateway.maton.ai/zoho-bigin/bigin/v2/Accounts?fields=Account_Name,Website)
req.addheader(Authorization, fBearer {os.environ[MATONAPI_KEY]})
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

获取记录

bash
GET /zoho-bigin/bigin/v2/{moduleapiname}/{record_id}

示例：

bash
python < import urllib.request, os, json
req = urllib.request.Request(https://gateway.maton.ai/zoho-bigin/bigin/v2/Contacts/7255024000000596045)
req.addheader(Authorization, fBearer {os.environ[MATONAPI_KEY]})
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

创建记录

bash
POST /zoho-bigin/bigin/v2/{moduleapiname}
Content-Type: application/json

{
data: [
{
fieldapiname: value
}
]
}

各模块必填字段：

示例 - 创建联系人：

bash
python < import urllib.request, os, json
data = json.dumps({
data: [{
Last_Name: Smith,
First_Name: John,
Email: john.smith@example.com,
Phone: +1-555-0123
}]
}).encode()
req = urllib.request.Request(https://gateway.maton