介绍
# Zoho Books
通过托管的 OAuth 身份验证访问 Zoho Books API。使用完整的 CRUD（增删改查）操作管理发票、联系人、账单、费用、销售订单、采购订单和其他会计数据。
## 快速开始
```bash # 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 ```
## 基础 URL
``` https://gateway.maton.ai/zoho-books/books/v3/{endpoint} ```
网关将请求代理到 `www.zohoapis.com/books/v3` 并自动注入您的 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 Books OAuth 连接。
### 列出连接
```bash 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 ```
### 创建连接
```bash 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 ```
### 获取连接
```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-books", "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 Books 连接，请使用 `Maton-Connection` 标头指定要使用的连接：
```bash 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 ```
如果省略，网关将使用默认（最旧）的活动连接。
## API 参考
### 可用模块
Zoho Books 将数据组织到模块中。主要模块包括：
| 模块 | 端点 | 描述 | |--------|----------|-------------| | 联系人 | `/contacts` | 客户和供应商 | | 发票 | `/invoices` | 销售发票 | | 账单 | `/bills` | 供应商账单 | | 费用 | `/expenses` | 业务费用 | | 销售订单 | `/salesorders` | 销售订单 | | 采购订单 | `/purchaseorders` | 采购订单 | | 贷项通知单 | `/creditnotes` | 客户贷项通知单 | | 循环发票 | `/recurringinvoices` | 自动循环发票 | | 循环账单 | `/recurringbills` | 自动循环账单 |
### 联系人
#### 列出联系人
```bash GET /zoho-books/books/v3/contacts ```
**示例：**
```bash 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 ```
**响应：** ```json { "code": 0, "message": "success", "contacts": [...], "page_context": { "page": 1, "per_page": 200, "has_more_page": false, "sort_column": "contact_name", "sort_order": "A" } } ```
#### 获取联系人
```bash GET /zoho-books/books/v3/contacts/{contact_id} ```
**示例：**
```bash 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 ```
#### 创建联系人
```bash POST /zoho-books/books/v3/contacts Content-Type: application/json
{ "contact_name": "Customer Name", "contact_type": "customer" } ```
**必填字段：** - `contact_name` - 联系人的显示名称 - `contact_type` - `customer`（客户）或 `vendor`（供应商）
**可选字段：** - `company_name` - 法人实体名称 - `email` - 电子邮件地址 - `phone` - 电话号码 - `billing_address` - 地址对象 - `payment_terms` - 付款天数
**示例：**
```bash python <<'EOF' import urllib.request, os, json data = json.dumps({ "contact_name": "Acme Corporation", "contact_type": "customer", "company_name": "Acme Corp", "email": "[email protected]", "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 ```
**响应：** ```json { "code": 0, "message": "The contact has been added.", "contact": { "contact_id": "8527119000000099001", "contact_name": "Acme Corporation", "company_name": "Acme Corp", "contact_type": "customer", ... } } ```
#### 更新联系人
```bash PUT /zoho-books/books/v3/contacts/{contact_id} Content-Type: application/json
{ "contact_name": "Updated Name", "phone": "+1-555-9999" } ```
**示例：**
```bash 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 ```
#### 删除联系人
```bash DELETE /zoho-books/books/v3/contacts/{contact_id} ```
**示例：**
```bash 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 ```
**响应：** ```json { "code": 0, "message": "The customer has been deleted." } ```
### 发票
#### 列出发票
```bash GET /zoho-books/books/v3/invoices ```
**示例：**
```bash 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 ```
#### 获取发票
```bash GET /zoho-books/books/v3/invoices/{invoice_id} ```
#### 创建发票
```bash POST /zoho-books/books/v3/invoices Content-Type: application/json
{ "customer_id": "8527119000000099001", "line_items": [ { "item_id": "8527119000000100001", "quantity": 1, "rate": 100.00 } ] } ```
**必填字段：** - `customer_id` - 客户标识符 - `line_items` - 包含 `item_id` 或手动输入的项目数组
**可选字段：** - `invoice_number` - 如果未指定则自动生成 - `date` - 发票日期（yyyy-mm-dd 格式） - `due_date` - 付款到期日 - `discount` - 百分比或固定金额 - `payment_terms` - 到期天数
#### 更新发票
```bash PUT /zoho-books/books/v3/invoices/{invoice_id} ```
#### 删除发票
```bash DELETE /zoho-books/books/v3/invoices/{invoice_id} ```
#### 发票操作
```bash # 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 ```
### 账单
#### 列出账单
```bash GET /zoho-books/books/v3/bills ```
**示例：**
```bash 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 ```
#### 创建账单
```bash 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 } ] } ```
**必填字段：** - `vendor_id` - 供应商标识符 - `bill_number` - 唯一的账单编号 - `date` - 账单日期（yyyy-mm-dd）
#### 更新账单
```bash PUT /zoho-books/books/v3/bills/{bill_id} ```
#### 删除账单
```bash DELETE /zoho-books/books/v3/bills/{bill_id} ```
### 费用
#### 列出费用
```bash GET /zoho-books/books/v3/expenses ```
**示例：**
```bash 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 ```
#### 创建费用
```bash 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" } ```
**必填字段：** - `account_id` - 费用账户 ID - `date` - 费用日期（yyyy-mm-dd） - `amount` - 费用金额 - `paid_through_account_id` - 付款账户 ID
**可选字段：** - `description` - 费用详情 - `customer_id` - 可计费客户 ID - `is_billable` - 可计费费用的布尔值 - `project_id` - 关联项目
#### 更新费用
```bash PUT /zoho-books/books/v3/expenses/{expense_id} ```
#### 删除费用
```bash DELETE /zoho-books/books/v3/expenses/{expense_id} ```
### 销售订单
#### 列出销售订单
```bash GET /zoho-books/books/v3/salesorders ```
#### 创建销售订单
```bash POST /zoho-books/books/v3/salesorders ```
### 采购订单
#### 列出采购订单
```bash GET /zoho-books/books/v3/purchaseorders ```
#### 创建采购订单
```bash POST /zoho-books/books/v3/purchaseorders ```
### 贷项通知单
#### 列出贷项通知单
```bash GET /zoho-books/books/v3/creditnotes ```
### 循环发票
#### 列出循环发票
```bash GET /zoho-books/books/v3/recurringinvoices ```
### 循环账单
#### 列出循环账单
```bash GET /zoho-books/books/v3/recurringbills ```
## 分页
Zoho Books 使用基于页面的分页：
```bash GET /zoho-books/books/v3/contacts?page=1&per_page=50 ```
响应在 `page_context` 中包含分页信息：
```json { "code": 0, "message": "success", "contacts": [...], "page_context": { "page": 1, "per_page": 50, "has_more_page": true, "sort_column": "contact_name", "sort_order": "A" } } ```
当 `has_more_page` 为 `true` 时继续获取，每次递增 `page`。
## 代码示例
### JavaScript
```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
```python import os import requests
response = requests.get( 'https://gateway.maton.ai/zoho-books/books/v3/contacts', headers={'Authorization': f'Bearer {os.environ["MATON_API_KEY"]}'} ) data = response.json() ```
## 注意事项
- 所有成功的响应都有 `code: 0` 和一个 `message` 字段 - 日期应采用 `yyyy-mm-dd` 格式 - 联系人类型为 `customer`（客户）或 `vendor`（供应商） - 某些模块（项目、科目表、银行账户、项目）可能需要额外的 OAuth 范围。如果您收到范围错误，请通过 [email protected] 联系 Maton 支持，并提供您需要的特定操作/API 以及您的用例 - 速率限制：每个组织 100 次/分钟 - 每日限制因计划而异：免费版（1,000）、标准版（2,000）、专业版（5,000）、付费版（10,000） - 重要：使用 curl 命令时，当 URL 包含方括号时，请使用 `curl -g` 以禁用 glob 解析 - 重要：将 curl 输出通过管道传递给 `jq` 或其他命令时，在某些 shell 环境中，`$MATON_API_KEY` 等环境变量可能无法正确展开
## 错误处理
| 状态 | 含义 | |--------|---------| | 400 | 缺少 Zoho Books 连接或请求无效 | | 401 | Maton API 密钥无效或缺失，或 OAuth 范围不匹配 | | 404 | 资源未找到 | | 429 | 速率限制 | | 4xx/5xx | 来自 Zoho Books API 的透传错误 |
### 常见错误代码
| 代码 | 描述 | |------|-------------| | 0 | 成功 | | 57 | 未授权（OAuth 范围不匹配） | | 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-books` 开头。例如：
- 正确：`https://gateway.maton.ai/zoho-books/books/v3/contacts` - 错误：`https://gateway.maton.ai/books/v3/contacts`
## 资源
- [Zoho Books API v3 简介](https://www.zoho.com/books/api/v3/introduction/) - [Zoho Books 发票 API](https://www.zoho.com/books/api/v3/invoices/) - [Zoho Books 联系人 API](https://www.zoho.com/books/api/v3/contacts/) - [Zoho Books 账单 API](https://www.zoho.com/books/api/v3/bills/) - [Zoho Books 费用 API](https://www.zoho.com/books/api/v3/expenses/) - [Maton 社区](https://discord.com/invite/dBfFAcefs2) - [Maton 支持](mailto:[email protected])