QuickBooks

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

快速开始

# Query customers
python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://gateway.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://gateway.maton.ai/quickbooks/{native-api-path}

将{native-api-path}替换为实际的QuickBooks API端点路径。网关将请求代理到quickbooks.api.intuit.com。:realmId占位符会自动从连接配置中替换为您公司的realm ID。

认证

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

连接管理

请在以下地址管理您的QuickBooks OAuth连接https://ctrl.maton.ai。

列出连接

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

指定连接

如果您有多个QuickBooks连接，请使用Maton-Connection请求头指定要使用哪一个：

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://gateway.maton.ai/quickbooks/v3/company/:realmId/companyinfo/:realmId')
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参考

公司信息

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请求：

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

报告

损益表

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

资产负债表

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

运算符：等于逗号相似逗号小于,,<=,>=,IN同步令牌

所有更新操作都需要提供当前的

同步令牌：通过GET请求获取实体以取得当前的

1. 同步令牌在POST请求体中包含
2. Id和同步令牌如果同步令牌不匹配，更新将失败代码示例
3. JavaScript

Python

注意事项

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

:realmId

import os
import requests

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

会自动被路由器替换

• 所有查询都必须进行URL编码is automatically replaced by the router
• All queries must be URL-encoded
• 使用MAXRESULTS来限制查询结果
• 日期格式为YYYY-MM-DD格式
• 通过设置Active: false
• 来软删除实体重要提示：使用curl命令时，如果URL包含方括号（fields[]、sort[]、records[]），请使用curl -g
• 来禁用通配符解析重要提示：当将curl输出通过管道传递给jq或其他命令时，在某些shell环境中，环境变量如$MATON_API_KEY

可能无法正确展开。通过管道传递时，您可能会遇到“API密钥无效”的错误。

故障排除：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路径以quickbooks开头。例如：

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

资源

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