基础URL

https://gateway.maton.ai/zoho-people/{原生API路径}

将{原生API路径}替换为实际的Zoho People API端点路径。网关会将请求代理到people.zoho.com并自动注入您的OAuth令牌。

认证

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

Authorization: Bearer $MATONAPIKEY

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

bash
export MATONAPIKEY=您的API密钥

获取您的API密钥

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

连接管理

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

列出连接

bash
python < import urllib.request, os, json
req = urllib.request.Request(https://ctrl.maton.ai/connections?app=zoho-people&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-people}).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: 7d11ea2e-c580-43fe-bc56-d9d4765b9bc6,
status: ACTIVE,
creation_time: 2026-02-06T07:42:07.681370Z,
lastupdatedtime: 2026-02-06T07:46:12.648445Z,
url: https://connect.maton.ai/?session_token=...,
app: zoho-people,
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 People连接，请使用Maton-Connection头指定要使用的连接：

bash
python < import urllib.request, os, json
req = urllib.request.Request(https://gateway.maton.ai/zoho-people/people/api/forms)
req.addheader(Authorization, fBearer {os.environ[MATONAPI_KEY]})
req.add_header(Maton-Connection, 7d11ea2e-c580-43fe-bc56-d9d4765b9bc6)
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

如果省略此头，网关将使用默认（最早创建的）活动连接。

API参考

表单操作

列出所有表单

获取Zoho People账户中所有可用表单的列表。

bash
GET /zoho-people/people/api/forms

示例：

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

响应：
json
{
response: {
result: [
{
componentId: 943596000000035679,
iscustom: false,
displayName: Employee,
formLinkName: employee,
PermissionDetails: {
Add: 3,
Edit: 3,
View: 3
},
isVisible: true,
viewDetails: {
view_Id: 943596000000035705,
viewName: PEmployeeView
}
}
],
message: Data fetched successfully,
status: 0
}
}

员工操作

列出员工（批量记录）

bash
GET /zoho-people/people/api/forms/employee/getRecords?sIndex={起始索引}&limit={数量}

查询参数：

示例：

bash
python < import urllib.request, os, json
req = urllib.request.Request(https://gateway.maton.ai/zoho-people/people/api/forms/employee/getRecords?sIndex=1&limit=10)
req.addheader(Authorization, fBearer {os.environ[MATONAPI_KEY]})
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

响应：
json
{
response: {
result: [
{
943596000000294355: [
{
FirstName: Christopher,
LastName: Brown,
EmailID: christopherbrown@zylker.com,
EmployeeID: S20,
Department: Management,
Designation: Administration,
Employeestatus: Active,
Gender: Male,
Dateofbirth: 02-Feb-1987,
Zoho_ID: 943596000000294355
}
]
}
],
message: Data fetched successfully,
status: 0
}
}

列出员工（基于视图）

bash
GET /zoho-people/api/forms/{视图名称}/records?rec_limit={数量}

示例：

bash
python < import urllib.request, os, json
req = urllib.request.Request(https://gateway.maton.ai/zoho-people/api/forms/PEmployeeView/records?reclimit=10)
req.addheader(Authorization, fBearer {os.environ[MATONAPI_KEY]})
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

按ID搜索员工

bash
GET /zoho-people/people/api/forms/employee/getRecords?SearchColumn=EMPLOYEEID&SearchValue={员工ID}

示例：

bash
python < import urllib.request, os, json
req = urllib.request.Request(https://gateway.maton.ai/zoho-people/people/api/forms/employee/getRecords?SearchColumn=EMPLOYEEID&SearchValue=S20)
req.addheader(Authorization, fBearer {os.environ[MATONAPI_KEY]})
print(json.dumps(json.load(urllib.request.urlopen(req