基础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 $MATONAPIKEY

环境变量： 将您的API密钥设置为MATONAPIKEY：

bash
export MATONAPIKEY=YOURAPIKEY

获取您的API密钥

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

连接管理

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

列出连接

bash
python < import urllib.request, os, json
req = urllib.request.Request(https://ctrl.maton.ai/connections?app=quickbooks&status=ACTIVE)
req.addheader(Authorization, fBearer {os.environ[MATONAPI_KEY]})
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

创建连接

bash
python < 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.addheader(Authorization, fBearer {os.environ[MATONAPI_KEY]})
req.add_header(Content-Type, application/json)
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

获取连接

bash
python < import urllib.request, os, json
req = urllib.request.Request(https://ctrl.maton.ai/connections/{connection_id})
req.addheader(Authorization, fBearer {os.environ[MATONAPI_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,
lastupdatedtime: 2026-01-31T20:03:32.593153Z,
url: https://connect.maton.ai/?session_token=...,
app: quickbooks,
metadata: {}
}
}

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

删除连接

bash
python < import urllib.request, os, json
req = urllib.request.Request(https://ctrl.maton.ai/connections/{connection_id}, method=DELETE)
req.addheader(Authorization, fBearer {os.environ[MATONAPI_KEY]})
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

指定连接

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

bash
python < import urllib.request, os, json
req = urllib.request.Request(https://gateway.maton.ai/quickbooks/v3/company/:realmId/companyinfo/:realmId)
req.addheader(Authorization, fBearer {os.environ[MATONAPI_KEY]})
req.add_header(Maton-Connection, 21fd90f9-5935-43cd-b6c8-bde9d915ca80)
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

如果省略，网关将使用默认（最旧的）活动连接。

API参考

公司信息

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

客户

查询客户

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

获取客户

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

创建客户

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

{
DisplayName: 张三,
PrimaryEmailAddr: {Address: zhangsan@example.com},
PrimaryPhone: {FreeFormNumber: 555-1234}
}

更新客户

需要之前GET请求中的Id和SyncToken：

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

{
Id: 123,
SyncToken: 0,
DisplayName: 张三（已更新）
}

发票

查询发票

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

创建发票

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

删除发票

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

{
Id: 123,
SyncToken: 0
}

付款

创建付款

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

报告

损益表

bash
GET /quickbooks/v3/company/:realmId/reports/ProfitAndLoss?startdate=2024-01-01&enddate=2024-12-31

资产负债表

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

批量操作

bash
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的查询：

sql
SELECT * FROM Customer WHERE DisplayName LIKE 张% MAXRESULTS 100

运算符：=、LIKE、<、>、<=、>=、IN

SyncToken

所有更新都需要当前的SyncToken：

1. 1. GET实体以获取当前SyncToken
2. 在POST请求体中包含Id和SyncToken
3. 如果SyncToken不匹配，更新将失败

代码示例

JavaScript

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

Python

python
import os
import requests

response = requests.get(
https://gateway.maton.ai/quickbooks/v3/company/:realmId/query,