介绍
# Zoho People
通过托管的 OAuth 身份验证访问 Zoho People API。使用完整的 CRUD 操作管理员工、部门、职位、考勤、请假和自定义 HR 表单。
## 快速开始
```bash # List all employees python <<'EOF' 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.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-people/{native-api-path} ```
将 `{native-api-path}` 替换为实际的 Zoho People API 端点路径。网关将请求代理到 `people.zoho.com` 并自动注入您的 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 People OAuth 连接。
### 列出连接
```bash python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://ctrl.maton.ai/connections?app=zoho-people&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-people'}).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": "7d11ea2e-c580-43fe-bc56-d9d4765b9bc6", "status": "ACTIVE", "creation_time": "2026-02-06T07:42:07.681370Z", "last_updated_time": "2026-02-06T07:46:12.648445Z", "url": "https://connect.maton.ai/?session_token=...", "app": "zoho-people", "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 People 连接，请使用 `Maton-Connection` 头指定要使用的连接：
```bash python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://gateway.maton.ai/zoho-people/people/api/forms') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_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 <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://gateway.maton.ai/zoho-people/people/api/forms') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_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, "view_Name": "P_EmployeeView" } } ], "message": "Data fetched successfully", "status": 0 } } ```
### 员工操作
#### 列出员工（批量记录）
```bash GET /zoho-people/people/api/forms/employee/getRecords?sIndex={startIndex}&limit={limit} ```
**查询参数：**
| 参数 | 类型 | 默认值 | 描述 | |-----------|------|---------|-------------| | `sIndex` | integer | 1 | 起始索引（从 1 开始） | | `limit` | integer | 200 | 记录数量（最大 200） | | `SearchColumn` | string | - | `EMPLOYEEID` 或 `EMPLOYEEMAILALIAS` | | `SearchValue` | string | - | 要搜索的值 | | `modifiedtime` | long | - | 修改记录的时间戳（毫秒） |
**示例：**
```bash python <<'EOF' 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.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ```
**响应：** ```json { "response": { "result": [ { "943596000000294355": [ { "FirstName": "Christopher", "LastName": "Brown", "EmailID": "[email protected]", "EmployeeID": "S20", "Department": "Management", "Designation": "Administration", "Employeestatus": "Active", "Gender": "Male", "Date_of_birth": "02-Feb-1987", "Zoho_ID": 943596000000294355 } ] } ], "message": "Data fetched successfully", "status": 0 } } ```
#### 列出员工（基于视图）
```bash GET /zoho-people/api/forms/{viewName}/records?rec_limit={limit} ```
**示例：**
```bash python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://gateway.maton.ai/zoho-people/api/forms/P_EmployeeView/records?rec_limit=10') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_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={employeeId} ```
**示例：**
```bash python <<'EOF' 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.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-people/people/api/forms/employee/getRecords?SearchColumn=EMPLOYEEMAILALIAS&SearchValue={email} ```
### 部门操作
#### 列出部门
```bash GET /zoho-people/people/api/forms/department/getRecords?sIndex={startIndex}&limit={limit} ```
**示例：**
```bash python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://gateway.maton.ai/zoho-people/people/api/forms/department/getRecords?sIndex=1&limit=50') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ```
**响应：** ```json { "response": { "result": [ { "943596000000294315": [ { "Department": "IT", "Department_Lead": "", "Parent_Department": "", "Zoho_ID": 943596000000294315 } ] } ], "message": "Data fetched successfully", "status": 0 } } ```
### 职位操作
#### 列出职位
```bash GET /zoho-people/people/api/forms/designation/getRecords?sIndex={startIndex}&limit={limit} ```
**示例：**
```bash python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://gateway.maton.ai/zoho-people/people/api/forms/designation/getRecords?sIndex=1&limit=50') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ```
**响应：** ```json { "response": { "result": [ { "943596000000294399": [ { "Designation": "Team Member", "EEO_Category": "Professionals", "Zoho_ID": 943596000000294399 } ] } ], "message": "Data fetched successfully", "status": 0 } } ```
### 插入记录
向任何表单添加新记录。
```bash POST /zoho-people/people/api/forms/json/{formLinkName}/insertRecord Content-Type: application/x-www-form-urlencoded
inputData={field1:'value1',field2:'value2'} ```
**示例 - 创建部门：**
```bash python <<'EOF' import urllib.request, os, json from urllib.parse import urlencode
inputData = json.dumps({"Department": "Engineering"}) data = urlencode({"inputData": inputData}).encode()
req = urllib.request.Request('https://gateway.maton.ai/zoho-people/people/api/forms/json/department/insertRecord', data=data, method='POST') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') req.add_header('Content-Type', 'application/x-www-form-urlencoded') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ```
**响应：** ```json { "response": { "result": { "pkId": "943596000000300001", "message": "Successfully Added" }, "message": "Data added successfully", "status": 0 } } ```
### 更新记录
修改现有记录。
```bash POST /zoho-people/people/api/forms/json/{formLinkName}/updateRecord Content-Type: application/x-www-form-urlencoded
inputData={field1:'newValue'}&recordId={recordId} ```
**示例 - 更新员工：**
```bash python <<'EOF' import urllib.request, os, json from urllib.parse import urlencode
inputData = json.dumps({"Department": "Engineering"}) data = urlencode({ "inputData": inputData, "recordId": "943596000000294355" }).encode()
req = urllib.request.Request('https://gateway.maton.ai/zoho-people/people/api/forms/json/employee/updateRecord', data=data, method='POST') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') req.add_header('Content-Type', 'application/x-www-form-urlencoded') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ```
### 请假操作
#### 列出请假记录
```bash GET /zoho-people/people/api/forms/leave/getRecords?sIndex={startIndex}&limit={limit} ```
#### 添加请假
```bash POST /zoho-people/people/api/forms/json/leave/insertRecord Content-Type: application/x-www-form-urlencoded
inputData={Employee_ID:'EMP001',Leavetype:'123456',From:'01-Feb-2026',To:'02-Feb-2026'} ```
### 考勤操作
注意：考勤端点需要额外的 OAuth 范围。
#### 获取考勤条目
```bash GET /zoho-people/people/api/attendance/getAttendanceEntries?date={date}&dateFormat={format} ```
**参数：**
| 参数 | 类型 | 描述 | |-----------|------|-------------| | `date` | string | 组织格式的日期 | | `dateFormat` | string | 日期格式（例如 `dd-MMM-yyyy`）| | `empId` | string | 员工 ID（可选）| | `emailId` | string | 员工邮箱（可选）|
#### 签到/签退
```bash POST /zoho-people/people/api/attendance Content-Type: application/x-www-form-urlencoded
dateFormat=dd/MM/yyyy HH:mm:ss&checkIn={datetime}&checkOut={datetime}&empId={empId} ```
## 常见表单链接名称
| 表单 | formLinkName | 描述 | |------|--------------|-------------| | 员工 | `employee` | 员工记录 | | 部门 | `department` | 部门 | | 职位 | `designation` | 职位名称 | | 请假 | `leave` | 请假请求 | | 客户 | `P_ClientDetails` | 客户信息 |
## 分页
Zoho People 使用基于索引的分页：
```bash GET /zoho-people/people/api/forms/{formLinkName}/getRecords?sIndex=1&limit=200 ```
- `sIndex`：起始索引（从 1 开始） - `limit`：每次请求的记录数量（最大 200）
对于后续页面： - 第 1 页：`sIndex=1&limit=200` - 第 2 页：`sIndex=201&limit=200` - 第 3 页：`sIndex=401&limit=200`
## 代码示例
### JavaScript
```javascript const response = await fetch( 'https://gateway.maton.ai/zoho-people/people/api/forms/employee/getRecords?sIndex=1&limit=10', { 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-people/people/api/forms/employee/getRecords', headers={'Authorization': f'Bearer {os.environ["MATON_API_KEY"]}'}, params={'sIndex': 1, 'limit': 10} ) data = response.json() ```
## 注意事项
- 记录 ID 是数字字符串（例如 `943596000000294355`） - 响应中的 `Zoho_ID` 字段包含记录 ID - 每个 GET 请求最多返回 200 条记录 - 插入/更新操作使用带有 `inputData` JSON 的 form-urlencoded 数据 - 日期格式因字段和组织设置而异 - 某些端点（考勤、请假）需要额外的 OAuth 范围。如果您收到 `INVALID_OAUTHSCOPE` 错误，请联系 Maton 支持 ([email protected])，并提供您需要的具体操作/API 以及您的使用场景 - 响应结构将数据封装在 `response.result[]` 数组中 - 重要：使用 curl 命令时，如果 URL 包含特殊字符，请使用 `curl -g` - 重要：当将 curl 输出通过管道传递给 `jq` 或其他命令时，像 `$MATON_API_KEY` 这样的环境变量在某些 shell 环境中可能无法正确扩展
## 错误处理
| 状态 | 含义 | |--------|---------| | 400 | 缺少 Zoho People 连接或请求无效 | | 401 | Maton API 密钥无效或缺失，或 OAuth 范围无效 | | 429 | 速率受限 | | 4xx/5xx | 来自 Zoho People API 的透传错误 |
### 常见错误代码
| 代码 | 描述 | |------|-------------| | 7011 | 表单名称无效 | | 7012 | 视图名称无效 | | 7021 | 超过最大记录限制（200）| | 7024 | 未找到记录 | | 7042 | 搜索值无效 | | 7218 | OAuth 范围无效 |
### 故障排除：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-people` 开头。例如：
- 正确：`https://gateway.maton.ai/zoho-people/people/api/forms` - 错误：`https://gateway.maton.ai/people/api/forms`
## 资源
- [Zoho People API 概览](https://www.zoho.com/people/api/overview.html) - [获取批量记录 API](https://www.zoho.com/people/api/bulk-records.html) - [获取表单 API](https://www.zoho.com/people/api/forms-api/fetch-forms.html) - [插入记录 API](https://www.zoho.com/people/api/insert-records.html) - [更新记录 API](https://www.zoho.com/people/api/update-records.html) - [考勤 API](https://www.zoho.com/people/api/attendance-entries.html) - [请假 API](https://www.zoho.com/people/api/add-leave.html) - [Maton 社区](https://discord.com/invite/dBfFAcefs2) - [Maton 支持](mailto:[email protected])