Skip to main content
Use the @bijection/connectors/quickbooks-desktop entrypoint to declare QuickBooks Desktop (Web Connector) resources.

​
Availability

This page describes the pinned source package. Published availability is unestablished for this artifact. Source build and package availability.

​
Resources and modes

Declare a resource in application code, then bind deployment-specific settings and credentials. See typed resources, connections and source inspection.

​
Company file

​
sync: QBWC sessions read records modified since each confirmed position, then deleted objects; EditSequence versions, read-only

The following example matches configuration standard.

​
Configuration: standard

Case: quickbooks-desktop/company/sync/standard. Connection and resource configuration are declared by this exact case. Credential kind: qbwc. Keep credential material in the private credential inventory.
Native admission analysis is available for this exact declaration. Collection: accounts
Collection: billPayments
Collection: bills
Collection: checks
Collection: creditMemos
Collection: customers
Collection: estimates
Collection: invoices
Collection: items
Collection: journalEntries
Collection: payments
Collection: purchaseOrders
Collection: salesReceipts
Collection: vendors
Recorded checks Hosted qualification: unestablished for this catalog configuration. Installed connections report their own identity, authority and current status.

​
Configuration: receivables

Case: quickbooks-desktop/company/sync/receivables. Connection and resource configuration are declared by this exact case. Credential kind: qbwc. Keep credential material in the private credential inventory.
Native admission analysis is available for this exact declaration. Collection: creditMemos
Collection: customers
Collection: invoices
Collection: items
Collection: payments
Recorded checks Hosted qualification: unestablished for this catalog configuration. Installed connections report their own identity, authority and current status.

​
Provider guidance

Compiled declaration examples and configuration details are published in the connector reference. Reads one QuickBooks Desktop company file through the QuickBooks Web Connector (QBWC), on the platform’s native qbwc transport. This is a different product from QuickBooks Online: use quickbooks for the cloud API. Intuit offers no REST API for Desktop; QBWC, installed beside QuickBooks on the customer’s Windows machine, connects out over HTTPS to the deployment on a schedule and is handed qbXML requests. Nothing is dialled, so no network relay or private endpoint is involved. company.sync declares one atomic group: one QBWC session reads every selected collection in turn and publishes each to its own table. collections selects a subset (all fourteen by default). qbXML is text: every scalar publishes as QuickBooks’ own string (amounts, quantities, true/false and dates are not converted), an aggregate (an address) as an object, a line list as an array, and an element QuickBooks did not return as null. Every transaction query asks for its line items. pageRecords is a page’s MaxReturned (100 by default, at most 500); maxResponseBytes bounds one retained response (512 KiB by default, at most 640 KiB); every (15 minutes by default) only bounds how long acquisition waits if the wake a retained response sends is lost. QBWC’s own poll interval is the .qwc file’s.

​
Setup

  1. Bind the connection: typed setup holds the QBWC username, optionally a pinned companyFile (the full .qbw path; a session QBWC opens on another file is refused) and runEveryMinutes (the poll interval the .qwc file asks for, 15 by default).
  2. Install the credential (quickbooksDesktop.credential, kind qbwc): its password is a secret of at least sixteen characters that the operator generates. The host does not generate it. The operator types the same password into QBWC once, and QBWC keeps it on that Windows machine. Rotating it means installing a new credential and entering it in QBWC again; until then QBWC’s authenticate is refused (nvu) and nothing is read.
  3. After the source’s first acquisition has minted its route, issue the .qwc file with POST /api/integrations/qbwc-setup (Deploy authority, body {source, url}). It returns the route /api/integrations/qbwc/<endpoint> and the .qwc XML: AppURL, AppSupport, the user name, OwnerID and FileID derived from the source, IsReadOnly and the poll interval. QBWC requires HTTPS except to localhost. No CLI command issues the file yet.
  4. In QuickBooks, open the company file as an administrator, add the .qwc file in QBWC (File > Update Web Services > Add an application), grant access when QuickBooks asks, and enter the password.
US editions only: the session negotiates qbXML 8.0 through 13.0, and other editions’ qbXML (Canada, UK, Australia) is not handled.

​
What a session does

Inside each session the host chooses every request; nothing QBWC sends selects a collection, query or position. Per collection, in name order, it asks for the records modified at or after its confirmed position (TimeModified; every record on the first read; inactive list elements included) through a qbXML iterator, then the entity’s deleted objects (ListDeletedQuery or TxnDeletedQuery) since its deletion position. Each response is retained in the source’s engine inbox before QBWC is answered, then published keyed by ListID/TxnID and versioned by EditSequence; a deleted object removes its key. No coverage is claimed: a modified-since read enumerates nothing. Interrupted sessions. A position advances only on the response that finished its whole query. An iterator never outlives its session, so a session closed early, a QBWC timeout, a lapsed ten-minute lease or a process restart leaves the position where it was, and the next session restarts that query from it. A refused continuation restarts the query once within the session. Rows an unfinished query already published stay as versioned observations; only the coverage the query would have confirmed is missing, and the boundary record is read again by every query. While another session still holds the lease, QBWC is answered busy. Failures. Status 1 (nothing found) and 500 are empty answers. A feature the company file does not have (3250, 3260: estimates or purchase orders turned off) or any other error status ends that collection’s read for the session. connectionError (QuickBooks not running, the file not open or not the pinned one) records QuickBooks as unavailable until the next poll. The source status shows the route, the session and the last failure, which is also what QBWC’s getLastError reports. Read only. The transport admits no command: an Add or Mod lost after QuickBooks applied it would be an unknown outcome, and writes are not built. QuickBooks’ retention of deleted objects is not checked, so a source left unpolled past it loses those deletions silently. Nothing here has reached QuickBooks Desktop or a real QuickBooks Web Connector. The shared transport’s histories run against a controlled QBWC client and company file; they do not exercise this declaration’s field paths.

​
Provider references

Provider references and prerequisites are maintained in the connector guidance above. No separate provider-documentation review date is recorded.

​
Source and evidence

Canonical connector source, native analysis and check receipts. Connector artifact: 905888ea276a2a28e36981a79e8142b2547ea451c3e63162cb6915ad4a7d1305. The resource declaration examples above are compiled and compared with exact catalog declarations. Recorded checks apply only to their source, declaration and runtime identities. Configure a connection and inspect its status to establish deployment-specific readiness.