Access QuickBooks remotely with the QBConnector!

What is it?

QBConnector.exe is a distributable command-line utility that allows you to connect your QuickBooks Integrator applications to remote QuickBooks instances. It is also used to connect your application to QuickBooks in situations where direct COM access to QuickBooks is not available (e.g. Java, ASP, or ASP.NET).

How does it work?

QBConnector contains a lightweight embedded web server, which listens for HTTP requests originating from the QuickBooks Integrator components. Each request contains the XML data to be communicated to QuickBooks as well as configuration settings specifying how the connection is to be opened. The Connector then communicates with QuickBooks via COM, and returns the QuickBooks response (or an error message) in the HTTP reply.

How do I set up the QBConnector?

The QBConnector is part of the /n software QuickBooks Integrator and it will be installed in your machine automatically when you install the SDK. Once installed, run the QBConnector from the command line with user and password arguments like so:

QBConnector user password [<options>]

The user and password arguments will be used by connecting applications to authenticate to the QBConnector before access to QuickBooks is granted. You may also set additional profile options to select for this user when they connect to the QBConnector. These options are as follows:

-companyfile <filename>

This argument specifies the company file to open, if QuickBooks is not running. This should be the fully qualified path to the company file, e.g.: C:\users\Public\Documents\Intuit\QuickBooks\Sample Company Files\QuickBooks 2010\sample_product-based business.qbw. If QuickBooks is already running and the companyfile is not specified, the QBConnector will connect to the company file that is already loaded.

-appname <name>

This is the name that the QBConnector will use when identifying itself to QuickBooks. Integrated applications do not authenticate themselves to the company file, even if the company file is run in multi-user mode. Access is granted strictly based on the name of the application as it presents itself to QuickBooks. If the appname is

-port <port>

This is the port that the QBConnector listens on. If this is not specified, the QBConnector will begin listening on port 2080. You will need to use this port in the URL you specify in the connecting object when you establish a connection to the QBConnector.

-connectionmode single|multi

This determines whether the application will connect to QuickBooks in single-user or multi-use mode. If it is not set, the application will connect in whatever mode QuickBooks is already open in.

-sslcerttype pfx|user|machine
-sslcertstore <store>
-sslcertpassword <password>
-sslcertsubject <subject>

The QBConnector is capable of supporting SSL connections for additional security, and these properties are used to determine what certificate is used to host the SSL connection. If none of these properties are set, the QBConnector will host connections in plain text. Using SSL, along with a digital certificate, greatly increases the security of the Remote Connector. SSL will encrypt all data transmitted across the network, ensuring that only the Connector can read incoming requests, and that only the requesting client can read the QuickBooks responses. This prevents unauthorized parties from accessing your QuickBooks data. 

You should use a full digital certificate in the QBConnector if you are enabling SSL; this will contain a public key and a private key. This version of your certificate should be kept private. You may export a version of the certificate containing the public key only, and distribute this to all clients that need to communicate with the QBConnector.

-debug <1|2|3|4|5|6|7>

This determines what kind of logging is available to the application. The higher the number, the more detailed the log will be. You can use output redirection to log the output to file, e.g.:

QBConnector user password -debug 7 >> QBConnectorLog.txt

Once executed, the QBConnector will listen for incoming messages from authenticated applications. The messages will be processed locally and the results will be automatically returned to the requesting client. This will continue until the application is aborted (Ctrl+C).

How do I access the QBConnector with my application?

To use the QBConnector you need to set the QBConnectionString property of any of the controls:

<control name>.QBConnectionString = "URL='http://www.foo.com:2080' User='Foo' Password='Bar'"

This will instruct the control to direct its request to the QBConnector instead of the local instance of QuickBooks.

What does it cost?

There is no additional cost for using the QBConnector. You may redistribute the executable freely as long as you are a licensed user of the QuickBooks Integrator.

Can I build my own QBConnector?

The QBConnector application is built using the QBConnector object in the /n software QuickBooks Integrator toolkit (with the exception of non-Windows versions such as the Java or C++ Unix/Linux Editions). You can use this object to build a QBConnector application that is integrated more closely with your application, includes a graphical user-interface, or is branded in your name.

Configuring SSL in the /n software QuickBooks Integrator

If you have configured SSL in the QBConnector, you will need to export your public key certificate for any connecting applications. You should add the following code (or something similar) to your application:

(control name).QBConnectionString = "URL='https://www.foo.com:2080' User='Foo' Password='Bar'"
(control name).Config("SSLAcceptServerCertFile=c:\exported_cert.cer")

Note that if you use SSL, all clients must use SSL (HTTPS) to make connections.