QBWCPoC — QuickBooks Web Connector proof of concept

A minimal Java SOAP service that speaks the QuickBooks Web Connector protocol, letting a server-side application read from and write to QuickBooks Desktop — which has no public network API of its own.

Archived. Written in 2013 against Axis2 and Java 6/7, and no longer maintained. It stays public because people still land here when wiring up the Web Connector, and the protocol has changed very little since.

Why this exists

QuickBooks Desktop keeps its data in a local company file and accepts no inbound connections. Intuit's Web Connector bridges that gap by polling: it runs on the same Windows machine as QuickBooks, calls out to your SOAP service on a schedule, asks whether there is work to do, and shuttles qbXML requests and responses back and forth.

So your service is the SOAP server, but the Web Connector drives the conversation. That inversion is the part that trips people up, and it's what this project demonstrates.

The call sequence

The connector invokes a fixed set of operations, all implemented in QBWebConnectorSvcSkeleton.java:

Operation	What this sample does
serverVersion	Returns the service version string
clientVersion	Returns empty — accept whatever connector version called in
authenticate	Returns a session token plus an empty company-file path, meaning "use the file already open in QuickBooks"
sendRequestXML	Returns the next qbXML request, or an empty string when there is no more work
receiveResponseXML	Receives QuickBooks' answer
connectionError	Called when the connector cannot reach QuickBooks
getLastError	Returns a message explaining why there was no work or what failed
closeConnection	Final callback, returns a closing message

Each method carries comments on what Intuit expects back, including the values with special meaning — nvu to reject invalid credentials, done to abandon a failed connection.

What the sample actually does

One thing, once: it adds a vendor. request.xml is a VendorAddRq for a fictional supplier, with {{VendorName}} substituted at send time so repeated runs don't collide on a duplicate name. After sending it, the service flips an internal flag and returns an empty string from the next sendRequestXML, which is how you tell the connector the session is finished.

Swap that file for your own qbXML and you have the skeleton of a real integration.

Build

mvn package

Deploy the resulting WAR to a servlet container. Axis2 generates the endpoint from QBWebConnectorSvc.wsdl and publishes it at /services/QBWebConnectorSvc.

Connecting it to QuickBooks

qbwc-poc.qwc is the application descriptor you import through File → Add an Application in the Web Connector. Edit AppURL before importing — it ships pointing at http://localhost:8080. The Web Connector requires HTTPS for any host that isn't localhost.

QBWCPoCHowto.pdf walks through the full setup with screenshots.

Layout

src/main/java/com/test/ws/          service skeleton, message receiver, WSDL
src/main/java/com/intuit/developer/ generated request/response types
src/main/resources/…/request.xml    the qbXML this sample sends
src/main/webapp/WEB-INF/            web.xml and Axis2 configuration
qbwc-poc.qwc                        Web Connector application descriptor