Zoho Inventory

核心用法

该技能通过 Maton 网关代理访问 Zoho Inventory API，采用托管 OAuth 认证模式，用户仅需持有 Maton API Key 即可调用完整的库存管理功能。核心操作涵盖八大模块：

• Items（商品）：SKU 管理、库存追踪、定价与分类
• Item Groups（商品组）：多规格变体批量管理
• Contacts（联系人）：客户与供应商档案维护
• Sales Orders（销售订单）：订单创建、确认、作废
• Invoices（发票）：开票、发送、收款追踪、贷项管理
• Purchase Orders（采购单）：向供应商下单、状态流转
• Bills（账单）：应付账款管理与付款追踪
• Shipment Orders（物流单）：发货追踪与交付标记

所有写操作（POST/PUT/DELETE）均需用户显式确认目标资源及操作意图，符合安全合规要求。

显著优点

1. 零 OAuth 配置负担：Maton 自动处理令牌刷新与密钥轮换，开发者无需维护 Zoho 应用凭证
2. 标准化 REST 接口：统一 Base URL，自动注入组织 ID，降低多租户适配成本
3. 多连接隔离支持：通过 Maton-Connection 头部实现多账号切换，适合代运营或集团架构
4. 完整状态机覆盖：订单、发票、账单均支持从草稿到终态的完整生命周期操作
5. 内置分页与限流提示：API 响应自带 page_context，文档明确标注各套餐日调用上限

潜在局限

• 网关依赖：所有请求须经 Maton 代理，若网关故障则服务中断
• 费率受限：免费版仅 1,000 次/日，高并发场景需升级 Zoho 套餐
• 字段约束严格：bill_number 等字段非自动生成，易因重复提交触发错误
• 地域合规待定：数据经 Maton 中转，敏感行业需确认数据 residency 条款

适合人群

• 中小电商/零售企业需快速集成库存系统
• SaaS 厂商为商户提供 Zoho Inventory 连接器
• 财务自动化工具开发者对接发票与采购流程
• 代运营服务商管理多客户 Zoho 账号

常规风险

| 风险类型 | 说明 | 缓解措施 |

|---------|------|---------|

| 误操作数据 | 批量更新或删除导致库存/财务数据错误 | 强制二次确认；生产环境先用只读权限测试 |

| 密钥泄露 | MATON_API_KEY 泄露导致未授权访问 | 使用环境变量或密钥管理服务；定期轮换 |

| 限流中断 | 峰值流量触发 429 错误 | 实施指数退避重试；监控日配额消耗 |

| OAuth 断连 | 用户撤销授权或令牌过期 | 建立连接健康检查与告警机制 |

核心用法

本 Skill 是 Zoho Inventory 的 API 集成代理，由 Maton 平台提供托管 OAuth 认证。用户无需处理复杂的 Zoho OAuth 流程，仅需配置 MATON_API_KEY 环境变量即可通过 https://api.maton.ai/zoho-inventory 代理端点调用完整的 Inventory API v1。

认证流程：
1. 在 Maton 平台获取 API Key 并设为环境变量
2. 创建 Zoho Inventory 连接（返回 OAuth 授权 URL）
3. 用户浏览器完成 Zoho 授权
4. 所有请求自动携带 OAuth Token 访问 Zoho Inventory

支持模块（完整 CRUD + 状态管理）：

• Items：商品/服务管理，支持库存追踪、SKU、税率、进销价
• Item Groups：多规格商品组（如尺码/颜色变体）
• Contacts：客户与供应商双角色管理
• Sales Orders：销售订单全生命周期（草稿→确认→作废）
• Invoices：发票管理，含邮件发送、收款、贷项应用、备注
• Purchase Orders：采购订单流程（草稿→已发出→取消）
• Bills：供应商账单，强制 bill_number，支持外币
• Shipment Orders：物流跟踪，对接承运商单号

关键特性：

• 自动分页处理（page_context.has_more_page）
• 多连接支持（Maton-Connection 头区分账户）
• 速率限制透明（100/min，日限额按 Zoho 套餐）
• 写入操作需用户显式确认（安全设计）

显著优点

| 维度 | 优势 |

|------|------|

| **OAuth 托管** | 免除 Zoho OAuth 2.0 的 token 刷新、scope 管理、重定向配置等复杂度 |

| **统一入口** | Maton 代理层自动处理 `organization_id`，多租户场景简化 |

| **安全设计** | 写入操作强制用户确认；纯代理模式，Maton 不持久化业务数据 |

| **文档完整** | 覆盖 8 大模块的字段级说明、必填/选填、状态流转、示例代码（Python/JS/curl） |

| **生态可信** | Zoho 为美股上市公司，Maton 为 T2 可信组织，API 调用全 HTTPS |

潜在局限

1. 网络依赖：必须能访问 api.maton.ai，无法离线或内网部署
2. 功能边界：仅为 Zoho Inventory API 代理，不支持 Zoho Books/Zoho CRM 原生功能（需通过 api-gateway skill 切换）
3. 速率天花板：受限于 Zoho Inventory 自身配额（Free 版 1,000/日），大吞吐量场景需升级 Zoho 套餐
4. 账单编号限制：bill_number 非自动生成，需调用方确保唯一性，易因冲突报错
5. OAuth 锁定：授权绑定 Maton 平台，迁移至其他代理需重新授权

适合人群

• 中小企业：使用 Zoho Inventory 管理进销存，需自动化数据同步
• 电商运营：对接自建商城/ERP，实现订单→库存→物流→财务的闭环
• 开发者：快速构建 Inventory 集成，无需深入研究 Zoho OAuth 细节
• 多账户管理方：通过 Maton-Connection 头轻松切换多个 Zoho 组织

不适合：需要完全离线部署、或对数据流经第三方代理有合规顾虑的场景。

常规风险

| 风险项 | 等级 | 说明 |

|--------|------|------|

| API Key 泄露 | **中** | `MATON_API_KEY` 泄露可导致 Zoho 数据被访问；务必环境变量管理，禁硬编码 |

| OAuth 授权范围 | **低** | Maton 请求的 scope 由平台控制，用户授权时可见，无过度授权风险 |

| 数据隐私 | **低** | 业务数据经 Maton 代理转发，Maton 声称不持久化；敏感行业建议评估 DPA |

| 服务可用性 | **低** | Maton/Zoho 双依赖，任一服务故障将中断；需设计重试与降级策略 |

| 误操作覆盖 | **中** | Update/Delete 无二次确认机制（除 Skill 层面的用户确认提示），生产环境建议测试库先行 |