Zoho Inventory

TotalClaw 作者 maton v1.0.3
Zoho Inventory API 与托管 OAuth 集成。管理项目、销售订单、发票、采购订单、账单、联系人和发货。当用户想要读取、创建、更新或删除 Zoho Inventory 中的库存项目、销售订单、发票、采购订单、账单或其他库存记录时，请使用此技能。对于其他第三方应用程序，请使用 api-gateway 技能 (https://clawhub.ai/byungkyu/api-gateway)。需要网络访问和有效的 Maton API 密钥。
源码 ↗
安装 / 下载方式

TotalClaw CLI推荐
totalclaw install totalclaw:byungkyu~zoho-inventory
cURL直接下载，无需登录
curl -fsSL https://skills.taituai.com/api/skills/totalclaw%3Abyungkyu~zoho-inventory/file -o zoho-inventory.md
Git 仓库获取源码
git clone https://github.com/openclaw/skills/commit/3d1d30901635647e5d8dc581b601899666b4b544
## 概述（中文）

Zoho Inventory API 与托管 OAuth 集成。管理项目、销售订单、发票、采购订单、账单、联系人和发货。
当用户想要读取、创建、更新或删除 Zoho Inventory 中的库存项目、销售订单、发票、采购订单、账单或其他库存记录时，请使用此技能。
对于其他第三方应用程序，请使用 api-gateway 技能 (https://clawhub.ai/byungkyu/api-gateway)。
需要网络访问和有效的 Maton API 密钥。

## 原文

# Zoho Inventory

Access the Zoho Inventory API with managed OAuth authentication. Manage items, sales orders, invoices, purchase orders, bills, contacts, shipment orders, and item groups with full CRUD operations.

## Quick Start

```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
```

## Base URL

```
https://gateway.maton.ai/zoho-inventory/inventory/v1/{endpoint}
```

The gateway proxies requests to `www.zohoapis.com/inventory/v1` and automatically injects your OAuth token.

## Authentication

All requests require the Maton API key in the Authorization header:

```
Authorization: Bearer $MATON_API_KEY
```

**Environment Variable:** Set your API key as `MATON_API_KEY`:

```bash
export MATON_API_KEY="YOUR_API_KEY"
```

### Getting Your API Key

1. Sign in or create an account at [maton.ai](https://maton.ai)
2. Go to [maton.ai/settings](https://maton.ai/settings)
3. Copy your API key

## Connection Management

Manage your Zoho Inventory OAuth connections at `https://ctrl.maton.ai`.

### List Connections

```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
```

### Create Connection

```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
```

### Get Connection

```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
```

**Response:**
```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": {}
  }
}
```

Open the returned `url` in a browser to complete OAuth authorization.

### Delete Connection

```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
```

### Specifying Connection

If you have multiple Zoho Inventory connections, specify which one to use with the `Maton-Connection` header:

```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
```

If omitted, the gateway uses the default (oldest) active connection.

## API Reference

### Available Modules

| Module | Endpoint | Description |
|--------|----------|-------------|
| Items | `/items` | Products and services |
| Item Groups | `/itemgroups` | Grouped product variants |
| Contacts | `/contacts` | Customers and vendors |
| Sales Orders | `/salesorders` | Sales orders |
| Invoices | `/invoices` | Sales invoices |
| Purchase Orders | `/purchaseorders` | Purchase orders |
| Bills | `/bills` | Vendor bills |
| Shipment Orders | `/shipmentorders` | Shipment tracking |

### Items

#### List Items

```bash
GET /zoho-inventory/inventory/v1/items
```

**Example:**

```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
```

**Response:**
```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
  }
}
```

#### Get Item

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

#### Create Item

```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
}
```

**Required Fields:**
- `name` - Item name

**Optional Fields:**
- `rate` - Sales price
- `purchase_rate` - Purchase cost
- `sku` - Stock keeping unit (unique)
- `item_type` - `inventory`, `sales`, `purchases`, or `sales_and_purchases`
- `product_type` - `goods` or `service`
- `unit` - Unit of measurement
- `is_taxable` - Tax applicability
- `tax_id` - Tax identifier
- `description` - Item description
- `reorder_level` - Reorder point
- `vendor_id` - Preferred vendor

**Example:**

```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
```

**Response:**
```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"
  }
}
```

#### Update Item

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

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

#### Delete Item

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

#### Item Status Actions

```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

#### List Contacts

```bash
GET /zoho-inventory/inventory/v1/contacts
```

**Query Parameters:**
- `filter_by` - `Status.All`, `Status.Active`, `Status.Inactive`, `Status.Duplicate`, `Status.Crm`
- `search_text` - Search across contact fields
- `sort_column` - `contact_name`, `first_name`, `last_name`, `email`, `created_time`, `last_modified_time`
- `contact_name`, `company_name`, `email`, `phone` - Field-specific filters

**Example:**

```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)), in