qbo

qbo — QuickBooks Online 命令行工具

安装

# macOS / Linux
brew install voska/tap/qbo

# Scoop (Windows)
scoop bucket add voska https://github.com/voska/scoop-bucket && scoop install qbo

# Go (any platform)
go install github.com/voska/qbo-cli/cmd/qbo@latest

# Binary: https://github.com/voska/qbo-cli/releases

获取凭据

需要 Intuit Developer 账户和 QuickBooks 应用来获取 OAuth 凭据。

1. 在 https://developer.intuit.com 注册，并从控制面板创建应用。
2. 将 QuickBooks Online and Payments 选为平台。
3. 在 Keys & credentials 下找到你的 Client ID 和 Client Secret。
4. 添加 Redirect URI（见下文）。

完整操作流程请参阅 Intuit 的 OAuth 2.0 指南。

Redirect URI 选项

沙盒允许使用 http://localhost:8844/callback——只需在 Intuit 门户中注册该 URI，qbo auth login 就会自动处理所有操作。

生产环境不允许使用 localhost。可选方案有三种：

1. 隧道/转发地址——将某个域名（例如 https://auth.yourdomain.com）路由回你的机器。将其注册为 redirect URI。使用 --redirect-uri 或设置 QBO_REDIRECT_URI。
2. 在同一台机器上登录——如果 Agent 在带有浏览器的机器上运行，可使用隧道让 localhost 回调正常工作。
3. 无法解析的域名——将你拥有的任意域名（例如 https://yourdomain.com）注册为 redirect URI。授权后，浏览器会重定向到该域名，并在 URL 中附带 ?code=...&realmId=...&state=...。从浏览器复制完整 URL，并粘贴回 qbo auth login（或提供给 Agent 手动交换）。

设置

# Store app-level OAuth client credentials in the system keychain (one time).
# After this, no QBO_CLIENT_ID/SECRET env vars are needed for any command.
qbo auth set-client --client-id your_client_id --client-secret your_client_secret

# Sandbox — uses localhost callback automatically
qbo auth login --sandbox

# Production — specify your redirect URI
qbo auth login --redirect-uri https://yourdomain.com

# Or set it as env var / config so you don't need the flag every time
export QBO_REDIRECT_URI=https://yourdomain.com
qbo auth login

# Print the URL without opening a browser (useful for agents/remote)
qbo auth login --manual

对于非 localhost 的 redirect URI，qbo auth login 会打印授权 URL，并提示你在授权后粘贴回调 URL。

令牌和客户端凭据（运行 qbo auth set-client 后，或首次运行 qbo auth login 后）会存储在系统密钥链（macOS Keychain、Windows Credential Manager）中；无法使用时会回退到基于文件的存储 ~/.config/qbo/tokens/。凭据按以下优先级解析：环境变量（QBO_CLIENT_ID/QBO_CLIENT_SECRET）→ 密钥链 → config.json，因此环境变量仍然可用，并且设置后会覆盖密钥链中的值。在无法访问登录密钥链的无头主机上，设置 QBO_KEYRING_BACKEND=file，改用加密文件后端。

验证

完成身份验证后，确认一切正常：

qbo auth status
qbo company info --sandbox --json

如果出现 “no company ID”，请设置一个：export QBO_COMPANY_ID=<realm_id> 或 qbo company switch <realm_id>。

故障排除

问题	解决方法
no company ID	export QBO_COMPANY_ID=<realm> 或 qbo company switch <realm>
生产环境端点出现 ApplicationAuthorizationFailed	使用 --sandbox，或为生产环境公司重新授权该应用
OAuth 状态不匹配	重新运行 qbo auth login，并使用新生成的 URL
令牌已过期	运行 qbo auth refresh 或重新运行 qbo auth login

响应结构

QBO 会封装所有响应。请了解其结构：

• list/query 返回 {"QueryResponse": {"Invoice": [...], "startPosition": 1, ...}}。 使用 --results-only 解包，仅返回数组。
• get 返回 {"Invoice": {...}}。使用 jq 深入提取内容：qbo get invoice 123 --json | jq '.Invoice'
• create/update/void 返回与 get 相同的封装结构。
• report 返回 {"Header": {...}, "Rows": {...}}。

以编程方式解析输出时，始终使用 --json。

常见模式

# List with filtering — --results-only gives you the array directly
qbo list customers --sandbox --json --results-only
qbo list invoices --where "Balance > '0'" --sandbox --json --results-only

# Get by ID — drill into entity key with jq
qbo get invoice 145 --sandbox --json | jq '.Invoice'
qbo get customer 58 --sandbox --json | jq '.Customer | {Id, DisplayName, Balance}'

# Create from stdin
echo '{"DisplayName":"Acme Corp"}' | qbo create customer -f - --sandbox --json

# Create from file
qbo create invoice -f invoice.json --sandbox --json

# Record a payment against an invoice
echo '{"CustomerRef":{"value":"58"},"TotalAmt":500,"Line":[{"Amount":500,"LinkedTxn":[{"TxnId":"145","TxnType":"Invoice"}]}]}' | qbo create payment -f - --sandbox --json

# Sparse update (partial)
echo '{"Id":"58","SyncToken":"0","DisplayName":"New Name"}' | qbo update customer 58 --sparse -f - --sandbox --json

# Reports
qbo report profit-and-loss --start-date 2026-01-01 --end-date 2026-12-31 --sandbox --json
qbo report balance-sheet --sandbox --json

# Raw query
qbo query "SELECT Id, DisplayName, Balance FROM Customer WHERE Active = true" --sandbox --json --results-only

工作流：创建发票并收款

# 1. Create customer
echo '{"DisplayName":"New Client","PrimaryEmailAddr":{"Address":"[email protected]"}}' \
  | qbo create customer -f - --sandbox --json | jq '.Customer.Id'

# 2. Create item (service)
echo '{"Name":"Consulting","Type":"Service","IncomeAccountRef":{"value":"1"},"UnitPrice":150}' \
  | qbo create item -f - --sandbox --json | jq '.Item.Id'

# 3. Create invoice (use IDs from above)
echo '{"CustomerRef":{"value":"CUSTOMER_ID"},"Line":[{"Amount":1500,"DetailType":"SalesItemLineDetail","SalesItemLineDetail":{"ItemRef":{"value":"ITEM_ID"},"Qty":10,"UnitPrice":150}}]}' \
  | qbo create invoice -f - --sandbox --json | jq '.Invoice | {Id, DocNumber, TotalAmt}'

# 4. Record payment
echo '{"CustomerRef":{"value":"CUSTOMER_ID"},"TotalAmt":1500,"Line":[{"Amount":1500,"LinkedTxn":[{"TxnId":"INVOICE_ID","TxnType":"Invoice"}]}]}' \
  | qbo create payment -f - --sandbox --json

附件

qbo attach invoice 123 receipt.pdf --json
qbo list attachable --where "AttachableRef.EntityRef.value = '123'" --json --results-only
qbo download <id>

交易 PDF

qbo pdf invoice 123 -o invoice-123.pdf   # also estimate, salesreceipt, creditmemo, purchaseorder

作废交易

作废 Invoice、Payment、SalesReceipt 或 BillPayment 会将金额置零，同时保留 单据编号、日期和审计记录。作废操作无法撤销。

qbo void invoice 145 --dry-run
qbo void invoice 145 --force --no-input --sandbox --json
qbo void payment 200 --sync-token 3 --force --no-input --sandbox --json

该命令会在提交前读取当前 SyncToken；使用 --sync-token 可锁定预期值，若不匹配则会失败且不会提交。已作废的记录（TotalAmt 为零且 PrivateNote 以 Voided 开头）会返回提示，不会发送 POST 请求。试运行不会调用 API；锁定令牌时会包含确切的请求正文。 使用 --no-input 时请同时使用 --force；否则命令会提示确认。

定期交易

按计划自动记账的模板（例如，每月摊销）。 每条记录都按类型包装一个底层交易，并包含嵌套的 RecurringInfo 块：{"JournalEntry": {"RecurringInfo": {...}, "Line": [...]}}。

qbo list recurringtransaction --json --results-only
qbo get recurringtransaction <id> --json
qbo create recurringtransaction -f examples/recurring-je.json --json
qbo delete recurringtransaction <id>   # reads + echoes the full object for you

Agent 自省

qbo schema --json             # Full CLI tree, all entities, all flags
qbo schema get --json         # Schema for a specific command
qbo schema void --json        # Void arguments and --sync-token flag
qbo exit-codes --json         # Exit codes as JSON

退出代码

0=成功，1=错误，2=用法错误，3=空，4=需要身份验证，5=未找到，6=禁止访问，7=请求过多，8=可重试，10=配置错误。

参考

完整命令参考请参阅 references/COMMANDS.md。