QuickBooks

通过受管 OAuth 认证访问 QuickBooks Online API。管理客户、供应商、发票、付款，并运行财务报表。

快速开始

# 查询客户
python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://api.maton.ai/quickbooks/v3/company/:realmId/query?query=SELECT%20*%20FROM%20Customer%20MAXRESULTS%20100')
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://api.maton.ai/quickbooks/{endpoint-path}

网关将请求代理至 quickbooks.api.intuit.com，且占位符 :realmId 会自动替换为连接配置中您公司的 realm ID。仅支持下文“API 参考”章节中明确记录的端点 —— 请始终使用该章节中列出的具体端点路径，切勿自行构造任意路径。

认证

所有请求均需在 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 密钥

连接管理

在 https://api.maton.ai 管理您的 QuickBooks OAuth 连接。

列出连接

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://api.maton.ai/connections?app=quickbooks&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': 'quickbooks'}).encode()
req = urllib.request.Request('https://api.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://api.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": "{connection_id}",
    "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": "quickbooks",
    "metadata": {}
  }
}

在浏览器中打开返回的 url 以完成 OAuth 授权。

删除连接

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://api.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

指定连接

若您拥有多个 QuickBooks 连接，请使用 Maton-Connection 请求头指定目标连接：

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://api.maton.ai/quickbooks/v3/company/:realmId/companyinfo/:realmId')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
req.add_header('Maton-Connection', '{connection_id}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

请始终包含 Maton-Connection 请求头，以确保请求被路由至预期的 QuickBooks 公司（尤其是执行任何写入操作前）。若您拥有多个连接却省略该请求头，网关将使用默认连接，这可能并非您意图操作的账户。

安全与权限

• 访问范围受限于已连接账户所授予的 OAuth 权限范围。仅在确有 QuickBooks 账务管理需求时安装。应遵循最小权限原则，并及时撤销不再使用的连接。
• 默认采用只读操作。 在提出任何变更前，请始终先列出或检索资源，以确认标识符、金额及账户上下文。
• 所有写入操作均需用户明确批准并附带具体细节。 在执行任何 POST 或 DELETE 请求前：
  1. 检索并展示目标资源（如客户名称/ID、发票编号、付款金额），供用户核验；
  2. 清晰描述预期影响（例如：“此操作将作废客户‘Acme Corp’的发票 #1042（$500.00）——该操作不可撤销”）；
  3. 必须等待用户明确确认后方可继续执行。
• 账务操作影响重大。 任何创建、修改或删除发票、付款、账单或客户记录的操作均会影响财务账簿。此类操作必须附带财务影响摘要，并要求用户确认。

API 参考

公司信息

GET /quickbooks/v3/company/:realmId/companyinfo/:realmId

客户

查询客户

GET /quickbooks/v3/company/:realmId/query?query=SELECT%20*%20FROM%20Customer%20MAXRESULTS%20100

获取客户

GET /quickbooks/v3/company/:realmId/customer/{customerId}

创建客户

POST /quickbooks/v3/company/:realmId/customer
Content-Type: application/json

{
  "DisplayName": "John Doe",
  "PrimaryEmailAddr": {"Address": "john@example.com"},
  "PrimaryPhone": {"FreeFormNumber": "555-1234"}
}

更新客户

需在请求体中包含此前 GET 返回的 Id 和 SyncToken：

POST /quickbooks/v3/company/:realmId/customer
Content-Type: application/json

{
  "Id": "123",
  "SyncToken": "0",
  "DisplayName": "John Doe Updated"
}

发票

查询发票

GET /quickbooks/v3/company/:realmId/query?query=SELECT%20*%20FROM%20Invoice%20MAXRESULTS%20100

创建发票

POST /quickbooks/v3/company/:realmId/invoice
Content-Type: application/json

{
  "CustomerRef": {"value": "123"},
  "Line": [
    {
      "Amount": 100.00,
      "DetailType": "SalesItemLineDetail",
      "SalesItemLineDetail": {
        "ItemRef": {"value": "1"},
        "Qty": 1
      }
    }
  ]
}

删除发票

POST /quickbooks/v3/company/:realmId/invoice?operation=delete
Content-Type: application/json

{
  "Id": "123",
  "SyncToken": "0"
}

付款

创建付款

POST /quickbooks/v3/company/:realmId/payment
Content-Type: application/json

{
  "CustomerRef": {"value": "123"},
  "TotalAmt": 100.00,
  "Line": [
    {
      "Amount": 100.00,
      "LinkedTxn": [{"TxnId": "456", "TxnType": "Invoice"}]
    }
  ]
}

报表

损益表（Profit and Loss）

GET /quickbooks/v3/company/:realmId/reports/ProfitAndLoss?start_date=2024-01-01&end_date=2024-12-31

资产负债表（Balance Sheet）

GET /quickbooks/v3/company/:realmId/reports/BalanceSheet?date=2024-12-31

批量操作

POST /quickbooks/v3/company/:realmId/batch
Content-Type: application/json

{
  "BatchItemRequest": [
    {"bId": "1", "Query": "SELECT * FROM Customer MAXRESULTS 2"},
    {"bId": "2", "Query": "SELECT * FROM Vendor MAXRESULTS 2"}
  ]
}

查询语言

QuickBooks 使用类 SQL 查询语法：

SELECT * FROM Customer WHERE DisplayName LIKE 'John%' MAXRESULTS 100

支持的运算符：=、LIKE、<、>、<=、>=、IN

SyncToken

所有更新操作均需提供当前 SyncToken：

1. 先执行 GET 获取实体当前的 SyncToken
2. 在 POST 请求体中同时包含 Id 和 SyncToken
3. 若 SyncToken 不匹配，则更新失败

代码示例

JavaScript

const response = await fetch(
  'https://api.maton.ai/quickbooks/v3/company/:realmId/query?query=SELECT%20*%20FROM%20Customer',
  {
    headers: {
      'Authorization': `Bearer ${process.env.MATON_API_KEY}`
    }
  }
);

Python

import os
import requests

response = requests.get(
    'https://api.maton.ai/quickbooks/v3/company/:realmId/query',
    headers={'Authorization': f'Bearer {os.environ["MATON_API_KEY"]}'},
    params={'query': 'SELECT * FROM Customer MAXRESULTS 10'}
)

注意事项

• :realmId 将由路由层自动替换
• 所有查询字符串必须进行 URL 编码
• 请使用 MAXRESULTS 限制查询结果数量
• 日期格式为 YYYY-MM-DD
• 通过设置 Active: false 实现软删除
• 重要：使用 curl 命令时，若 URL 中含方括号（如 fields[]、sort[]、records[]），请添加 -g 参数以禁用 glob 解析
• 重要：当将 curl 输出管道传递给 jq 或其他命令时，在部分 shell 环境中环境变量（如 $MATON_API_KEY）可能无法正确展开，从而导致“Invalid API key”错误。

错误处理

故障排查：API 密钥问题

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

echo $MATON_API_KEY

2. 通过列出连接验证 API 密钥有效性：

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://api.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 路径以 quickbooks 开头。例如：

• 正确：https://api.maton.ai/quickbooks/v3/company/:realmId/query
• 错误：https://api.maton.ai/v3/company/:realmId/query

相关资源

• QuickBooks API 概览
• 客户
• 发票
• 付款
• 报表
• Maton 社区
• Maton 支持