核心用法
Zoho People Skill 是 Maton 平台提供的托管 API 网关封装，旨在简化 Zoho People（企业人力资源管理 SaaS）的 REST API 调用。用户无需自行管理 OAuth 2.0 的 token 生命周期，仅需持有 Maton API Key 即可通过统一网关 (gateway.maton.ai/zoho-people) 完成 CRUD 操作。核心能力覆盖四大模块：
1. 员工数据管理：批量查询 (getRecords)、视图查询、按员工 ID 或邮箱搜索、更新员工字段（部门、职级等）。
2. 组织架构维护：部门 (department) 与职位 (designation) 的增删改查，支持层级结构。
3. 考勤与假期：打卡记录查询、手动签入签出、请假申请与审批（需额外 OAuth scope）。
4. 自定义表单：访问 Zoho People 中所有标准与自定义表单 (Forms)，通过 formLinkName 动态操作。
认证采用双 Token 架构：外层 Maton Bearer Token（用户持有）+ 内层 Zoho OAuth（平台托管）。连接管理通过独立控制面板 ctrl.maton.ai 完成，支持多连接切换（Maton-Connection 头指定）。
显著优点
- 零 OAuth 运维：Zoho 的 OAuth 授权、刷新、失效处理完全托管，降低集成门槛。
- 原生 API 透传：网关路径直接映射 Zoho 官方 API，保留完整语义（如
people/api/forms/employee/getRecords），无功能裁剪。 - 多租户隔离：通过
Maton-Connection头实现同一 API Key 下的多 Zoho 账户切换，适合代运营或集团场景。 - 标准化错误码：网关层统一封装 HTTP 状态与 Zoho 业务错误码（如 7218 INVALID_OAUTHSCOPE），便于程序化重试。
潜在缺点与局限性
- 供应商锁定风险：所有流量强制经过 Maton 网关，若服务中断或定价变更，迁移需重写 endpoint 与认证逻辑。
- OAuth Scope 隐性门槛：考勤、假期等敏感操作需额外申请 scope，首次调用失败需人工联系 support@maton.ai，自动化流水线可能阻塞。
- 分页硬限制：单次查询上限 200 条，大规模数据导出需客户端实现指数退避或并行分页，增加代码复杂度。
- 调试黑盒：OAuth token 不可导出，Zoho 原生诊断日志不可见，复杂权限问题依赖 Maton 支持工单。
适合人群
- 需快速集成 Zoho People 至内部 ERP/BI 系统的中小企业技术团队。
- 无专职运维、希望避免 OAuth 证书管理的早期创业公司。
- 代账或 HR SaaS 代理商，需统一管控多客户 Zoho 账户的 MSP。
常规风险
- 数据隐私：员工 PII（姓名、邮箱、生日）流经第三方网关，需确认 Maton 数据处理协议 (DPA) 符合 GDPR/个保法。
- 密钥泄漏：
MATON_API_KEY一旦泄露，攻击者可访问所有授权 Zoho 账户，建议配合最小权限连接与定期轮转。 - API 配额叠加：同时受 Maton 网关限流与 Zoho People 原生配额双重约束，高峰期需预压测。