Zoho Books

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

快速入门

# 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：

export MATON_API_KEY="YOUR_API_KEY"

获取您的API密钥

1. 登录或创建账户于maton.ai
2. 前往maton.ai/settings
3. 复制您的API密钥

连接管理

在以下位置管理您的Zoho Books OAuth连接：https://ctrl.maton.ai.

列出连接

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

创建连接

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

获取连接

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

在浏览器中打开返回的网址以完成 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 Books 连接，请使用Maton-Connection标头指定要使用哪一个：

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 将数据组织到模块中。关键模块包括：

联系人

列出联系人

GET /zoho-books/books/v3/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

响应：

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

获取联系人

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

示例：

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

创建联系人

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- 付款天数

更新联系人

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

示例：

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

删除联系人

PUT /zoho-books/books/v3/contacts/{contact_id}
Content-Type: application/json

{
  "contact_name": "Updated Name",
  "phone": "+1-555-9999"
}

示例：

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 /zoho-books/books/v3/contacts/{contact_id}

发票

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

列出发票

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

示例：

获取发票

GET /zoho-books/books/v3/invoices

创建发票

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 /zoho-books/books/v3/invoices/{invoice_id}

customer_id

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

{
  "customer_id": "8527119000000099001",
  "line_items": [
    {
      "item_id": "8527119000000100001",
      "quantity": 1,
      "rate": 100.00
    }
  ]
}

- 客户标识符

• line_items- 包含以下内容的项目数组
• item_id或手动输入可选字段：invoice_number

- 如未指定，则自动生成

• date- 发票日期（yyyy-mm-dd格式）
• due_date- Invoice date (yyyy-mm-dd format)
• due_date- 付款截止日期
• 折扣- 百分比或固定金额
• 付款条件- 到期天数

更新发票

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

删除发票

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

发票操作

# 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

账单

账单列表

GET /zoho-books/books/v3/bills

示例：

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

创建账单

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

必填字段：

• 供应商ID- 供应商标识符
• 账单编号- 唯一账单编号
• 日期- 账单日期（年-月-日）

更新账单

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

删除账单

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

支出

支出列表

GET /zoho-books/books/v3/expenses

示例：

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

创建支出

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

必填字段：

• 账户ID- 费用账户ID
• 日期- 费用日期（年-月-日）
• 金额- 费用金额
• 支付账户ID- 付款账户ID

可选字段：

• 描述- 费用详情
• 客户ID- 可计费客户ID
• 是否可计费- 可计费费用的布尔值
• 项目ID- 关联项目

更新费用

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

删除费用

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

销售订单

列出销售订单

GET /zoho-books/books/v3/salesorders

创建销售订单

POST /zoho-books/books/v3/salesorders

采购订单

列出采购订单

GET /zoho-books/books/v3/purchaseorders

创建采购订单

POST /zoho-books/books/v3/purchaseorders

贷项通知单

列出贷项通知单

GET /zoho-books/books/v3/creditnotes

定期发票

列出定期发票

GET /zoho-books/books/v3/recurringinvoices

定期账单

列出定期账单

GET /zoho-books/books/v3/recurringbills

分页

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

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

响应中包含分页信息于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"
  }
}

当has_more_page为true时继续获取，每次递增page。

代码示例

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 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并包含一个消息字段
• 日期应采用yyyy-mm-dd格式
• 联系人类型为客户或供应商
• 某些模块（如物料、会计科目表、银行账户、项目）可能需要额外的OAuth权限范围。如果您收到权限范围错误，请联系Maton技术支持，邮箱为support@maton.ai并说明您需要的具体操作/API及您的使用场景
• 速率限制：每个组织每分钟100个请求
• 每日限额因套餐而异：免费版（1,000）、标准版（2,000）、专业版（5,000）、付费版（10,000）
• 重要提示：使用curl命令时，如果URL包含方括号，请使用curl -g以禁用通配符解析
• 重要提示：将curl输出通过管道传递给jq或其他命令时，像$MATON_API_KEY在某些shell环境中可能无法正确展开

错误处理

常见错误代码

故障排除：API密钥问题

1. 请检查MATON_API_KEY环境变量是否已设置：

echo $MATON_API_KEY

2. 通过列出连接来验证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

故障排除：无效的应用名称

1. 确保您的URL路径以zoho-books开头。例如：

• 正确示例：https://gateway.maton.ai/zoho-books/books/v3/contacts
• 错误示例：https://gateway.maton.ai/books/v3/contacts

资源

• Zoho Books API v3 简介
• Zoho Books 发票API
• Zoho Books 联系人API
• Zoho Books 账单API
• Zoho Books 费用API
• 马顿社区
• 马顿支持