介绍
# Zoho Inventory
通过托管的 OAuth 身份验证访问 Zoho Inventory API。通过完整的 CRUD 操作管理项目、销售订单、发票、采购订单、账单、联系人、发货订单和项目组。
## 快速开始
```bash # List items python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://gateway.maton.ai/zoho-inventory/inventory/v1/items') 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-inventory/inventory/v1/{endpoint} ```
网关将请求代理到 `www.zohoapis.com/inventory/v1` 并自动注入您的 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 Inventory OAuth 连接。
### 列出连接
```bash python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://ctrl.maton.ai/connections?app=zoho-inventory&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-inventory'}).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": "21fd90f9-5935-43cd-b6c8-bde9d915ca80", "status": "ACTIVE", "creation_time": "2025-12-08T07:20:53.488460Z", "last_updated_time": "2026-01-31T20:03:32.593153Z", "url": "https://connect.maton.ai/?session_token=...", "app": "zoho-inventory", "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 Inventory 连接，请使用 `Maton-Connection` 标头指定要使用的连接：
```bash python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://gateway.maton.ai/zoho-inventory/inventory/v1/items') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') req.add_header('Maton-Connection', '21fd90f9-5935-43cd-b6c8-bde9d915ca80') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ```
如果省略，网关将使用默认（最旧的）活动连接。
## API 参考
### 可用模块
| 模块 | 端点 | 描述 | |--------|----------|-------------| | Items | `/items` | 产品和服务 | | Item Groups | `/itemgroups` | 分组的产品变体 | | Contacts | `/contacts` | 客户和供应商 | | Sales Orders | `/salesorders` | 销售订单 | | Invoices | `/invoices` | 销售发票 | | Purchase Orders | `/purchaseorders` | 采购订单 | | Bills | `/bills` | 供应商账单 | | Shipment Orders | `/shipmentorders` | 发货跟踪 |
### Items
#### 列出项目
```bash GET /zoho-inventory/inventory/v1/items ```
**示例：**
```bash python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://gateway.maton.ai/zoho-inventory/inventory/v1/items') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ```
**响应：** ```json { "code": 0, "message": "success", "items": [ { "item_id": "1234567890000", "name": "Widget", "status": "active", "sku": "WDG-001", "rate": 25.00, "purchase_rate": 10.00, "is_taxable": true } ], "page_context": { "page": 1, "per_page": 200, "has_more_page": false } } ```
#### 获取项目
```bash GET /zoho-inventory/inventory/v1/items/{item_id} ```
#### 创建项目
```bash POST /zoho-inventory/inventory/v1/items Content-Type: application/json
{ "name": "Widget", "rate": 25.00, "purchase_rate": 10.00, "sku": "WDG-001", "item_type": "inventory", "product_type": "goods", "unit": "pcs", "is_taxable": true } ```
**必填字段：** - `name` - 项目名称
**可选字段：** - `rate` - 销售价格 - `purchase_rate` - 采购成本 - `sku` - 库存单位（唯一） - `item_type` - `inventory`、`sales`、`purchases` 或 `sales_and_purchases` - `product_type` - `goods` 或 `service` - `unit` - 计量单位 - `is_taxable` - 税收适用性 - `tax_id` - 税务标识符 - `description` - 项目描述 - `reorder_level` - 再订货点 - `vendor_id` - 首选供应商
**示例：**
```bash python <<'EOF' import urllib.request, os, json data = json.dumps({ "name": "Widget", "rate": 25.00, "purchase_rate": 10.00, "sku": "WDG-001", "item_type": "inventory", "product_type": "goods", "unit": "pcs" }).encode() req = urllib.request.Request('https://gateway.maton.ai/zoho-inventory/inventory/v1/items', 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 ```
**响应：** ```json { "code": 0, "message": "The item has been added.", "item": { "item_id": "1234567890000", "name": "Widget", "status": "active", "rate": 25.00, "purchase_rate": 10.00, "sku": "WDG-001" } } ```
#### 更新项目
```bash PUT /zoho-inventory/inventory/v1/items/{item_id} Content-Type: application/json
{ "name": "Updated Widget", "rate": 30.00 } ```
#### 删除项目
```bash DELETE /zoho-inventory/inventory/v1/items/{item_id} ```
#### 项目状态操作
```bash # Mark as active POST /zoho-inventory/inventory/v1/items/{item_id}/active
# Mark as inactive POST /zoho-inventory/inventory/v1/items/{item_id}/inactive ```
### Contacts
#### 列出联系人
```bash GET /zoho-inventory/inventory/v1/contacts ```
**查询参数：** - `filter_by` - `Status.All`、`Status.Active`、`Status.Inactive`、`Status.Duplicate`、`Status.Crm` - `search_text` - 跨联系人字段搜索 - `sort_column` - `contact_name`、`first_name`、`last_name`、`email`、`created_time`、`last_modified_time` - `contact_name`、`company_name`、`email`、`phone` - 特定字段过滤器
**示例：**
```bash python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://gateway.maton.ai/zoho-inventory/inventory/v1/contacts') 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-inventory/inventory/v1/contacts/{contact_id} ```
#### 创建联系人
```bash POST /zoho-inventory/inventory/v1/contacts Content-Type: application/json
{ "contact_name": "Acme Corporation", "contact_type": "customer", "company_name": "Acme Corp", "email": "[email protected]", "phone": "+1-555-1234" } ```
**必填字段：** - `contact_name` - 显示名称
**可选字段：** - `contact_type` - `customer` 或 `vendor` - `company_name` - 法人实体名称 - `email` - 电子邮件地址 - `phone` - 电话号码 - `billing_address` - 地址对象 - `shipping_address` - 地址对象 - `payment_terms` - 付款天数 - `currency_id` - 货币标识符 - `website` - 网站 URL
#### 更新联系人
```bash PUT /zoho-inventory/inventory/v1/contacts/{contact_id} ```
#### 删除联系人
```bash DELETE /zoho-inventory/inventory/v1/contacts/{contact_id} ```
#### 联系人状态操作
```bash # Mark as active POST /zoho-inventory/inventory/v1/contacts/{contact_id}/active
# Mark as inactive POST /zoho-inventory/inventory/v1/contacts/{contact_id}/inactive ```
### Sales Orders
#### 列出销售订单
```bash GET /zoho-inventory/inventory/v1/salesorders ```
**示例：**
```bash python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://gateway.maton.ai/zoho-inventory/inventory/v1/salesorders') 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-inventory/inventory/v1/salesorders/{salesorder_id} ```
#### 创建销售订单
```bash POST /zoho-inventory/inventory/v1/salesorders Content-Type: application/json
{ "customer_id": "1234567890000", "date": "2026-02-06", "line_items": [ { "item_id": "1234567890001", "quantity": 5, "rate": 25.00 } ] } ```
**必填字段：** - `customer_id` - 客户标识符 - `line_items` - 包含 `item_id`、`quantity`、`rate` 的项目数组
**可选字段：** - `salesorder_number` - 如果未指定则自动生成（如果启用了自动生成，请勿指定） - `date` - 订单日期 (yyyy-mm-dd) - `shipment_date` - 预计发货日期 - `reference_number` - 外部参考 - `notes` - 内部备注 - `terms` - 条款和条件 - `discount` - 折扣百分比或金额 - `shipping_charge` - 运费 - `adjustment` - 价格调整
#### 更新销售订单
```bash PUT /zoho-inventory/inventory/v1/salesorders/{salesorder_id} ```
#### 删除销售订单
```bash DELETE /zoho-inventory/inventory/v1/salesorders/{salesorder_id} ```
#### 销售订单状态操作
```bash # Mark as confirmed POST /zoho-inventory/inventory/v1/salesorders/{salesorder_id}/status/confirmed
# Mark as void POST /zoho-inventory/inventory/v1/salesorders/{salesorder_id}/status/void ```
### Invoices
#### 列出发票
```bash GET /zoho-inventory/inventory/v1/invoices ```
**示例：**
```bash python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://gateway.maton.ai/zoho-inventory/inventory/v1/invoices') 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-inventory/inventory/v1/invoices/{invoice_id} ```
#### 创建发票
```bash POST /zoho-inventory/inventory/v1/invoices Content-Type: application/json
{ "customer_id": "1234567890000", "line_items": [ { "item_id": "1234567890001", "quantity": 5, "rate": 25.00 } ] } ```
**必填字段：** - `customer_id` - 客户标识符 - `line_items` - 项目数组
**可选字段：** - `invoice_number` - 如果未指定则自动生成 - `date` - 发票日期 (yyyy-mm-dd) - `due_date` - 付款到期日 - `payment_terms` - 到期天数 - `discount` - 折扣百分比或金额 - `shipping_charge` - 运费 - `notes` - 内部备注 - `terms` - 条款和条件
#### 更新发票
```bash PUT /zoho-inventory/inventory/v1/invoices/{invoice_id} ```
#### 删除发票
```bash DELETE /zoho-inventory/inventory/v1/invoices/{invoice_id} ```
#### 发票状态操作
```bash # Mark as sent POST /zoho-inventory/inventory/v1/invoices/{invoice_id}/status/sent
# Mark as draft POST /zoho-inventory/inventory/v1/invoices/{invoice_id}/status/draft
# Void invoice POST /zoho-inventory/inventory/v1/invoices/{invoice_id}/status/void ```
#### 发票邮件
```bash # Email invoice to customer POST /zoho-inventory/inventory/v1/invoices/{invoice_id}/email
# Get email content template GET /zoho-inventory/inventory/v1/invoices/{invoice_id}/email ```
#### 发票付款
```bash # List payments applied GET /zoho-inventory/inventory/v1/invoices/{invoice_id}/payments
# Delete a payment DELETE /zoho-inventory/inventory/v1/invoices/{invoice_id}/payments/{invoice_payment_id} ```
#### 发票贷项
```bash # List credits applied GET /zoho-inventory/inventory/v1/invoices/{invoice_id}/creditsapplied
# Apply credits POST /zoho-inventory/inventory/v1/invoices/{invoice_id}/credits
# Delete applied credit DELETE /zoho-inventory/inventory/v1/invoices/{invoice_id}/creditsapplied/{creditnotes_invoice_id} ```
#### 发票评论
```bash # List comments GET /zoho-inventory/inventory/v1/invoices/{invoice_id}/comments
# Add comment POST /zoho-inventory/inventory/v1/invoices/{invoice_id}/comments
# Update comment PUT /zoho-inventory/inventory/v1/invoices/{invoice_id}/comments/{comment_id}
# Delete comment DELETE /zoho-inventory/inventory/v1/invoices/{invoice_id}/comments/{comment_id} ```
### Purchase Orders
#### 列出采购订单
```bash GET /zoho-inventory/inventory/v1/purchaseorders ```
**示例：**
```bash python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://gateway.maton.ai/zoho-inventory/inventory/v1/purchaseorders') 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-inventory/inventory/v1/purchaseorders/{purchaseorder_id} ```
#### 创建采购订单
```bash POST /zoho-inventory/inventory/v1/purchaseorders Content-Type: application/json
{ "vendor_id": "1234567890000", "line_items": [ { "item_id": "1234567890001", "quantity": 100, "rate": 10.00 } ] } ```
**必填字段：** - `vendor_id` - 供应商标识符 - `line_items` - 项目数组
**可选字段：** - `purchaseorder_number` - 如果未指定则自动生成（如果启用了自动生成，请勿指定） - `date` - 订单日期 (yyyy-mm-dd) - `delivery_date` - 预计交货日期 - `reference_number` - 外部参考 - `ship_via` - 运输方式 - `notes` - 内部备注 - `terms` - 条款和条件
#### 更新采购订单
```bash PUT /zoho-inventory/inventory/v1/purchaseorders/{purchaseorder_id} ```
#### 删除采购订单
```bash DELETE /zoho-inventory/inventory/v1/purchaseorders/{purchaseorder_id} ```
#### 采购订单状态操作
```bash # Mark as issued POST /zoho-inventory/inventory/v1/purchaseorders/{purchaseorder_id}/status/issued
# Mark as cancelled POST /zoho-inventory/inventory/v1/purchaseorders/{purchaseorder_id}/status/cancelled ```
### Bills
#### 列出账单
```bash GET /zoho-inventory/inventory/v1/bills ```
**示例：**
```bash python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://gateway.maton.ai/zoho-inventory/inventory/v1/bills') 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-inventory/inventory/v1/bills/{bill_id} ```
#### 创建账单
```bash POST /zoho-inventory/inventory/v1/bills Content-Type: application/json
{ "vendor_id": "1234567890000", "bill_number": "BILL-001", "date": "2026-02-06", "due_date": "2026-03-06", "line_items": [ { "item_id": "1234567890001", "quantity": 100, "rate": 10.00 } ] } ```
**必填字段：** - `vendor_id` - 供应商标识符 - `bill_number` - 唯一账单编号（必填，非自动生成） - `date` - 账单日期 (yyyy-mm-dd) - `due_date` - 付款到期日 - `line_items` - 项目数组
**可选字段：** - `reference_number` - 外部参考 - `notes` - 内部备注 - `terms` - 条款和条件 - `currency_id` - 货币标识符 - `exchange_rate` - 外币汇率
#### 更新账单
```bash PUT /zoho-inventory/inventory/v1/bills/{bill_id} ```
#### 删除账单
```bash DELETE /zoho-inventory/inventory/v1/bills/{bill_id} ```
#### 账单状态操作
```bash # Mark as open POST /zoho-inventory/inventory/v1/bills/{bill_id}/status/open
# Mark as void POST /zoho-inventory/inventory/v1/bills/{bill_id}/status/void ```
### Shipment Orders
#### 创建发货订单
```bash POST /zoho-inventory/inventory/v1/shipmentorders Content-Type: application/json
{ "shipment_number": "SHP-001", "date": "2026-02-06", "delivery_method": "FedEx", "tracking_number": "1234567890" } ```
**必填字段：** - `shipment_number` - 唯一发货编号 - `date` - 发货日期 - `delivery_method` - 承运商/交货方式
**可选字段：** - `tracking_number` - 承运商跟踪号 - `shipping_charge` - 运费 - `notes` - 内部备注 - `reference_number` - 外部参考
#### 获取发货订单
```bash GET /zoho-inventory/inventory/v1/shipmentorders/{shipmentorder_id} ```
#### 更新发货订单
```bash PUT /zoho-inventory/inventory/v1/shipmentorders/{shipmentorder_id} ```
#### 删除发货订单
```bash DELETE /zoho-inventory/inventory/v1/shipmentorders/{shipmentorder_id} ```
#### 标记为已送达
```bash POST /zoho-inventory/inventory/v1/shipmentorders/{shipmentorder_id}/status/delivered ```
### Item Groups
#### 列出项目组
```bash GET /zoho-inventory/inventory/v1/itemgroups ```
#### 获取项目组
```bash GET /zoho-inventory/inventory/v1/itemgroups/{itemgroup_id} ```
#### 创建项目组
```bash POST /zoho-inventory/inventory/v1/itemgroups Content-Type: application/json
{ "group_name": "T-Shirts", "unit": "pcs", "items": [ { "name": "T-Shirt - Small", "rate": 20.00, "purchase_rate": 8.00, "sku": "TS-S" }, { "name": "T-Shirt - Medium", "rate": 20.00, "purchase_rate": 8.00, "sku": "TS-M" } ] } ```
**必填字段：** - `group_name` - 组名称 - `unit` - 计量单位
#### 更新项目组
```bash PUT /zoho-inventory/inventory/v1/itemgroups/{itemgroup_id} ```
#### 删除项目组
```bash DELETE /zoho-inventory/inventory/v1/itemgroups/{itemgroup_id} ```
#### 项目组状态操作
```bash # Mark as active POST /zoho-inventory/inventory/v1/itemgroups/{itemgroup_id}/active
# Mark as inactive POST /zoho-inventory/inventory/v1/itemgroups/{itemgroup_id}/inactive ```
## 分页
Zoho Inventory 使用基于页面的分页：
```bash GET /zoho-inventory/inventory/v1/items?page=1&per_page=50 ```
响应在 `page_context` 中包含分页信息：
```json { "code": 0, "message": "success", "items": [...], "page_context": { "page": 1, "per_page": 50, "has_more_page": true, "sort_column": "name", "sort_order": "A" } } ```
当 `has_more_page` 为 `true` 时继续获取，每次增加 `page`。
## 代码示例
### JavaScript
```javascript const response = await fetch( 'https://gateway.maton.ai/zoho-inventory/inventory/v1/items', { 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-inventory/inventory/v1/items', headers={'Authorization': f'Bearer {os.environ["MATON_API_KEY"]}'} ) data = response.json() ```
## 备注
- 所有成功的响应都有 `code: 0` 和一个 `message` 字段 - 日期应采用 `yyyy-mm-dd` 格式 - 联系人类型为 `customer` 或 `vendor` - 项目类型：`inventory`、`sales`、`purchases`、`sales_and_purchases` - 产品类型：`goods` 或 `service` - `organization_id` 参数由网关自动处理 - 您无需指定它 - 销售订单和采购订单编号默认为自动生成 - 除非在设置中禁用了自动生成，否则请勿指定 `salesorder_number` 或 `purchaseorder_number` - 状态操作端点使用 POST 方法（例如 `/status/confirmed`、`/status/void`） - 速率限制：每个组织 100 次请求/分钟 - 每日限制因计划而异：免费版 (1,000)、标准版 (2,500)、专业版 (5,000)、高级版 (7,500)、企业版 (10,000) - 重要提示：使用 curl 命令时，如果 URL 包含括号，请使用 `curl -g` 以禁用 glob 解析 - 重要提示：将 curl 输出通过管道传递到 `jq` 或其他命令时，在某些 shell 环境中，像 `$MATON_API_KEY` 这样的环境变量可能无法正确扩展
## 错误处理
| 状态 | 含义 | |--------|---------| | 400 | 缺少 Zoho Inventory 连接或请求无效 | | 401 | Maton API 密钥无效或缺失，或 OAuth 范围不匹配 | | 404 | 资源未找到 | | 429 | 速率受限 | | 4xx/5xx | 来自 Zoho Inventory API 的透传错误 |
### 常见错误代码
| 代码 | 描述 | |------|-------------| | 0 | 成功 | | 1 | 无效值 | | 2 | 缺少必填字段 | | 3 | 资源不存在 | | 5 | 无效 URL |
### 故障排除：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-inventory` 开头。例如：
- 正确：`https://gateway.maton.ai/zoho-inventory/inventory/v1/items` - 错误：`https://gateway.maton.ai/inventory/v1/items`
## 资源
- [Zoho Inventory API v1 简介](https://www.zoho.com/inventory/api/v1/introduction/) - [Zoho Inventory 项目 API](https://www.zoho.com/inventory/api/v1/items/) - [Zoho Inventory 联系人 API](https://www.zoho.com/inventory/api/v1/contacts/) - [Zoho Inventory 销售订单 API](https://www.zoho.com/inventory/api/v1/salesorders/) - [Zoho Inventory 发票 API](https://www.zoho.com/inventory/api/v1/invoices/) - [Zoho Inventory 采购订单 API](https://www.zoho.com/inventory/api/v1/purchaseorders/) - [Zoho Inventory 账单 API](https://www.zoho.com/inventory/api/v1/bills/) - [Maton 社区](https://discord.com/invite/dBfFAcefs2) - [Maton 支持](mailto:[email protected])