Zoho People

2026-03-25 新闻来源：网淘吧围观:46

电脑广告

手机广告

Zoho People

通过托管的OAuth认证访问Zoho People API。管理员工、部门、职位、考勤、请假以及自定义人力资源表单，支持完整的增删改查操作。

快速开始

# 列出所有员工
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:

export MATON_API_KEY="YOUR_API_KEY"

获取您的 API 密钥

登录或在以下网址创建账户maton.ai
前往maton.ai/settings
复制您的 API 密钥

连接管理

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

列出连接

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

创建连接

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

获取连接

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

{ "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 授权。删除连接

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请求头指定要使用的连接：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 账户中所有可用表单的列表。

GET /zoho-people/people/api/forms

GET /zoho-people/people/api/forms

示例：

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

响应：

{
  "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": "数据获取成功",
    "status": 0
  }
}

员工操作

列出员工（批量记录）

GET /zoho-people/people/api/forms/employee/getRecords?sIndex={startIndex}&limit={limit}

查询参数：

参数	类型	默认值	描述
`sIndex`	整数	1	起始索引（从1开始）
`limit`	整数	200	记录数量（最大200）
`搜索列`	字符串	-	`员工ID`或`员工邮件别名`
`搜索值`	字符串	-	要搜索的值
`修改时间`	长整型	-	修改记录的时间戳（毫秒）

示例：

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

响应：

{
  "response": {
    "result": [
      {
        "943596000000294355": [
          {
            "FirstName": "克里斯托弗",
            "LastName": "布朗",
            "EmailID": "christopherbrown@zylker.com",
            "EmployeeID": "S20",
            "Department": "管理部",
            "Designation": "行政管理",
            "Employeestatus": "在职",
            "Gender": "男",
            "Date_of_birth": "1987年2月2日",
            "Zoho_ID": 943596000000294355
          }
        ]
      }
    ],
    "message": "数据获取成功",
    "status": 0
  }
}

列出员工（基于视图）

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

示例：

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搜索员工

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

示例：

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

按邮箱搜索员工

GET /zoho-people/people/api/forms/employee/getRecords?SearchColumn=EMPLOYEEMAILALIAS&SearchValue={邮箱}

部门操作

列出部门

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

示例：

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

响应：

{
  "response": {
    "result": [
      {
        "943596000000294315": [
          {
            "Department": "IT",
            "Department_Lead": "",
            "Parent_Department": "",
            "Zoho_ID": 943596000000294315
          }
        ]
      }
    ],
    "message": "数据获取成功",
    "status": 0
  }
}

职位操作

列出职位

GET /zoho-people/people/api/forms/designation/getRecords?sIndex={startIndex}&limit={limit}

示例：

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

响应：

{
  "response": {
    "result": [
      {
        "943596000000294399": [
          {
            "Designation": "团队成员",
            "EEO_Category": "专业人员",
            "Zoho_ID": 943596000000294399
          }
        ]
      }
    ],
    "message": "数据获取成功",
    "status": 0
  }
}

插入记录

向任何表单添加新记录。

POST /zoho-people/people/api/forms/json/{formLinkName}/insertRecord
Content-Type: application/x-www-form-urlencoded

inputData={field1:'value1',field2:'value2'}

示例 - 创建部门：

python <<'EOF'
import urllib.request, os, json
from urllib.parse import urlencode

inputData = json.dumps({"Department": "工程部"})
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

响应：

{
  "response": {
    "result": {
      "pkId": "943596000000300001",
      "message": "添加成功"
    },
    "message": "数据添加成功",
    "status": 0
  }
}

更新记录

修改现有记录。

POST /zoho-people/people/api/forms/json/{formLinkName}/updateRecord
Content-Type: application/x-www-form-urlencoded

inputData={field1:'newValue'}&recordId={recordId}

示例 - 更新员工：

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

休假操作

列出休假记录

GET /zoho-people/people/api/forms/leave/getRecords?sIndex={startIndex}&limit={limit}

添加休假

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权限范围。

获取考勤记录

GET /zoho-people/people/api/attendance/getAttendanceEntries?date={date}&dateFormat={format}

参数：

参数	类型	描述
`date`	字符串	使用组织格式的日期
`日期格式`	字符串	日期格式（例如：`日-月-年`）
`员工编号`	字符串	员工编号（可选）
`邮箱地址`	字符串	员工邮箱（可选）

签到/签退

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}

常用表单链接名称

表单	表单链接名称	描述
员工	`employee`	员工记录
部门	`department`	部门信息
职位	`designation`	职位名称
请假	`leave`	请假申请
客户	`P_ClientDetails`	客户信息

分页

Zoho People 使用基于索引的分页：

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

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

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 条记录
插入/更新操作使用表单编码数据，并带有inputDataJSON
日期格式因字段和组织设置而异
某些端点（考勤、请假）需要额外的 OAuth 范围。如果您收到INVALID_OAUTHSCOPE错误，请通过以下方式联系Maton技术支持support@maton.ai并提供您需要的具体操作/API以及您的使用场景
响应结构会将数据包装在response.result[]数组中
重要提示：使用curl命令时，如果URL包含特殊字符，请使用curl -g 重要提示：当将curl输出通过管道传递给
jq或其他命令时，某些shell环境中可能无法正确展开诸如$MATON_API_KEY之类的环境变量错误处理

状态码

含义	400
缺少Zoho People连接或请求无效	401
Maton API密钥无效或缺失，或OAuth范围无效	429
请求频率受限	4xx/5xx
来自Zoho People API的透传错误	常见错误代码

代码

描述	7011
无效的表单名称	7012
无效的视图名称	Invalid view name
7021	超出最大记录限制 (200)
7024	未找到记录
7042	搜索值无效
7218	OAuth 范围无效

故障排除：API 密钥问题

检查是否已设置MATON_API_KEY环境变量：

echo $MATON_API_KEY

通过列出连接来验证 API 密钥是否有效：

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

故障排除：应用程序名称无效

请确保您的 URL 路径以zoho-people开头。例如：

正确：https://gateway.maton.ai/zoho-people/people/api/forms
错误：https://gateway.maton.ai/people/api/forms

资源

免责申明

部分文章来自各大搜索引擎，如有侵权，请与我联系删除。

打赏

文章底部电脑广告

手机广告位-内容正文底部

标签

上一篇：Intelligent Stocks Screener 下一篇：Frontend Design Ultimate

Zoho People

Zoho People

快速开始

基础URL

认证

获取您的 API 密钥

连接管理

列出连接

创建连接

获取连接

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 连接，请使用

表单操作

列出所有表单

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

员工操作

列出员工（批量记录）

列出员工（基于视图）

按ID搜索员工

按邮箱搜索员工

部门操作

列出部门

职位操作

列出职位

插入记录

更新记录

休假操作

列出休假记录

添加休假

考勤操作

获取考勤记录

签到/签退

常用表单链接名称

分页

代码示例

JavaScript

Python

注意事项

状态码

代码

故障排除：API 密钥问题

故障排除：应用程序名称无效

资源

相关文章

推荐文章

热门浏览

标签列表