Web Connector Guide

User Manual:

Open the PDF directly: View PDF PDF.
Page Count: 98

DownloadWeb-connector-guide
Open PDF In BrowserView PDF
Intuit QuickBooks SDK
®

QuickBooks Web Connector
Programmer’s Guide

Version 2.0

QBWC version 2.0, released May 2009. (c) 2009 Intuit Inc. All rights reserved.
QuickBooks and Intuit are registered trademarks of Intuit Inc. All other
trademarks are the property of their respective owners and should be treated
as such.
Acknowledgement: This product includes software developed by the Apache
Software Foundation () (c) 1999-2004 The Apache
Software Foundation. All rights reserved.

Intuit Inc.
P.O. Box 7850
Mountain View, CA 94039-7850
For more information about the QuickBooks SDK and the SDK documentation,
visit http://developer.intuit.com/QuickBooksSDK/.

Who Should Read This Guide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
Before You Begin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
What’s New in This Release . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7

Chapter 1: Introduction to QBWC Programming
QuickBooks Supported by QBWC . . . . . . . . . . . . . . . . . . . . . . . . .
Why Do I Need to Support QBWC in My Web Service?. . . . . . . . . . .
What is the COM Issue and How Does QBWC Solve This? . . . . . .
What is the Firewall Issue and How Does QBWC Solve That? . . .
Are There Any Alternatives to QBWC? . . . . . . . . . . . . . . . . . . . . . .
The QBWC-to-Web Service Communication Universe . . . . . . . . . . .
Initial Customer Interaction with Your Web Service . . . . . . . . . .
Ongoing Communication Between QBWC and a Web Service . . .
What Will My Web Service Solution Look Like? . . . . . . . . . . . . . . . .
How to Build a QWC File. . . . . . . . . . . . . . . . . . . . . . . . . . . . .
How to Build QBWC Support into Your Web Service . . . . . . . . . .
Are There Samples to Jumpstart My Work? . . . . . . . . . . . . . . . . . .
Frequently Asked Questions. . . . . . . . . . . . . . . . . . . . . . . . . . . . .
What Platforms and Languages can I use in my Implementation?
Why Do I Need SOAP? 15
Which QuickBooks/QB POS Versions Support QBWC?. . . . . . . . .
Can I Specify Which QuickBooks Editions Access My Service? . . .
Does My Web Service Need a Certificate to Access QBWC? . . . . .
Developing a Web Service Without Certificates 17
Where is the QBWC WSDL? . . . . . . . . . . . . . . . . . . . . . . . . . .
Is There a Limit to the Number of Messages I Send to QBWC? . .
Why QBWC and Not a Simple Web Interface? . . . . . . . . . . . . . .

.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.

. 9
. 9
. 9
10
12
12
12
14
14
14
15
15
15
15

. . . . . . . . . . . . 16
. . . . . . . . . . . . 16
. . . . . . . . . . . . 17
. . . . . . . . . . . . 17
. . . . . . . . . . . . 17
. . . . . . . . . . . . 17

Chapter 2: The QBWC Communication Model
A Closer Look at the Communication Model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19

Chapter 3: Implementing a Web Service for QBWC
Generating and Implementing the Service Skeleton with .NET . . . . . . . . . . . . . . 27
Generating and Implementing the Service Skeleton with Java and Apache Axis . . 31

Chapter 4: Building The QWC File for Your Users
A Sample QWC File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
How Do I Set the QBWCXML Fields in the QWC File? . . . . . . . . . . . . . . . . . . . . . 34
Is the Order of the Tags Important? 38
Can I Start Developing Without All That “Cert” Stuff? 38
Can I Run My Web Service in “Real Time”? 39
Can I Stop My Users From Running Updates in “Real Time”? 39
Can I Specify Run EveryNSeconds and RunEveryNMinutes in one QWC File? 39

Contents
(c) 2009 Intuit Inc. All rights reserved.

3

How Does the User Add the QWC File? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39

Chapter 5: Exchanging Data with QuickBooks and QBPOS
A Note About the Required NameSpace . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
Data Exchange Considerations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41

Chapter 6: Interacting Directly with the Web Connector
How to Implement Interactive Mode . . . . . . . . . . . . . . . .
Using docontrol to Change Web Service Behavior in QBWC.
Sample docontrol URLs . . . . . . . . . . . . . . . . . . . . . . .
For Time Consuming Updates, Use async=true . . .
How to Get Status of the Update . . . . . . . . . . . . .
Requests for the docontrol operation 45
Using doquery to Invoke Pre-Set SDK Requests . . . . . . . .

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

. . . . . . 43
. . . . . . 44
. . . . . . 44
. 44
. 45

. . . . . . . . . . . . . . . . . . . 46

Chapter 7: Understanding the End-User Experience and Setup
Initial End User Setup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49

Chapter 8: Handling Errors
The Web Connector Cannot Access QuickBooks . . . . . . . . . . . .
How Your Web Service Should Respond to QB Access Errors
Why Would a Web Service Try a Different Company? 52
The Web Service Gets Unexpected Data from Web Connector . .
How Your Web Service Should Respond to Unexpected Data
The Web Service Encounters an Unexpected State . . . . . . . . .

. . . . . . . . . . . . . . . . 51
. . . . . . . . . . . . . . . . 52
. . . . . . . . . . . . . . . . 52
. . . . . . . . . . . . . . . . 53
. . . . . . . . . . . . . . . . 53

Chapter 9: How Do I TroubleShoot Problems?
About Logging. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55
How Do I Get to the Troubleshooting Page? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55
What Is Provided at the Troubleshooting Pages? . . . . . . . . . . . . . . . . . . . . . . . . . . . 59

Chapter 10: QBWC Callback Web Method Reference
authenticate . . . . .
clientVersion . . . . .
closeConnection . .
connectionError. . .
getInteractiveURL .
getLastError . . . . .
getServerVersion. .
interactiveDone . . .
interactiveRejected
4

.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.

Contents
(c) 2009 Intuit Inc. All rights reserved.

.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.

. 62
. 66
. 68
. 69
. 71
. 72
. 74
. 75
. 76

receiveResponseXML. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77
sendRequestXML . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80

Appendix A: Understanding and Responding to QBWC Error Codes

Contents
(c) 2009 Intuit Inc. All rights reserved.

5

6

Contents
(c) 2009 Intuit Inc. All rights reserved.

ABOUT THIS GUIDE

This Programmer’s Guide describes the integration of QuickBooks and QuickBooks POS
with web services via the QuickBooks Web Connector (QBWC) application. The purpose
of this guide is to provide the details you need to know in order to successfully create a web
service that talks to QuickBooks or QuickBooks POS.
In this guide, the examples are in C-sharp.

Who Should Read This Guide
This guide is for developers who are creating web service applications that integrate with
QBWC.
In order to create the web service, we assume you are familiar with the platform you are
developing for and the language you are using to program in. You should also know a little
about SOAP, about XML and how to build an XML document.

Before You Begin
Be sure to familiarize yourself with the material contained in the Onscreen Reference for
QuickBooks and for QuickBooks POS, which contains the qbXML and qbposXML syntax
for each request and response message type.

What’s New in This Release
The following improvements have been made to QBWC 2.0:
•

Support for interactive mode:
>

Protocol Handler for Internet Explorer that allows web-based applications to
interact directly with the web connector.

>

Three new optional web methods to facilitate Interactive mode:
-InteractiveURL
-InteractiveRejected
-isInteractiveDone

•

Masterkeys are now handled and maintained automatically by .NET managed password
storage mechanism.

•

Update locking mechanism to help manage company file during simultaneous updates
from multiple web connector clients.

•

Included VERBOSE mode for logging level. With this, we now have three log levels:
NONE = No logging, DEBUG (default setting) = Logging + first 50 characters of
request/response xml, VERBOSE = Logging + complete request/response xml
Who Should Read This Guide
(c) 2009 Intuit Inc. All rights reserved.

7

8

•

Added a response value of an O: (stands for Okay)
O: for clientVersion(). It provides an update
path for user if server’s QBWCVersion is greater than user’s QBWCVersion

•

NoOp for sendRequestXML(). When sendRequestXML() call receives an empty string,
QBWC calls getLastError(). If a NOOP is sent back from web-service for the
getLastError(), QBWC will pause update for 5 seconds. This allows a web-service to
tell QBWC to wait five seconds before calling sendRequestXML() again.

•

New webmethod getServerVersion() provides a way for web-service to notify QBWC
of itís version. This version string shows up in the More Information pop-up dialog in
QBWC.

•

Notification (system tray pop up) is now turned off by default.

•

A new optional QWC parameter  to provide means to provide certificate
server for ssl certificates other than web server.

•

A new optional QWC parameter  introduced. Value of true will enable
notification (pop up at systray) at app level. Anything else will disable notification.

•

- A new optional QWC parameter  is introduced. If available,
QBWC will use this to display name in the QBWC UI. Otherwise, use  as
usual. This is just for UI purpose. Update process still uses the  (or,
AppUniqueName if provided)

•

A new optional parameter  is introduced. If this element is
available in QWC file, QBWC will not go into itís typical clone/replace mode for
AppName and directly use the replace routine.

•

There are new optional QWC file parameters for three rp.AuthPreferences parameters
IsReadOnly (true/false), UnattendedModePref (umpRequired/umpOptional), and
PersonalDataPref(pdpNotNeeded/pdpOptional/pdpRequired).

•

Improved performance due to code refactoring.

•

Improved error messages with suggestions on actions where applicable.

About This Guide
(c) 2009 Intuit Inc. All rights reserved.

CHAPTER 1
INTRODUCTION TO QBWC PROGRAMMING

1
1

If you are developing a web-based application that works with QuickBooks or QB POS,
you’ll want to consider implementing a solution designed to work with the QuickBooks
Web Connector (QBWC). QBWC enables web-based applications to access Quickbooks
and QuickBooks Point of Sale (QBPOS) over the internet.

QuickBooks Supported by QBWC
The following QuickBooks versions/editions are supported/not supported as indicated:
•

Enterprise Edition: all editions

•

Pro & Premier, QB 2002 and later

•

Simple Start Edition: QuickBooks 2006 and later

•

Online Edition: Not supported

Why Do I Need to Support QBWC in My Web Service?
There are a couple of reasons why you need to include QBWC support in your
implementation of a web-based application that talks to QuickBooks or QBPOS. The first
revolves around the basic COM issue, which applies more to QuickBooks integrations than
to QBPOS. The second revolves around the firewall issue, which potentially applies to
both.

What is the COM Issue and How Does QBWC Solve This?
In order for an application to access QuickBooks via the SDK, it must instantiate the
QuickBooks SDK request processor via COM. COM requires the COM object server and
its client (your application) to be resident on the same machine, or at least in the same LAN
(if you use DCOM and configure things very carefully). Consequently, your web-based
application, which is not in the same LAN or on the same machine, cannot access
QuickBooks directly via the request processor.
To get around this limitation, in the past, developers have created a go-between application
that resides on the same machine as QuickBooks and does the QuickBooks interaction,
passing the results back to their web-based app. This approach does work, but adds a
significant amount of learning and work to the implementation effort.

QuickBooks Supported by QBWC
(c) 2009 Intuit Inc. All rights reserved.

9

Which is why QBWC was developed. QBWC is a free and standard go-between application
that can be used by any web-based application that needs to talk to QuickBooks or QBPOS.
The core function of QBWC is to act as the conduit through which all qbXML/qbposXML
requests and responses pass between web-based applications and QuickBooks or QBPOS.

What is the Firewall Issue and How Does QBWC Solve That?
For QBPOS, the request processor can be on a remote machine, such as the one hosting
your web service. So a web service could conceivably talk to remote QBPOS installations.
However, with this, there is a security issue as those remote QBPOS installations would
have to open their firewall to each web service.
For QuickBooks, some developers have considered using the Remote Data Sharing (RDS)
feature introduced with QB SDK 2.1 to allow their web-based application to talk to
QuickBooks. This approach is not recommended for various security reasons, one of which
being the requirement of opening a firewall port to the RDS server, which is not secure
enough for this purpose when it comes to the internet, as RDS is a LAN solution, not an
internet one.
QBWC eliminates the firewall issue by using an “upside-down” communication model
where the QBWC initiates the session with the web service over HTTPS and asks the web
service if it has work for QuickBooks or QBPOS (see Figure 1-1.) Consequently, there is no
need to open any ports.

10 Chapter 1: Introduction to QBWC Programming
(c) 2009 Intuit Inc. All rights reserved.

Figure 1-1

QBWC “upside-down” communication model

IMPORTANT
Some firewalls may initially interfere with QBWC in that they
may prevent QBWC’s initial outbound contacting of the web
services. In these special cases, some additional tweaking of
the firewall to allow QBWC to reach out to web services may
be required.

Why Do I Need to Support QBWC in My Web Service? 11
(c) 2009 Intuit Inc. All rights reserved.

Are There Any Alternatives to QBWC?
The only recommended alternative to QBWC to enable web-based application integration is
for a developer to write their own go-between application, in effect, replacing QBWC with
their own implementation.
There are other alternatives, but these are not recommended. Using RDS involves
substantial security risk, as we’ve already mentioned. Using the unsupported Intuit
Interchange Format (IIF), as some web developers have done, is not recommended because
this bypasses the QuickBooks business logic, and so could result in data that is unsound
from an accounting and a QuickBooks business logic perspective.

The QBWC-to-Web Service Communication Universe
There are two aspects of the overall QBWC-to-web service communication that you need to
keep in mind:
•

What does the initial customer interaction look like?

•

What does ongoing data communication with the web service look like?

Initial Customer Interaction with Your Web Service
The customer’s first “communication” with your web service is an out-of-band
communication in which your customer does all the things that need to get done before any
data communication can happen. A typical activity sequence for this initial stage is shown
in Figure 1-2.

12 Chapter 1: Introduction to QBWC Programming
(c) 2009 Intuit Inc. All rights reserved.

Figure 1-2

How a User Gets Ready to Access Your Web Service

As shown in the figure, the user must first learn about your service and what it requires,
downloads and installs QBWC, subscribes to your service and obtains a password and a
QWC configuration file. The QWC file, when loaded into QBWC, automatically transfers
almost everything QBWC needs to contact your web service, such as user name, URLs, and
so forth. (See Chapter 4, “Building The QWC File for Your Users,” for details on
constructing the QWC file.)
The only thing NOT automatically loaded into QBWC is the user password from the web
service provider. For security reasons, the user needs to save this manually into QBWC,
where it is encrypted and stored.

The QBWC-to-Web Service Communication Universe 13
(c) 2009 Intuit Inc. All rights reserved.

Ongoing Communication Between QBWC and a Web Service
Figure 1-3 shows a high level view of the communication between a user’s local system
running QuickBooks/QuickBooks POS with QBWC talking to a web service over the
internet.

Figure 1-3

High-level communication diagram

QBWC uses the QWC file from each web service provider to locate that providers web
service and begin the communication sequence. A detailed view of this communication
sequence can be found in Chapter 2, “The QBWC Communication Model.” Your web
service must implement the SOAP-based interfaces listed in Chapter 2 and described in
detail in Chapter 10.
QBWC contacts the web service when your customer asks it to or at the regular intervals
scheduled by your customer. If your web service needs to do some work for the customer, it
responds with requests for QuickBooks or QB POS, which QBWC forwards to QuickBooks
or QB POS, then returns the responses to your web service. If the web service has no work
to be done at the time QBWC makes contact, then the communication simply stops.

What Will My Web Service Solution Look Like?
This document does not cover certain aspects of your total solution, such as getting
subscription requests from your customer and providing them with passwords, the
mechanism used to supply QWC files and so forth. It describes primarily those core pieces
of functionality you must provide:
•

The QWC file you provide to the customer that contains all the connection data

•

The web service QBWC callbacks you must implement in your web service

How to Build a QWC File
Each customer will have to have a separate QWC file with their unique username. The user
downloads this and opens it to automatically load all its data into QBWC. Instructions on
constructing this QWC file are provided in Chapter 4, “Building The QWC File for Your
Users.”

14 Chapter 1: Introduction to QBWC Programming
(c) 2009 Intuit Inc. All rights reserved.

How to Build QBWC Support into Your Web Service
To enable QBWC to work with your web service, you need only implement the following
SOAP interfaces
•

authenticate

•

clientVersion

•

closeConnection

•

connectionError

•

getLastError

•

receiveResponseXML

•

sendRequestXML

These callbacks are described in detail in Chapter 10, “QBWC Callback Web Method
Reference.” A detailed description of how they are used is provided in Chapter 2, “The
QBWC Communication Model.”

Are There Samples to Jumpstart My Work?
The QB SDK package provides two sample web services, one for QuickBooks, one for
QuickBooks POS, each with their own QWC file. These are located in the QB SDK
samples subdirectory \samples\qbdt\c-sharp\qbXML\WCWebService and in the QBPOS
SDK samples subdirectory \Samples\qbpos\c-sharp\qbposxml\QWCPOSWebService.
Each sample web service can be run locally on your system along with QBWC, that is, with
no certificates, to keep things simple. Directions on building and running the sample are
provided in the readme.html page for the samples.

Frequently Asked Questions
The rest of this chapter provides answers to several frequently asked questions.

What Platforms and Languages can I use in my Implementation?
The web service should be able to run on any platform that supports standard SOAP for
communication. Platforms that are known to work include Apache Tomcat (Axis)and ASP
(.Net).
Why Do I Need SOAP?
There are several technologies designed to allow dissimilar applications to talk to each
other. That is, you can write one side in C# on Windows XP and the other could be Cobol
on an IBM Mainframe (which is an extreme example, perhaps). A few years ago a
technology called Common Object Request Broker Architecture (CORBA) was popular,

Are There Samples to Jumpstart My Work? 15
(c) 2009 Intuit Inc. All rights reserved.

but SOAP (Simple Object Access Protocol) has emerged to grab greater mindshare.
Although if you like cheap jokes, you could argue that the advantages offered by each were
largely a wash.
The main point is that SOAP provides a way for data to flow between two disparate
systems. From the perspective of the remote system, it doesn’t matter what language or
technology you use to implement your web service, so long as this system is capable of
interpreting the object/message being passed via SOAP.

Which QuickBooks/QB POS Versions Support QBWC?
QBWC works with any QuickBooks or QB POS product that supports the QB SDK and
QBPOS SDK, respectively, except QuickBooks Online edition. However, older versions
may not support some of the newer SDK requests that newer QuickBooks or QB POS
versions support. QBWC does return QuickBooks version data to help you determine
whether your web service will work with the customer’s QuickBooks or not.

Can I Specify Which QuickBooks Editions Access My Service?
There is an  parameter in the QWC file that allows you to specify which
QuickBooks editions are supported by your web service. By default, all editions are
supported, even Simple Start editions. This default is different from the default behavior of
AuthFlags for QB SDK applications. For QB SDK applications the default AuthFlags
support is not for all QB editions, but only Enterprise, Premier, and Pro, in order to avoid
breaking existing applications that didn't know about Simple Start edition.
Since QBWC is a new product, it makes sense to require application developers to think
about Simple Start edition from the beginning. Accordingly, when you test your
application, and you use the default AuthFlags, you must test your application against
Simple Start edition, to make sure Simple Start provides the functionality your application
requires.
Here are the values you can supply for :
Table 1-1

Supporting QuickBooks Editions

QB Supported

AuthFlags Value

Support All (default)

0x0

SupportQBSimpleStart

0x1

SupportQBPro

0x2

SupportQBPremier

0x4

SupportQBEnterprise

0x8

If you want to support several editions but not all, you can AND the values for the editions
you want to support.

16 Chapter 1: Introduction to QBWC Programming
(c) 2009 Intuit Inc. All rights reserved.

Does My Web Service Need a Certificate to Access QBWC?
All production communication between web services and QBWC uses HTTPS. This means
SSL is required, which means you’ll need a X.509 certificate. This is a standard certificate
that you can obtain from companies (such as Verisign) that provide them.
Developing a Web Service Without Certificates
However, for development purposes only, you can bypass the certificate issue by using http
and specifying “localhost” in your QWC AppURL settings. This will allow you to run your
web service on your system and let it talk to the QBWC installation on your system. You
could also optionally use a domain name within your LAN to test against a server
somewhere in your LAN. For more details, see Chapter 4, “Building The QWC File for
Your Users.”
Alternatively, if you want to use a self-signed certificate for testing purposes only, you can
use the tool Microsoft provides for this on the Microsoft web site . Follow the
instructions at the Microsoft web site. Or, you could also use openssl to test against if you
happen to have cygwin installed. (Though the openssl instructions say it is for IIS 6.0, it
works fine with IIS 5.1.)

Where is the QBWC WSDL?
The QBWC WSDL is located at the IDN web site .

Is There a Limit to the Number of Messages I Send to QBWC?
There is no limit on the number of messages your web service sends to QuickBooks Web
Connector (QBWC). It depends on your application -- when in response to
receiveResponseXML() you send a return value of 100 (which means 100% completed)
then QBWC will stop calling sendRequestXML().

Why QBWC and Not a Simple Web Interface?
Some developers may wonder why we supply QBWC rather than providing a web
interface. This is a philosophical question that we’ll have to address in a more longwinded
way.
Once upon a time, Quickbooks started out with the premise of making an accounting
system for people who weren't accountants. The assumption is that the end users are experts
in their business, not ours. This remains our assumption. We can’t assume that our
customers are going to figure out all the technical and security issues that surround the
seemingly simple issue of providing an application that opens internet access to our
customer’s financial data. That access must be kept as secure as possible and it must keep
the business owner in charge of access.

Frequently Asked Questions 17
(c) 2009 Intuit Inc. All rights reserved.

In other words, it can be difficult for developers to handle all the server components and
security components necessary to be successful at a QBWC-centric web service, but we
feel that the difficulty is better on the developer side than pushing this difficulty off to the
end users. Anyone developing an application that opens financial data to direct internet
access should carefully consider the security implications.
If you (as the developer) understand your user community well enough to know that they
can manage these decisions, then this functionality would make a good value-add you can
develop. If you are considering this business opportunity, please make sure you cover the
following areas:
1. Your clients will have to allow external traffic through their firewall into their
QuickBooks/QuickBooks POS system.
2. The ISP hosting your client will have to allow this traffic through, not all ISP's allow
this. Make sure you charge enough for your product to recoup the investment you'll
have to make at installation time working with ISP technical support. In the end, some
of your clients may be forced to use a different ISP.
3. Your client will have to configure SSL servers, if they don't have an IT department,
they'll likely look to you for help. If they misconfigure, or forget to enable security,
their data will be transferred in the clear. If they don't understand this they will likely be
upset with you for not making this clear.
4. In order to contact their system, they will have to have updated DNS records. If they
don't have a permanent IP address, they'll have to have DDNS somewhere. They will
likely look to you for help on this.
5. Because this is financial data, the bad guys have an incentive to try to get in. Your
clients will need to keep up with security patches in all the middle wear. And they need
to have very good policies about not allowing Trojan software or viruses onto their
systems. And they need to understand Phishing and prepare their staff to recognize and
react appropriately when they face it.

18 Chapter 1: Introduction to QBWC Programming
(c) 2009 Intuit Inc. All rights reserved.

CHAPTER 2
THE QBWC COMMUNICATION MODEL

1
1

In QBWC-to-web service communication, the typical QB/QBPOS SDK application pattern
is turned a bit upside-down. In a typical QB/QBPOS SDK application, the application
contacts QuickBooks or QuickBooks POS when it needs access.
In QBWC-to-web service communication, it is QBWC that contacts the application (the
web service) to ask whether that application wants to access QuickBooks/QuickBooks
POS. The QuickBooks/QuickBooks POS user decides how often QBWC “polls” your web
service by using the scheduler feature inside QBWC. Figure 2-1 illustrates this
communication flow.

Figure 2-1

QBWC and Web Service Communication Flow

A Closer Look at the Communication Model
The communication flow overview shown in the following figures gives some pretty good
hints as to how your web service needs to be structured to talk to the Web Connector. The
Web Connector will be calling into your web service and that your web service will need to
supply certain callback methods that will be expected by the Web Connector in order to
support the communication flow. Your web service must implement all of the callbacks
shown in the figures. (For detailed descriptions and sample code for each callback, see
Chapter 10, “QBWC Callback Web Method Reference.”)

A Closer Look at the Communication Model
(c) 2009 Intuit Inc. All rights reserved.

19

To implement the callbacks in your web service, you’ll need a more precise picture of what
is transpiring within the QBWC-web service communication. So, take a look at the
following illustrations as well as the running commentary provided with each drawing.

Figure 2-2

clientVersion and authenticate callbacks

What Figure 2-2 shows is what happens when a user at the QBWC clicks the Update button
or when a scheduled Update for a web service occurs. Here is what happens:

20 Chapter 2: The QBWC Communication Model
(c) 2009 Intuit Inc. All rights reserved.

1. First, QBWC calls your clientVersion callback to let your web service know which
QBWC version is calling. The purpose of this is to let you warn your user or even stop
the update if your web service doesn’t support that QBWC version. Notice that if your
web service doesn’t have the optional clientVersion callback, QBWC proceeds to the
authenticate call. In fact, QBWC always proceeds to call authenticate unless it receives
a message string prefixed by the two characters “E:” or the two characters “O:” (O as in
Oscar, not zero).
You can append a string after the colon; for E: this would be an error string, for O: this
would be a QBWC version string, which is used to tell the user at the client end what
QBWC version your web service requires.
2. Next, QBWC calls your authenticate callback, supplying the username you provided
your user via the QWC file, as described in Chapter 4, “Building The QWC File for
Your Users.” QBWC also sends the password that you supplied to your user and which
the user has stored into QWBC.
Your return to the authenticate call will be a string array with a maximum of four
strings.
The first member of the array is a session token, which could be a GUID or anything
else that you want to use to identify the session. This token will be returned by QBWC
in subsequent callbacks in the session.
The second member of the string array can contain a variety of things.
a. If the username and password in the authenticate call is invalid, you would supply
the value “nvu”.
b. If on the other hand the user data is valid but you have no work to do for that user,
you would supply the value “none”.
c. If you do have work to do for the that user, you can supply the full pathname of the
company to be used in the current update.
d. If you want to use whatever QuickBooks company is currently open at the client
end, simply supply an empty string.
The optional third member of the string array contains the number of seconds to
wait before the next update. You would use this to in effect tell that QBWC client
not to bother you for a specified time.
The optional fourth member of the string array contains the number of seconds to
be used as the MinimumRunEveryNSeconds time for your web service, which tells
QBWC how frequently your web service needs to be contacted.
What happens when QBWC gets this string array? If the second member of the string array
contains “none” or “nvu”, QBWC will display a message, call closeConnection, and stop
the session.

A Closer Look at the Communication Model
(c) 2009 Intuit Inc. All rights reserved.

21

If the second member contains a string with any other value, including an empty string,
QBWC will use that string as the path to the company file and will attempt to open it; an
empty string means use the currently open company file.
If the connection attempt fails, QBWC calls connectionError, and uses the pathname string
returned from connectionError to retry the connection until the connectionError callback
tells it to stop.

Figure 2-3

sendRequestXML, getLastError, and getInteractiveURL

What Figure 2-3 shows is what happens if the clientVersion and authenticate calls
succeeded and resulted in further work. QBWC invokes OpenConnection and BeginSession
on the indicated company and calls your sendRequestXML callback.
3. QBWC invokes sendRequestXML once the connection and session with QB or QBPOS
is started. If your web service is a QB web service, the first time QBWC calls
sendRequestXML in the session, it fills the strHCPResponse parameter with the results
of a HostQuery, CompanyQuery, and PreferencesQuery, as this data can be useful for
your web service when it constructs requests. If your web service is a QBPOS web
service, the first time QBWC calls sendRequestXML it fills the strHCPResponse
parameter with the string “HOSTQUERY/COMPANYQUERY/PREFQUERY is
currently not supported in QBPOS.” For all subsequent invocations of
sendRequestXML during the session, strHCPResponse contains only an empty string,
for both QBPOS and for QB.
22 Chapter 2: The QBWC Communication Model
(c) 2009 Intuit Inc. All rights reserved.

4. If the return from sendRequestXML is not empty, QBWC passes the supplied string to
the QB or QBPOS request processor to be handled. The string must be a validly
constructed qbposXML or qbXML request message set
If the return from your sendRequestXML callback is an empty string, QBWC calls
getLastError to see whether your web service needs to:
a. Report an error, in which case an error string would be returned from your
getLastError callback
b. Wait a few seconds before calling sendXMLRequest again, in which case the string
“NoOp” would be returned.
c. Start interactive mode, in which case the string “Interactive mode” would be
returned.
5. As shown in Figure 2-3, if the string “Interactive mode” is returned at this point from
getLastError, QBWC calls getInteractiveURL and starts a web browser open to the
page specified in the return to this call.

Figure 2-4

QBWC callbacks for interactive mode

6. As hinted at in Figure 2-4, just because the web service wants interactive mode doesn’t
mean it will get it. QBWC must ask the user if they authorize interactive mode by
popping up a dialog. If the user responds with “no” or if the user is not there, then
QBWC calls the interactiveRejected callback to let the web service know about this.
Your callback does whatever you need it to do, but all you need to return is some sort of
message you want displayed to your user.
7. If the user does authorize interactive mode, then the user will be taken to your web
page and will be doing whatever supported activities are available at that page. You will
handle user input and respond by invoking docontrol and/or doquery as described in the
chapter “Interacting Directly with the Web Connector”.
8. While the user is doing this, or until there is a timeout because the user got tired and
went to lunch, QBWC will periodically call interactiveDone to see if you are finished.
A Closer Look at the Communication Model
(c) 2009 Intuit Inc. All rights reserved.

23

If you are finished or if you know that there is a timeout, return an empty string in the
callback to end the interactive mode session.

Figure 2-5

Finishing the communication

9. If there is no interactive mode, then the return from sendRequestXML contains qbXML
or qbposXML requests. QBWC hands this off to QB or QBPOS and once it has
responses, sends them to your web service by calling receiveResponseXML. The data
returned by QB or QBPOS in response to the incoming requests is supplied in the
QBWC receiveResponseXML, in the response parameter. Your callback returns a
negative integer if there are any errors, such as out of sequence calls due to network
problems. Otherwise, it returns a positive integer between 0 and 100, indicating the
percentage of work done up to that point, with a value of 100 meaning that the update
activity is finished. If there is work left, then QBWC calls sendRequestXML again to
allow your web service to continue its work.
10. If the return from receiveResponseXML is a negative integer, QBWC calls
getLastError to allow your web service to supply some message string to inform the
user. This message is displayed by QBWC and then QBWC invokes closeConnection
to end the session.
24 Chapter 2: The QBWC Communication Model
(c) 2009 Intuit Inc. All rights reserved.

11. If not called prior to this point by some error condition, once all update activity is
finished, as indicated by the web service’s return to the receiveResponseXML call, then
QBWC invokes closeConnection and ends the current update session.

A Closer Look at the Communication Model
(c) 2009 Intuit Inc. All rights reserved.

25

26 Chapter 2: The QBWC Communication Model
(c) 2009 Intuit Inc. All rights reserved.

CHAPTER 3
IMPLEMENTING A WEB SERVICE FOR QBWC

1
1

In general, there are two approaches to building SOAP web services and their clients (codefirst and WSDL-first), with a fair degree of religious argument for each approach, however
there is little dispute that when interoperability is important, a WSDL-first approach makes
the most sense.
In the case of the Web Connector, the Web Connector is acting as a SOAP client which was
written based on a canonical standard .NET web service’s WSDL, so we followed the
WSDL-first approach to building the client and as we went through the process of testing
with .NET and Java web services we found the WSDL-first approach to be the most
reliable method of ensuring that the web services we built to support the web connector
remain compatible with the web connector.
In fact, we spent quite a bit of time tracking down what appeared to be bugs in the web
connector (and were certainly less than graceful failures) that turned out to be caused by
web services that did not conform to the WSDL we expected! We therefore strongly
recommend a wsdl-first approach to developing a web service that works with the web
connector!

Generating and Implementing the Service Skeleton with .NET
The .NET framework SDK includes the wsdl.exe tool for generating web service skeleton
code or web service client proxy classes from a pre-existing WSDL, by default it will create
a client proxy class, but with the /server switch will cause it to instead generate a skeleton
class for use in a web service, we therefore start by generating the service skeleton, we’ll
use C# for our example, though the same principles apply for VB.NET, all that needs to
change is the /language flag to wsdl.exe.
Wsdl.exe /server /language:cs http://developer.intuit.com/uploadedFiles/Support/
QBWebConnectorSvc.wsdl
This will generate a file called QBWebConnectorSvc.cs containing an abstract class with
methods for each of the SOAP WebMethods that the web connector expects:
// This source code was auto-generated by wsdl, Version=1.1.4322.2032.
using System.Diagnostics;
using System.Xml.Serialization;
using System;
using System.Web.Services.Protocols;
using System.ComponentModel;
using System.Web.Services;
/// 

27
(c) 2009 Intuit Inc. All rights reserved.

[WebServiceBindingAttribute(Name="QBWebConnectorSvcSoap",
Namespace="http://developer.intuit.com/")]
public abstract class QBWebConnectorSvc : WebService {
/// 
[WebMethodAttribute()]
[SoapDocumentMethodAttribute("http://developer.intuit.com/authenticate",
RequestNamespace="http://developer.intuit.com/",
ResponseNamespace="http://developer.intuit.com/",
Use=Description.SoapBindingUse.Literal,
ParameterStyle=SoapParameterStyle.Wrapped)]
public abstract string[] authenticate(string strUserName,
string strPassword);
/// 
[WebMethodAttribute()]
[SoapDocumentMethodAttribute("http://developer.intuit.com/sendRequestXML",
RequestNamespace="http://developer.intuit.com/",
ResponseNamespace="http://developer.intuit.com/",
Use=Description.SoapBindingUse.Literal,
ParameterStyle=SoapParameterStyle.Wrapped)]
public abstract string sendRequestXML(string ticket,
string strHCPResponse,
string strCompanyFileName,
string qbXMLCountry,
int qbXMLMajorVers,
int qbXMLMinorVers);
/// 
[WebMethodAttribute()]

[SoapDocumentMethodAttribute("http://developer.intuit.com/
receiveResponseXML",
RequestNamespace="http://developer.intuit.com/",
ResponseNamespace="http://developer.intuit.com/",
Use=Description.SoapBindingUse.Literal,
ParameterStyle=SoapParameterStyle.Wrapped)]

public abstract int receiveResponseXML(string ticket, string response,
string hresult, string message);
/// 
[System.Web.Services.WebMethodAttribute()]
[SoapDocumentMethodAttribute("http://developer.intuit.com/connectionError",
RequestNamespace="http://developer.intuit.com/",
ResponseNamespace="http://developer.intuit.com/",
Use=Description.SoapBindingUse.Literal,
ParameterStyle=SoapParameterStyle.Wrapped)]

28 Chapter 3: Implementing a Web Service for QBWC
(c) 2009 Intuit Inc. All rights reserved.

public abstract string connectionError(string ticket, string hresult,
string message);
/// 
[WebMethodAttribute()]
[SoapDocumentMethodAttribute("http://developer.intuit.com/getLastError",
RequestNamespace="http://developer.intuit.com/",
ResponseNamespace="http://developer.intuit.com/",
Use=Description.SoapBindingUse.Literal,
ParameterStyle=SoapParameterStyle.Wrapped)]
public abstract string getLastError(string ticket);
/// 
[WebMethodAttribute()]
[SoapDocumentMethodAttribute("http://developer.intuit.com/closeConnection",
RequestNamespace="http://developer.intuit.com/",
ResponseNamespace="http://developer.intuit.com/",
Use=Description.SoapBindingUse.Literal,
ParameterStyle=SoapParameterStyle.Wrapped)]
public abstract string closeConnection(string ticket);
}

This file can then be added (Add>Add Existing Item) to a Web project in Visual Studio and
then we can add a new web service (Add>Add Web Service) to inherit from this class and
implement each of the interfaces defined by the parent class. Intellisense makes this quite
easy, as shown in Figure 3-1.

29
(c) 2009 Intuit Inc. All rights reserved.

Figure 3-1

Implementing the Web Service

The highlighted areas of Figure 3-1 represent changes made to the standard template
created by Visual Studio, in particular note that we must add the WebService and
WebServiceBinding attributes to the class (they are not inherited from the abstract base
30 Chapter 3: Implementing a Web Service for QBWC
(c) 2009 Intuit Inc. All rights reserved.

class and the Namespace is particularly important) and, similarly, we must add
[WebMethod] attributes to each of the web methods we define (again, they are
unfortunately not inherited from the base class. For absolute completeness we could also
copy over the SoapDocumentMethod attributes from the base class, but it seems as though
those are either properly inherited or the defaults are correct in .NET.

Generating and Implementing the Service Skeleton with Java and
Apache Axis
If you are not using .NET, the likely alternative is the Apache Axis web services
framework. Similar to the .NET framework’s wsdl.exe tool, Apache Axis includes the
wsdl2java tool for creating a complete java source framework to implement a web service
based on a WSDL. Again, by default WSDL2Java generates a Java Proxy class to
communicate with a web service implementing the given WSDL, but the -server-side and skeletonDeploy flags can be used to create the server-side framework, including an Axis
Web Services Deployment Descriptor (wsdd) file:
java org.apache.axis.wsdl.WSDL2Java-server-side-skeletonDeploy http://
developer.intuit.com/uploadedFiles/Support/QBWebConnectorSvc.wsdl
The result is a complete set of .java source files, of particular interest is the
QBWebConnectorSvcSoapImpl.java file, shown below, where we will implement the logic
for each of the six methods required by the web connector. The rest of the generated files
require no modification, unless you wish to change the package name from the default
com.intuit.developer they need only be compiled as part of the overall solution.
/**
* QBWebConnectorSvcSoapImpl.java
* This file was auto-generated from WSDL
* by the Apache Axis 1.2.1 Jun 14, 2005 (09:15:57 EDT) WSDL2Java emitter.
*/
package com.intuit.developer;
public class QBWebConnectorSvcSoapImpl implements
com.intuit.developer.QBWebConnectorSvcSoap{
public com.intuit.developer.ArrayOfString authenticate(
java.lang.String strUserName,
java.lang.String strPassword)
throws java.rmi.RemoteException {
return null;
}
public java.lang.String sendRequestXML(java.lang.String ticket,
java.lang.String strHCPResponse,
java.lang.String strCompanyFileName,
java.lang.String qbXMLCountry,

31
(c) 2009 Intuit Inc. All rights reserved.

int qbXMLMajorVers,
int qbXMLMinorVers)
throws java.rmi.RemoteException {
return null;
}
public int receiveResponseXML(java.lang.String ticket,
java.lang.String response,
java.lang.String hresult,
java.lang.String message)
throws java.rmi.RemoteException {
return -3;
}
public java.lang.String connectionError(java.lang.String ticket,
java.lang.String hresult,
java.lang.String message)
throws java.rmi.RemoteException {
return null;
}
public java.lang.String getLastError(java.lang.String ticket)
throws java.rmi.RemoteException {
return null;
}
public java.lang.String closeConnection(java.lang.String ticket)
throws java.rmi.RemoteException {
return null;
}
}

Unlike the .NET case, this is not an abstract class and we are free to simply write the
appropriate logic to implement each of the six methods directly in the
QBWebConnectorSvcSoapImpl.java file.
One interesting quirk here is that although both the .NET and Java services are generated
from the same source WSDL, there can be a subtle difference in the way the return values
are SOAP encoded - this is the reason for the