Skip to content

README.md

Latest commit

 

History

History
86 lines (61 loc) · 5.86 KB

README.md

File metadata and controls

86 lines (61 loc) · 5.86 KB
Raw

Desktop Accounting API examples

Runnable QuickBooks Desktop integrations built on the Desktop Accounting API SDKs, in Node.js (TypeScript), Python, C# / .NET and Java. Every example exists in all four languages and does the same thing in each.

Example What it shows
quickstart Health check of the end user's QuickBooks connection, then the first 10 invoices.
create-invoice Create a customer and an invoice with a fixed idempotency key, read the invoice's current revisionNumber and update the memo, void the invoice. Re-running with the same run ID replays instead of duplicating.
network-drop A create whose response is lost on the first attempt. The SDK retries with the same idempotency key and exactly one invoice exists afterwards.
sync-customers Auto-pagination over every customer, 10 per page. --slow waits past the cursor idle window to show CursorExpiredError with its progress fields and request ID, then restarts the list and skips the IDs it already has.
async-webhooks An async-mode create returning a request handle, then a void of the invoice, plus a small webhook receiver that verifies Standard Webhooks signatures with the SDK helper.
error-handling Typed errors: code, userFacingMessage, fixes, docsUrl and requestId for an unknown customer, plus the local errors for a malformed key and a missing end user. Exits 1 if a step gets a different error than the one it demonstrates.

Packages

The examples install the released SDKs from their public registries, at version 0.7.0:

Language Folder Package
Node.js / TypeScript node @desktopaccountingapi/quickbooks-desktop on npm
Python python desktopaccountingapi-quickbooks-desktop on PyPI
C# / .NET dotnet DesktopAccountingAPI.QuickBooksDesktop on NuGet
Java java com.desktopaccountingapi:quickbooks-desktop on Maven Central

Each SDK's README documents its full API: Node.js, Python, .NET, Java.

Setup

You need:

  1. A secret key from the dashboard (API keys). Use a test project and its sk_test_... key.
  2. An end user whose QuickBooks Desktop company file is connected through the Web Connector, and QuickBooks open on that computer. Use a sample or test company file: the examples create invoices and void every invoice they create; create-invoice also creates one customer per run.
  3. The toolchains pinned in mise.toml (Node.js, Python with uv, .NET 8, Java 21 with Maven). With mise: mise install. Other installs of the supported versions work too.

Configuration comes from environment variables:

Variable Meaning
DAAPI_SECRET_KEY Secret key. Required. Keep it out of source control.
DAAPI_END_USER_ID End user (eu_...) whose company file the examples use. Required.
DAAPI_BASE_URL API base URL. Defaults to https://api.desktopaccountingapi.com.
DAAPI_WEBHOOK_SECRET Webhook endpoint signing secret (whsec_...), for async-webhooks.
PORT Port for the webhook receiver. Defaults to 8080.
DAAPI_CUSTOMER_ID, DAAPI_ITEM_ID Customer and service item the write examples use. Defaults to the first active ones.

Run the quickstart

export DAAPI_SECRET_KEY="sk_test_..." DAAPI_END_USER_ID="eu_..."

# Pick your language:
(cd node && npm install && node quickstart.ts)                                   # Node.js 22.18+
(cd python && python -m venv .venv && .venv/bin/pip install -r requirements.txt && .venv/bin/python quickstart.py)
(cd dotnet && dotnet run --project quickstart)
(cd java && mvn -q compile exec:java -Dexec.mainClass=examples.Quickstart)

On Windows, the virtual environment keeps its programs in .venv\Scripts\ instead of .venv/bin/. The Python quickstart in PowerShell:

$env:DAAPI_SECRET_KEY = "sk_test_..."; $env:DAAPI_END_USER_ID = "eu_..."
cd python
python -m venv .venv
.venv\Scripts\pip install -r requirements.txt
.venv\Scripts\python quickstart.py

Each language folder's README lists every example's run command and options.

Checks

  • mise run check:registry builds or type-checks every example in every language against the released packages from npm, PyPI, NuGet and Maven Central, and runs the webhook self-tests. CI runs it on every push and weekly.
  • mise run check does the same against SDK repository checkouts in SDK_REPOS_DIR (default ./sdk), which is how SDK changes are tested before a release.

Neither calls the API. The examples reach a real QuickBooks company file only when you run them.

Support

License

MIT. See LICENSE.

QuickBooks is a registered trademark of Intuit Inc. Desktop Accounting API is an independent product and is not affiliated with, endorsed by, or approved by Intuit Inc.