Building a .qwc File for QuickBooks Web Connector Integration
How the Web Connector bridges QuickBooks Desktop with custom applications, what the .qwc file does, and which SOAP methods your web service must expose.
QuickBooks Desktop users who need to connect a custom web application to their company file frequently ask how to create the .qwc configuration file that the QuickBooks Web Connector requires. The question comes up most often among developers building custom integrations, and the answer requires understanding what the Web Connector actually does behind the scenes.
What the Web Connector Really Is
The Web Connector is not an API endpoint in the traditional sense. It functions as a relay or proxy that sits between QuickBooks Desktop and an external web service. Installed on the same machine running QuickBooks, it periodically polls a remote SOAP-based web service, asking whether there is work to perform. The web service responds with structured XML requests — specifically, qbXML — that instruct QuickBooks to carry out tasks such as adding a customer, querying invoices, or updating records. QuickBooks processes each request, returns a response through the Web Connector, and the cycle continues until the web service signals completion.
This polling architecture means the external application never talks to QuickBooks directly. Instead, the Web Connector mediates every exchange.
The SOAP Methods Your Web Service Must Provide
A web service intended for Web Connector integration must implement a specific set of SOAP methods. The accepted answer identifies the core methods by name, and each one plays a distinct role in the exchange.
authenticate()
This is the first method called when the Web Connector connects. It receives a username and password, validates them, and returns a two-element string array. The first element is a session ticket — a unique identifier for the connection. The second element tells the Web Connector what to do next. An empty string means use the company file currently open in QuickBooks. The literal value none signals that no further action is needed. The value nvu indicates the credentials were invalid. Supplying a file path instead directs the Web Connector to open a specific company file.
sendRequestXML()
After authentication succeeds, the Web Connector calls this method to retrieve the next qbXML request. The method receives the session ticket, company file information, country code, and version numbers. It returns a qbXML string — or an empty string when there are no more requests to send.
receiveResponseXML()
Once QuickBooks processes a request, the Web Connector passes the response back through this method. The web service can then parse the result, store data, and prepare the next request. The method returns an integer indicating completion percentage, with 100 signaling that all work is finished.
Two additional methods — connectionError and getLastError — handle error reporting and connection diagnostics.
The .qwc File Structure
The .qwc file itself is an XML document that tells the Web Connector where to find the web service and how to authenticate. At minimum, it contains the URL of the SOAP endpoint, the application display name, a username for the authenticate call, and a unique identifier called an Owner ID used for personal data queries. It also includes an optional scheduler element that controls how frequently the Web Connector polls the service — for example, every two minutes or once an hour.
A basic .qwc file includes the AppDescription, AppID, AppName, AppSupportURL, UserName, and QBXMLVersion elements, wrapped in a root QBWCXML tag. The file is saved with a .qwc extension and then opened through the Web Connector interface, where the user grants it access to the company file.
Where to Find Working Examples
The QuickBooks SDK ships with complete reference implementations. After installing the SDK, developers can find a full C# Web Connector sample that demonstrates all required SOAP methods, proper qbXML construction, and session handling. The SDK documentation also includes a detailed guide covering the architecture, security model, and supported request types.
For users dealing with damaged or corrupt QuickBooks company files that may complicate integration testing, file integrity should be verified before attempting any Web Connector exchange.
Practical Takeaway
Creating a .qwc file is the final step — not the first. The real work lies in building a compliant SOAP web service that implements the required methods, returns properly formatted qbXML, and manages session state correctly. Once that service exists and is reachable over HTTP, the .qwc file simply points the Web Connector at it.