TenkeyBridge
← Back to blog

QuickBooks SDK vs. Web Connector vs. a REST Bridge: Picking a Desktop Integration Path

  • quickbooks sdk vs web connector
  • qbxml vs rest api
  • quickbooks desktop api options
  • quickbooks web connector alternative
Hands at a laptop loading a .QWC file into Web Connector, with raw qbXML open on a second monitor.

Quick answers

What are my options for integrating with QuickBooks Desktop? Three: write qbXML against the QBXMLRP2 COM SDK on the same Windows machine as the company file, build a SOAP service that QuickBooks Web Connector polls, or call a REST API that wraps one of those for you.

Is qbXML still required? Underneath, yes — every path ends in qbXML requests against the Desktop file — but you don't have to author it yourself if something else does that translation.

What's the difference between the SDK and the Web Connector? The SDK is an in-process COM API that requires your code to run on the QuickBooks machine; the Web Connector is a desktop app that polls your server over HTTPS, so your code runs anywhere.

When does a REST bridge win? When you already ship against the QuickBooks Online API and want to reuse those request shapes, OAuth2 flow, and query syntax instead of writing a second integration.

When is hand-rolled qbXML still the right call? When you need an entity or an attribute the REST layer doesn't map, or you're already shipping a Windows agent to the customer's server anyway.


If you ship an integration against the QuickBooks Online API and a customer says "we're on Desktop Enterprise," you're suddenly evaluating a protocol stack that was designed in the early 2000s and has not meaningfully changed. This is a neutral tour of the three paths, what each one actually requires of you and the customer, and how to pick.

No claims here about other vendors. Just the mechanics.

The one thing all three have in common

QuickBooks Desktop has no network API. The company file (.QBW) is opened by the QuickBooks application, and the only supported way to read or write it programmatically is qbXML — a request/response XML dialect — delivered through the QuickBooks SDK's QBXMLRP2 COM object, running on the same Windows machine, with QuickBooks either running or able to be auto-started.

That's the floor. Everything else is a question of who runs that COM call and how the request gets there.

A minimal qbXML request looks like this:

<?xml version="1.0" encoding="utf-8"?>
<?qbxml version="16.0"?>
<QBXML>
  <QBXMLMsgsRq onError="stopOnError">
    <CustomerQueryRq requestID="1">
      <MaxReturned>50</MaxReturned>
    </CustomerQueryRq>
  </QBXMLMsgsRq>
</QBXML>

Fine. Now look at the equivalent in the QBO API — GET /v3/company/{realmId}/query?query=select * from Customer maxresults 50 — and you can see the size of the gap you're deciding how to cross.

Path 1: qbXML directly against the COM SDK

You write a Windows application (.NET, or anything that can do COM interop) that opens a session with QBXMLRP2.RequestProcessor, passes qbXML strings in, and parses qbXML strings out.

Who hosts what: the customer hosts everything. Your code is installed on their server, next to the company file, under their patch cycle and their antivirus.

Where the code runs: on the QuickBooks machine. Period. There is no remote mode. If the file lives on a hosted desktop (Rightworks, a private RDS farm, Citrix), you are asking a hosting provider to let you install a binary on a shared image — which is a procurement conversation, not an engineering one.

How errors surface: two layers, and they look nothing alike. COM-level failures come back as HRESULTs (0x80040408 when QuickBooks isn't running, 0x80040402 for an unknown error from the request processor). Application-level failures come back inside the response XML as statusCode / statusSeverity / statusMessage on each *Rs element — and a statusCode="3140" ("invalid reference to QuickBooks list element") is the kind of thing you'll spend an afternoon mapping to "the Customer ListID in my payload doesn't exist in this file." We've written up how those status codes and HRESULTs map onto QBO-style faults if you want the decoder ring.

QBO code reuse: approximately none. Different auth model (there is no auth — you get a certificate-based grant from a human clicking a dialog in QuickBooks), different entity names, different field names, different pagination (IteratorID, not STARTPOSITION), different everything.

When it's still the right choice:

  • You need qbXML surface area that no abstraction layer exposes — obscure request types, DataExtRet custom fields on unusual entities, or *Mod semantics you want byte-level control over.
  • You're already shipping a Windows agent to this customer for other reasons (a POS bridge, a scanner service), so the install is already paid for.
  • You're doing a one-time migration, you have physical access to the machine, and nothing needs to run again next Tuesday.

Honest trade-off: this is the most capable path and the most expensive one to operate. Every customer upgrade, every "the server rebooted and QuickBooks came back in single-user mode," every hosting-provider image refresh is your pager.

Path 2: QuickBooks Web Connector

The Web Connector (QBWC) is a small Intuit-provided desktop application that ships with QuickBooks. You give the customer a .QWC XML file; they load it into the Web Connector; the Web Connector then polls your server on a schedule over HTTPS, speaking SOAP.

The inversion is the whole point. You don't call QuickBooks. QuickBooks' helper app calls you, and asks: do you have any work for me?

The SOAP contract is small and fixed:

| Method | What happens | |---|---| | authenticate | QBWC sends the username/password from the .QWC; you return a session ticket and either an empty string (use the currently open file) or a file path | | sendRequestXML | You return the next qbXML request string, or empty string to signal "nothing left" | | receiveResponseXML | QBWC hands you the qbXML response; you return a percent-complete integer | | getLastError / connectionError | Failure reporting back to the Web Connector UI | | closeConnection | Session teardown |

Who hosts what: you host the SOAP endpoint; Intuit's app runs on the customer's machine. Nothing of yours gets installed. That is a materially easier conversation with a hosted-QuickBooks provider, because the Web Connector is already approved software on those images.

Where the code runs: your infrastructure, any OS, any language that can serve SOAP.

How errors surface: same two layers as Path 1 — you still author and parse qbXML — plus a third: Web Connector's own transport and scheduling errors, which land in QWCLog.txt on the customer's machine where you cannot see them without asking someone to email you a file.

QBO code reuse: still basically none. You've solved the deployment problem. You have not solved the protocol problem.

The constraints that bite:

  • It's a poll, not a push. Minimum schedule granularity is one minute, and realistically customers set it to 5, 15, or 60. "Real-time" does not exist here. A write you queue at 10:02 may land at 10:17.
  • One request in flight at a time. sendRequestXML → receiveResponseXML is strictly serial per session. Throughput is a function of round-trip count, so batching matters — and batches on Desktop are not transactions, so partial failure handling is on you.
  • The customer can turn it off. It's a tray app with checkboxes. If someone unticks the row, your sync silently stops.
  • Someone has to be logged in, unless the install is configured to run QuickBooks in a service-like context — which, on hosted desktops, varies by provider.

Path 3: a QBO-shaped REST API in front of Desktop

The third path is to put a compatibility layer between your code and qbXML, so that your application speaks the REST API it already speaks.

The shape:

POST https://api.tenkeybridge.com/v3/company/{realmId}/invoice
Authorization: Bearer {oauth2_access_token}
Content-Type: application/json

{
  "CustomerRef": { "value": "42" },
  "Line": [
    { "Amount": 1250.00,
      "DetailType": "SalesItemLineDetail",
      "SalesItemLineDetail": { "ItemRef": { "value": "7" }, "Qty": 5 } }
  ]
}

That's the QBO request body, unmodified, against a Desktop company file. The bridge translates it to an InvoiceAddRq, runs it, and translates the response — including the error — back into a QBO-shaped fault.

Who hosts what: this is the part worth being specific about. TenkeyBridge runs on the Web Connector underneath. The customer loads a .QWC file into the Intuit app they already have; TenkeyBridge hosts the SOAP endpoint and the queue; you call REST. Nothing of ours is installed on the customer's server — same deployment profile as Path 2, which is why it works on hosted QuickBooks without a provider approval cycle.

Where the code runs: wherever your QBO integration already runs. No Windows requirement anywhere in your stack.

How errors surface: as HTTP status codes with QBO-style Fault objects. The qbXML statusCode is still there in the detail — you haven't lost information — but a 3140 arrives as a 400 with a fault you can switch on, not a string you have to regex.

QBO code reuse: this is the entire value proposition, and it's also where honesty is required. Reuse is high, not total. The Desktop data model genuinely differs from QBO's in places: some QBO entities have no Desktop equivalent, some Desktop fields have no QBO home, and a few behaviors differ by necessity. Change data capture is a good example — Desktop's *QueryRq with FromModifiedDate carries a 30-day window and object caps that QBO's CDC endpoint doesn't have. Sparse update semantics are another; sparse: true has to be emulated because qbXML *Mod requests are full replacements by default.

Read the compatibility matrix before you scope. If the entity you need isn't there, that's a real answer, and it's better to get it in week one.

The trade-offs you're accepting:

  • A third party is in the data path. For some buyers that's a contractual conversation.
  • You inherit Web Connector's latency floor, because it's underneath. A bridge can't make a poll into a push.
  • You give up byte-level qbXML control in exchange for not writing qbXML.

A decision table

| | Direct qbXML / SDK | Web Connector (your own) | QBO-shaped REST bridge | |---|---|---|---| | Install on customer server | Your binary | Intuit's app only | Intuit's app only | | Where your code runs | Customer's Windows box | Your infra (SOAP) | Your infra (REST) | | Language/OS constraints | Windows + COM | Any, must serve SOAP | Any HTTP client | | Protocol you write | qbXML | qbXML + SOAP | JSON you already write | | Auth model | QuickBooks cert grant | Shared secret in .QWC | OAuth2 | | Error format | HRESULT + status codes | HRESULT + status codes + QWC log | HTTP + QBO Fault | | Latency | Immediate (local) | Poll interval | Poll interval | | QBO code reuse | None | None | High, with documented gaps | | Full qbXML surface | Yes | Yes | What's mapped |

How to actually pick

Work through it in this order.

  1. Can you install software on the customer's QuickBooks machine? If the file is on a hosted desktop or a locked-down server, Path 1 is probably out before you evaluate anything else. Multi-user and hosted environments have their own rules.
  2. Is this one customer or a product feature? One customer, one migration, physical access: hand-rolled qbXML is fine, and arguably cheapest. A feature you'll sell to fifty Desktop shops: you want a hosted path, because fifty Windows installs is fifty support contracts.
  3. Do you already have a working QBO integration? If yes, price the rewrite honestly. It's not just the HTTP calls — it's the entity mapping, the pagination, the retry logic, the error taxonomy, the test fixtures. If you'd be rewriting all of it, the REST bridge is buying you exactly that work back.
  4. List the entities and fields you actually need. Then check them against the parity matrix. If something critical is missing, you're back to Paths 1 or 2 for that piece — and a hybrid is legitimate: REST for the 95%, your own Web Connector service for the odd *Rq that isn't mapped.
  5. Decide what "real-time" means for ExampleCo. If Pat Owner expects invoices in QuickBooks within thirty seconds of a Stripe webhook, say plainly that Desktop polls. Every hosted path has this floor. Setting that expectation in the sales call is cheaper than engineering around it later.

What this doesn't change

None of these paths give you a push notification from QuickBooks. None of them make the company file multi-writer-safe in ways QuickBooks itself isn't. None of them survive a customer who closes QuickBooks and goes on vacation. The Desktop constraints are the Desktop constraints; you're choosing how much of the translation work you want to own, not whether the constraints exist.

If you want to see the difference concretely, there's a side-by-side of the same request against the QBO sandbox and the TenkeyBridge sandbox, and a checklist for pointing an existing QBO integration at Desktop that enumerates what actually has to change in your code.

FAQ

Do I need qbXML to integrate with QuickBooks Desktop?

Something in the chain does — it's the only supported interface to the company file. But if a compatibility layer authors and parses it for you, you can ship a Desktop integration without writing a line of qbXML yourself. You'll still want to recognize the status codes when they show up in error details.

What does the Web Connector do, and what doesn't it do?

It handles the hard part of transport: it runs on the customer's machine, opens the company file through the SDK, and calls out to your HTTPS endpoint on a schedule so you never need inbound access. It does not translate protocols — you still write qbXML — and it does not push, batch concurrently, or run without the customer having it enabled.

When is a REST bridge the better choice?

When you already have QBO API code and the cost you're trying to avoid is a second integration, not a second deployment. It's also the better choice when you can't get software approved on the customer's server, since the only thing installed is the Intuit-supplied Web Connector.

Can I use more than one path at once?

Yes. Running REST for mapped entities and your own Web Connector service for an unmapped request type is a reasonable hybrid, as long as you're clear about which system owns which writes. Two writers against the same file still need the same coordination discipline as any concurrent integration.

Does any of this work for read-only reporting?

All three can read, but note that Desktop reports come back as qbXML report responses with their own row/column structure, not as the QBO Report JSON shape. Check the parity matrix for which reports are mapped before you promise a dashboard.

What about AI agents and tool-calling?

A REST layer with stable, documented shapes is considerably easier to hand to an agent than a COM interop library, mostly because the error path is inspectable. There's a longer write-up on giving an agent checkable access to a Desktop file if that's where you're headed. If you want to try the REST shape against a real Desktop file without setting anything up, the sandbox and the quickstart are both about ten minutes.