Zoho Inventory

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

电脑广告

手机广告

Zoho Inventory

通过托管的 OAuth 认证访问 Zoho Inventory API。对商品、销售订单、发票、采购订单、账单、联系人、发货订单和商品组进行完整的增删改查操作。

快速开始

# 列出商品
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：

export MATON_API_KEY="YOUR_API_KEY"

获取您的 API 密钥

登录或在maton.ai
创建账户前往
maton.ai/settings

复制您的 API 密钥

在https://ctrl.maton.ai管理您的 Zoho Inventory OAuth 连接。

列出连接

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

创建连接

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

获取连接

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": "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 授权。

删除连接

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请求头来指定要使用哪一个：

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`	产品与服务
商品分组	`/itemgroups`	分组产品变体
联系人	`/contacts`	客户与供应商
销售订单	`/salesorders`	销售订单
发票	`/invoices`	销售发票
采购订单	`/purchaseorders`	采购订单
账单	`/bills`	供应商账单
发货订单	`/shipmentorders`	货物追踪

商品

列出商品

GET /zoho-inventory/inventory/v1/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

响应：

{
  "code": 0,
  "message": "success",
  "items": [
    {
      "item_id": "1234567890000",
      "name": "小部件",
      "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
  }
}

获取商品

GET /zoho-inventory/inventory/v1/items/{item_id}

创建商品

POST /zoho-inventory/inventory/v1/items
Content-Type: application/json

{
  "name": "小部件",
  "rate": 25.00,
  "purchase_rate": 10.00,
  "sku": "WDG-001",
  "item_type": "inventory",
  "product_type": "goods",
  "unit": "pcs",
  "is_taxable": true
}

必填字段：

名称- 商品名称

可选字段：

价格- 销售价格
采购价格- 采购成本
SKU- 库存单位（唯一）
物品类型-库存,销售,采购, 或销售与采购
产品类型-商品或服务
单位- 计量单位
是否应税- 税收适用性
税号- 税务标识符
描述- 物品描述
再订货点- 补货临界点
供应商ID- 首选供应商

示例：

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

响应：

{
  "code": 0,
  "message": "商品已添加。",
  "item": {
    "item_id": "1234567890000",
    "name": "Widget",
    "status": "active",
    "rate": 25.00,
    "purchase_rate": 10.00,
    "sku": "WDG-001"
  }
}

更新商品

PUT /zoho-inventory/inventory/v1/items/{item_id}
Content-Type: application/json

{
  "name": "Updated Widget",
  "rate": 30.00
}

删除商品

DELETE /zoho-inventory/inventory/v1/items/{item_id}

商品状态操作

# 标记为活跃
POST /zoho-inventory/inventory/v1/items/{item_id}/active

# 标记为不活跃
POST /zoho-inventory/inventory/v1/items/{item_id}/inactive

联系人

列出联系人

GET /zoho-inventory/inventory/v1/contacts

查询参数：

filter_by-Status.All,Status.Active,Status.Inactive,状态.重复,状态.客户关系管理
搜索文本- 在联系人字段中搜索
排序列-联系人姓名,名字,姓氏,电子邮件,创建时间,最后修改时间
联系人姓名,公司名称,电子邮件,电话- 字段特定筛选器

示例：

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

获取联系人

GET /zoho-inventory/inventory/v1/contacts/{contact_id}

创建联系人

POST /zoho-inventory/inventory/v1/contacts
Content-Type: application/json

{
  "contact_name": "Acme Corporation",
  "contact_type": "customer",
  "company_name": "Acme Corp",
  "email": "billing@acme.com",
  "phone": "+1-555-1234"
}

必填字段：

contact_name- 显示名称

可选字段：

contact_type-customer或vendor
company_name- 法人实体名称
email- 电子邮件地址
phone- 电话号码
billing_address- 地址对象
shipping_address- 地址对象
payment_terms- 付款天数
currency_id- 货币标识符
website- 网站URL

更新联系人

PUT /zoho-inventory/inventory/v1/contacts/{contact_id}

删除联系人

DELETE /zoho-inventory/inventory/v1/contacts/{contact_id}

联系人状态操作

# 标记为活跃
POST /zoho-inventory/inventory/v1/contacts/{contact_id}/active

# 标记为不活跃
POST /zoho-inventory/inventory/v1/contacts/{contact_id}/inactive

销售订单

列出销售订单

GET /zoho-inventory/inventory/v1/salesorders

示例：

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

获取销售订单

GET /zoho-inventory/inventory/v1/salesorders/{salesorder_id}

创建销售订单

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- 条款与条件
折扣- 折扣百分比或金额
运费- 运输成本
调整- 价格调整

更新销售订单

PUT /zoho-inventory/inventory/v1/salesorders/{salesorder_id}

删除销售订单

DELETE /zoho-inventory/inventory/v1/salesorders/{salesorder_id}

销售订单状态操作

# 标记为已确认
POST /zoho-inventory/inventory/v1/salesorders/{salesorder_id}/status/confirmed

# 标记为作废
POST /zoho-inventory/inventory/v1/salesorders/{salesorder_id}/status/void

发票

列出发票

GET /zoho-inventory/inventory/v1/invoices

示例：

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

获取发票

GET /zoho-inventory/inventory/v1/invoices/{invoice_id}

创建发票

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- 发票日期（年-月-日）
due_date- 付款截止日期
payment_terms- 到期天数
discount- 折扣百分比或金额
shipping_charge- 运费
notes- 内部备注
terms- 条款与条件

更新发票

PUT /zoho-inventory/inventory/v1/invoices/{invoice_id}

删除发票

DELETE /zoho-inventory/inventory/v1/invoices/{invoice_id}

发票状态操作

# 标记为已发送
POST /zoho-inventory/inventory/v1/invoices/{invoice_id}/status/sent

# 标记为草稿
POST /zoho-inventory/inventory/v1/invoices/{invoice_id}/status/draft

# 作废发票
POST /zoho-inventory/inventory/v1/invoices/{invoice_id}/status/void

发票邮件

# 向客户发送发票邮件
POST /zoho-inventory/inventory/v1/invoices/{invoice_id}/email

# 获取邮件内容模板
GET /zoho-inventory/inventory/v1/invoices/{invoice_id}/email

发票付款

# 列出已应用的付款
GET /zoho-inventory/inventory/v1/invoices/{invoice_id}/payments

# 删除付款
DELETE /zoho-inventory/inventory/v1/invoices/{invoice_id}/payments/{invoice_payment_id}

发票信用额度

# 列出已应用的信用额度
GET /zoho-inventory/inventory/v1/invoices/{invoice_id}/creditsapplied

# 应用信用额度
POST /zoho-inventory/inventory/v1/invoices/{invoice_id}/credits

# 删除已应用的信用额度
DELETE /zoho-inventory/inventory/v1/invoices/{invoice_id}/creditsapplied/{creditnotes_invoice_id}

发票评论

# 列出评论
GET /zoho-inventory/inventory/v1/invoices/{invoice_id}/comments

# 添加评论
POST /zoho-inventory/inventory/v1/invoices/{invoice_id}/comments

# 更新评论
PUT /zoho-inventory/inventory/v1/invoices/{invoice_id}/comments/{comment_id}

# 删除评论
DELETE /zoho-inventory/inventory/v1/invoices/{invoice_id}/comments/{comment_id}

采购订单

列出采购订单

GET /zoho-inventory/inventory/v1/purchaseorders

示例：

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

获取采购订单

GET /zoho-inventory/inventory/v1/purchaseorders/{purchaseorder_id}

创建采购订单

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- 条款与条件

更新采购订单

PUT /zoho-inventory/inventory/v1/purchaseorders/{purchaseorder_id}

删除采购订单

DELETE /zoho-inventory/inventory/v1/purchaseorders/{purchaseorder_id}

采购订单状态操作

# 标记为已签发
POST /zoho-inventory/inventory/v1/purchaseorders/{purchaseorder_id}/status/issued

# 标记为已取消
POST /zoho-inventory/inventory/v1/purchaseorders/{purchaseorder_id}/status/cancelled

账单

列出账单

GET /zoho-inventory/inventory/v1/bills

示例：

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

获取账单

GET /zoho-inventory/inventory/v1/bills/{bill_id}

创建账单

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- 内部备注
条款- 条款与条件
货币标识- 货币标识符
汇率- 外币汇率

更新账单

PUT /zoho-inventory/inventory/v1/bills/{bill_id}

删除账单

DELETE /zoho-inventory/inventory/v1/bills/{bill_id}

账单状态操作

# 标记为未结
POST /zoho-inventory/inventory/v1/bills/{bill_id}/status/open

# 标记为作废
POST /zoho-inventory/inventory/v1/bills/{bill_id}/status/void

发货单

创建发货单

POST /zoho-inventory/inventory/v1/shipmentorders
Content-Type: application/json

{
  "shipment_number": "SHP-001",
  "date": "2026-02-06",
  "delivery_method": "FedEx",
  "tracking_number": "1234567890"
}

必填字段：

发货单号- 唯一的发货单号
日期- 发货日期
配送方式- 承运商/配送方式

可选字段：

追踪号码- 承运商追踪号码
运费- 运输成本
备注- 内部备注
参考编号- 外部参考

获取发货订单

GET /zoho-inventory/inventory/v1/shipmentorders/{shipmentorder_id}

更新发货订单

PUT /zoho-inventory/inventory/v1/shipmentorders/{shipmentorder_id}

删除发货订单

DELETE /zoho-inventory/inventory/v1/shipmentorders/{shipmentorder_id}

标记为已送达

POST /zoho-inventory/inventory/v1/shipmentorders/{shipmentorder_id}/status/delivered

物品组

列出物品组

GET /zoho-inventory/inventory/v1/itemgroups

获取物料组

GET /zoho-inventory/inventory/v1/itemgroups/{itemgroup_id}

创建物料组

POST /zoho-inventory/inventory/v1/itemgroups
Content-Type: application/json

{
  "group_name": "T恤衫",
  "unit": "件",
  "items": [
    {
      "name": "T恤衫 - 小号",
      "rate": 20.00,
      "purchase_rate": 8.00,
      "sku": "TS-S"
    },
    {
      "name": "T恤衫 - 中号",
      "rate": 20.00,
      "purchase_rate": 8.00,
      "sku": "TS-M"
    }
  ]
}

必填字段：

group_name- 组名称
unit- 计量单位

更新物料组

PUT /zoho-inventory/inventory/v1/itemgroups/{itemgroup_id}

删除物料组

DELETE /zoho-inventory/inventory/v1/itemgroups/{itemgroup_id}

物料组状态操作

# 标记为活跃
POST /zoho-inventory/inventory/v1/itemgroups/{itemgroup_id}/active

# 标记为不活跃
POST /zoho-inventory/inventory/v1/itemgroups/{itemgroup_id}/inactive

分页

Zoho Inventory 使用基于页面的分页：

GET /zoho-inventory/inventory/v1/items?page=1&per_page=50

响应中包含了分页信息，位于页面上下文:

{
  "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

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

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或服务
该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以禁用通配符解析
重要提示：将 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密钥问题

检查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-inventory开头。例如：

正确：https://gateway.maton.ai/zoho-inventory/inventory/v1/items
错误：https://gateway.maton.ai/inventory/v1/items

资源

免责申明

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

打赏

文章底部电脑广告

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

标签

上一篇：Self Reflection 下一篇：google-search