Zoho Books — Zoho 账本 API 集成

Name: Zoho Books — Zoho 账本 API 集成
Rating: 1 (3 reviews)
Author: byungkyu

byungkyu

Zoho Books — Zoho 账本 API 集成

v1.0.2

通过 Maton 网关实现 Zoho Books API 集成，支持管理发票、联系人、账单、支出等财务数据。用于读取、创建、更新或删除 Zoho Books 中的财务记录。

3· 3,861·1 当前·1 累计

by @byungkyu·MIT-0

API工具数据分析网络工具 AI模型访问

下载技能包

License

MIT-0

最后更新

2026/2/26

安全扫描

VirusTotal

无害

查看报告

OpenClaw

安全

medium confidence

该技能的请求和运行指令与其声明的目的（通过 Maton 网关代理 Zoho Books）一致，仅要求一个 API 密钥；主要风险在于信任 Maton 服务，因为技能将请求路由到该服务。

评估建议

该技能内部一致：使用 Maton 网关访问 Zoho Books 且仅需要 MATON_API_KEY。安装前，请验证您信任 maton.ai（隐私/安全、数据处理），仅提供最小权限 API 密钥，考虑创建一个专用 Maton 帐户，审查 https://ctrl.maton.ai 的 OAuth 连接，并谨慎允许自动代理调用，因为代理可以通过 Maton 访问您的 Zoho 数据。如果需要来源，请在提供凭据前向发布者请求主页或组织身份。...

详细分析 ▾

✓ 用途与能力

该技能通过 Maton 网关暴露 Zoho Books 端点，仅请求 MATON_API_KEY。调用托管网关需要 API 密钥，与描述的托管 OAuth 集成一致。

✓ 指令范围

SKILL.md 仅指示代理调用 gateway.maton.ai 和 ctrl.maton.ai 端点，并读取 MATON_API_KEY 环境变量。它不要求代理读取无关文件、其他环境变量或本地系统状态。

✓ 安装机制

未提供安装规范或代码文件（仅指令）。这最小化了安装时风险，因为技能本身没有下载或写入磁盘。

ℹ 凭证需求

该技能要求一个环境变量 MATON_API_KEY，这与调用托管网关成比例。然而，该密钥可能授予 Maton 代理或代表 Zoho Books 连接的访问权限 — 因此，密钥授予了显著的访问权限，应视为敏感。

ℹ 持久化与权限

该技能不总是活动的，且可由用户调用。允许模型调用（正常），这意味着如果允许，代理可以自主调用 Maton 网关。这是预期行为，但如果您不信任 Maton 或提供的 API 密钥，会增加风险。

安全有层次，运行前请审查代码。

License

MIT-0

可自由使用、修改和再分发，无需署名。

查看条款 ↗

运行时依赖

无特殊依赖

版本

latestv1.0.22026/2/8

添加了指定所需环境变量和自定义表情符号的新元数据部分，以兼容 clawdbot。技能功能和 API 行为无变化。文档和示例保持不变。

● 无害

安装命令点击复制

官方npx clawhub@latest install zoho-books

镜像加速npx clawhub@latest install zoho-books --registry https://cn.clawhub-mirror.com

技能文档

（由于原始内容过长且包含大量代码块和 Markdown 格式，以下仅提供简要翻译，保留原始代码块不翻译）

# Zoho Books 访问通过托管 OAuth 认证访问 Zoho Books API。管理发票、联系人、账单、支出、销售订单、采购订单和其他财务数据，支持完整的 CRUD 操作。

... （保留原始代码块和 Markdown 格式，不进行翻译） ...

Access the Zoho Books API with managed OAuth authentication. Manage invoices, contacts, bills, expenses, sales orders, purchase orders, and other accounting data with full CRUD operations.

Quick Start

# List contacts
python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://gateway.maton.ai/zoho-books/books/v3/contacts')
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-books/books/v3/{endpoint}

The gateway proxies requests to www.zohoapis.com/books/v3 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:

export MATON_API_KEY="YOUR_API_KEY"

Getting Your API Key

Sign in or create an account at maton.ai
Go to maton.ai/settings
Copy your API key

Connection Management

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

List Connections

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://ctrl.maton.ai/connections?app=zoho-books&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

python <<'EOF'
import urllib.request, os, json
data = json.dumps({'app': 'zoho-books'}).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

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:

{
  "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-books",
    "metadata": {}
  }
}

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

Delete Connection

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 Books connections, specify which one to use with the Maton-Connection header:

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://gateway.maton.ai/zoho-books/books/v3/contacts')
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

Zoho Books organizes data into modules. Key modules include:

Module	Endpoint	Description
Contacts	`/contacts`	Customers and vendors
Invoices	`/invoices`	Sales invoices
Bills	`/bills`	Vendor bills
Expenses	`/expenses`	Business expenses
Sales Orders	`/salesorders`	Sales orders
Purchase Orders	`/purchaseorders`	Purchase orders
Credit Notes	`/creditnotes`	Customer credit notes
Recurring Invoices	`/recurringinvoices`	Automated recurring invoices
Recurring Bills	`/recurringbills`	Automated recurring bills

Contacts

List Contacts

GET /zoho-books/books/v3/contacts

Example:

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://gateway.maton.ai/zoho-books/books/v3/contacts')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

Response:

{
  "code": 0,
  "message": "success",
  "contacts": [...],
  "page_context": {
    "page": 1,
    "per_page": 200,
    "has_more_page": false,
    "sort_column": "contact_name",
    "sort_order": "A"
  }
}

Get Contact

GET /zoho-books/books/v3/contacts/{contact_id}

Example:

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://gateway.maton.ai/zoho-books/books/v3/contacts/8527119000000099001')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

Create Contact

POST /zoho-books/books/v3/contacts Content-Type: application/json

{ "contact_name": "Customer Name", "contact_type": "customer" }

Required Fields:

contact_name - Display name for the contact
contact_type - Either customer or vendor

Optional Fields:

company_name - Legal entity name
email - Email address
phone - Phone number
billing_address - Address object
payment_terms - Days for payment

Example:

python <<'EOF'
import urllib.request, os, json
data = json.dumps({
    "contact_name": "Acme Corporation",
    "contact_type": "customer",
    "company_name": "Acme Corp",
    "email": "billing@acme.com",
    "phone": "+1-555-1234"
}).encode()
req = urllib.request.Request('https://gateway.maton.ai/zoho-books/books/v3/contacts', 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:

{
  "code": 0,
  "message": "The contact has been added.",
  "contact": {
    "contact_id": "8527119000000099001",
    "contact_name": "Acme Corporation",
    "company_name": "Acme Corp",
    "contact_type": "customer",
    ...
  }
}

Update Contact

PUT /zoho-books/books/v3/contacts/{contact_id}
Content-Type: application/json{
  "contact_name": "Updated Name",
  "phone": "+1-555-9999"
}

Example:

python <<'EOF'
import urllib.request, os, json
data = json.dumps({
    "contact_name": "Acme Corporation Updated",
    "phone": "+1-555-9999"
}).encode()
req = urllib.request.Request('https://gateway.maton.ai/zoho-books/books/v3/contacts/8527119000000099001', data=data, method='PUT')
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

Delete Contact

DELETE /zoho-books/books/v3/contacts/{contact_id}

Example:

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://gateway.maton.ai/zoho-books/books/v3/contacts/8527119000000099001', 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

Response:

{
  "code": 0,
  "message": "The customer has been deleted."
}

Invoices

List Invoices

GET /zoho-books/books/v3/invoices

Example:

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://gateway.maton.ai/zoho-books/books/v3/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 Invoice

GET /zoho-books/books/v3/invoices/{invoice_id}

Create Invoice

POST /zoho-books/books/v3/invoices
Content-Type: application/json{
  "customer_id": "8527119000000099001",
  "line_items": [
    {
      "item_id": "8527119000000100001",
      "quantity": 1,
      "rate": 100.00
    }
  ]
}

Required Fields:

customer_id - Customer identifier
line_items - Array of items with item_id or manual entry

Optional Fields:

invoice_number - Auto-generated if not specified
date - Invoice date (yyyy-mm-dd format)
due_date - Payment due date
discount - Percentage or fixed amount
payment_terms - Days until due

Update Invoice

PUT /zoho-books/books/v3/invoices/{invoice_id}

Delete Invoice

DELETE /zoho-books/books/v3/invoices/{invoice_id}

Invoice Actions

# Mark as sent
POST /zoho-books/books/v3/invoices/{invoice_id}/status/sent
# Void invoice
POST /zoho-books/books/v3/invoices/{invoice_id}/status/void# Email invoice
POST /zoho-books/books/v3/invoices/{invoice_id}/email

Bills

List Bills

GET /zoho-books/books/v3/bills

Example:

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://gateway.maton.ai/zoho-books/books/v3/bills')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

Create Bill

POST /zoho-books/books/v3/bills Content-Type: application/json

{ "vendor_id": "8527119000000099002", "bill_number": "BILL-001", "date": "2026-02-06", "line_items": [ { "account_id": "8527119000000100002", "description": "Office Supplies", "amount": 150.00 } ] }

Required Fields:

vendor_id - Vendor identifier
bill_number - Unique bill number
date - Bill date (yyyy-mm-dd)

Update Bill

PUT /zoho-books/books/v3/bills/{bill_id}

Delete Bill

DELETE /zoho-books/books/v3/bills/{bill_id}

Expenses

List Expenses

GET /zoho-books/books/v3/expenses

Example:

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://gateway.maton.ai/zoho-books/books/v3/expenses')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

Create Expense

POST /zoho-books/books/v3/expenses Content-Type: application/json

{ "account_id": "8527119000000100003", "date": "2026-02-06", "amount": 75.50, "paid_through_account_id": "8527119000000100004", "description": "Business lunch" }

Required Fields:

account_id - Expense account ID
date - Expense date (yyyy-mm-dd)
amount - Expense amount
paid_through_account_id - Payment account ID

Optional Fields:

description - Expense details
customer_id - Billable customer ID
is_billable - Boolean for billable expenses
project_id - Associated project

Update Expense

PUT /zoho-books/books/v3/expenses/{expense_id}

Delete Expense

DELETE /zoho-books/books/v3/expenses/{expense_id}

Sales Orders

List Sales Orders

GET /zoho-books/books/v3/salesorders

Create Sales Order

POST /zoho-books/books/v3/salesorders

Purchase Orders

List Purchase Orders

GET /zoho-books/books/v3/purchaseorders

Create Purchase Order

POST /zoho-books/books/v3/purchaseorders

Credit Notes

List Credit Notes

GET /zoho-books/books/v3/creditnotes

Recurring Invoices

List Recurring Invoices

GET /zoho-books/books/v3/recurringinvoices

Recurring Bills

List Recurring Bills

GET /zoho-books/books/v3/recurringbills

Pagination

Zoho Books uses page-based pagination:

GET /zoho-books/books/v3/contacts?page=1&per_page=50

Response includes pagination info in page_context:

{
  "code": 0,
  "message": "success",
  "contacts": [...],
  "page_context": {
    "page": 1,
    "per_page": 50,
    "has_more_page": true,
    "sort_column": "contact_name",
    "sort_order": "A"
  }
}

Continue fetching while has_more_page is true, incrementing page each time.

Code Examples

JavaScript

const response = await fetch(
  'https://gateway.maton.ai/zoho-books/books/v3/contacts',
  {
    headers: {
      'Authorization': Bearer ${process.env.MATON_API_KEY}
    }
  }
);
const data = await response.json();

Python

import os
import requestsresponse = requests.get(
    'https://gateway.maton.ai/zoho-books/books/v3/contacts',
    headers={'Authorization': f'Bearer {os.environ["MATON_API_KEY"]}'}
)
data = response.json()

Notes

All successful responses have code: 0 and a message field
Dates should be in yyyy-mm-dd format
Contact types are customer or vendor
Some modules (items, chart of accounts, bank accounts, projects) may require additional OAuth scopes. If you receive a scope error, contact Maton support at support@maton.ai with the specific operations/APIs you need and your use-case
Rate limits: 100 requests/minute per organization
Daily limits vary by plan: Free (1,000), Standard (2,000), Professional (5,000), Paid (10,000)
IMPORTANT: When using curl commands, use curl -g when URLs contain brackets to disable glob parsing
IMPORTANT: When piping curl output to jq or other commands, environment variables like $MATON_API_KEY may not expand correctly in some shell environments

Error Handling

Status	Meaning
400	Missing Zoho Books connection or invalid request
401	Invalid or missing Maton API key, or OAuth scope mismatch
404	Resource not found
429	Rate limited
4xx/5xx	Passthrough error from Zoho Books API

Common Error Codes

Code	Description
0	Success
57	Not authorized (OAuth scope mismatch)
1	Invalid value
2	Mandatory field missing
3	Resource does not exist
5	Invalid URL

Troubleshooting: API Key Issues

Check that the MATON_API_KEY environment variable is set:

echo $MATON_API_KEY

Verify the API key is valid by listing connections:

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

Troubleshooting: Invalid App Name

Ensure your URL path starts with zoho-books. For example:

Correct: https://gateway.maton.ai/zoho-books/books/v3/contacts
Incorrect: https://gateway.maton.ai/books/v3/contacts

Resources

数据来源：ClawHub ↗ · 中文优化：龙虾技能库

OpenClaw 技能定制 / 插件定制 / 私有工作流定制

免费技能或插件可能存在安全风险，如需更匹配、更安全的方案，建议联系付费定制

了解定制服务

License

运行时依赖

版本

安装命令 点击复制

技能文档

Quick Start

Base URL

Authentication

Getting Your API Key

Connection Management

List Connections

Create Connection

Get Connection

Delete Connection

Specifying Connection

API Reference

Available Modules

Contacts

List Contacts

Get Contact

Create Contact

Update Contact

Delete Contact

Invoices

List Invoices

Get Invoice

Create Invoice

Update Invoice

Delete Invoice

Invoice Actions

Bills

List Bills

Create Bill

Update Bill

Delete Bill

Expenses

List Expenses

Create Expense

Update Expense

Delete Expense

Sales Orders

List Sales Orders

Create Sales Order

Purchase Orders

List Purchase Orders

Create Purchase Order

Credit Notes

List Credit Notes

Recurring Invoices

List Recurring Invoices

Recurring Bills

List Recurring Bills

Pagination

Code Examples

JavaScript

Python

Notes

Error Handling

Common Error Codes

Troubleshooting: API Key Issues

Troubleshooting: Invalid App Name

Resources

安装命令点击复制