QuickBooks_知识管理 skill-PHP中文网

首页专区 Skill 文章专题 AI工具学习编程手册

剧云中文短剧剧本制作平台 AniShort AI短剧协同制作平台 Seko AI短剧一键生成成片 Laper 剧本策划到成片协作

PHP MySQL jquery HTML CSS

QuickBooks

Polar Sponsor

爱发电赞助

.NET 9.0

立即下载

QuickBooks API 集成，采用托管 OAuth。仅在需要 QuickBooks 会计管理时安装，请使用最小权限的QuickBooks 账户进行连接...

使用管理下的 OAuth 认证访问快书在线API

功能概述

使用管理下的 OAuth 认证访问快书在线API是一项面向实际任务的技能，主要用于管理客户、供应商、发票、付款和运行财务报告；QQ 快启动.；

核心要点

Base URL；
网关代理 r。
它将相关步骤、工具调用和结果整理方式集中到统一流程中，帮助使用者更快完成目标并减少重复操作。

使用与执行

使用时应结合输入条件选择合适的执行方式，核对必要参数、依赖环境与输出内容，并按原始要求处理异常情况。该技能适合需要稳定复用相关能力的场景，可作为自动化工作流的一部分，也便于后续检查、调整和扩展。从功能定位来看，该技能强调把分散的操作要求整理成清晰、可复用的处理流程，使用户能够围绕既定目标快速准备输入、选择执行方式并获得结构化结果。

结果检查与注意事项

实际使用前应先确认任务范围、数据来源、运行环境、必要权限和关键参数，再依据技能说明逐步执行；若输入条件不完整，应先补齐信息或采用保守配置，避免因错误假设导致结果偏离需求。执行过程中需要关注工具调用是否成功、接口或依赖是否可用、输出格式是否符合预期，并对异常提示、缺失字段和边界情况进行处理；涉及批量任务时，还应保存进度，避免中断后重复操作。

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 密钥

在 maton.ai 登录或注册账户
访问 maton.ai/settings
复制您的 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：

先执行 GET 获取实体当前的 SyncToken
在 POST 请求体中同时包含 Id 和 SyncToken
若 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”错误。

错误处理

状态码	含义
400	缺少 QuickBooks 连接
401	Maton API 密钥无效或缺失
429	请求频率超限（每账户 10 次/秒）
4xx/5xx	来自 QuickBooks API 的透传错误

故障排查：API 密钥问题

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

echo $MATON_API_KEY

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