Communicating with QuickBooks

If you walked through the demonstration of basic steps, you saw that the SDKTestPlus3 application was able to communicate, via the QuickBooks Desktop SDK, with a running instance of QuickBooks, and exchanged messages that requested and received some QuickBooks data. This page looks in more detail at the mechanisms that enable this communication, which are the mechanisms that your own applications will use.

For developers building applications that integrate with QuickBooks Desktop editions, there are two entities to be aware of:

• The QuickBooks request processor, which is a DLL that is installed during a QuickBooks installation and runs in the same process as QuickBooks. The request processor implements a COM interface that allows applications to open connections to QuickBooks and set up working sessions. Applications communicate with QuickBooks by calling the SDK’s methods to open connections, begin sessions, and send requests to QuickBooks. The request processor validates the messages, hands off the requests to QuickBooks and then returns the QuickBooks responses to the originating application.

A request processor session gives access to one QuickBooks company file. The request processor is available even when QuickBooks is not running or a when working session for a specific company file has not yet been established, which gives applications possibilities such as connecting to QuickBooks when the UI is not running and specifying a company file at they time they open a session.

• The QuickBooks Desktop SDK is a developer-installed package that contains the software libraries, utilities, samples, and documentation that support development of applications that communicate with the request processor and integrate with QuickBooks.

Notice that communication between applications and the request processor is via a special set of XML known as qbXML, and the SDK provides applications with two different ways to work with qbXML. Applications can either write their own qbXML messages and send them to the request processor, or make use of the QuickBooks foundation classes (QBFC) to build request messages and process response messages. Examples of both techniques are given throughout this documentation, enabling you to choose between them.

In the demonstration of basic steps, you saw that the SDKTestPlus3 application first performed some initialization steps (opening a connection, beginning a session, obtaining authorization), and then performed the actual work by sending a request for information and receiving a response that contained the requested information. This pattern–sending requests and receiving responses–is used in all of your application’s data interactions with QuickBooks, including adding, modifying, and deleting data, querying QuickBooks, and running QuickBooks reports.

1. The application sends a request to QuickBooks Desktop, asking it to perform a specified operation and supplying it with any necessary data. Examples of requests would be adding an invoice, modifying information about an employee, or querying for unpaid bills. Note that it is possible to combine multiple request messages into a single request message set.
2. The application receives a response from QuickBooks Desktop. QuickBooks Desktop sends a response back to the application for each received request. If multiple requests are sent in a request message set, the response will be a response message set with a separate response for each request in the request message set.

The SDK provides two methods of preparing qbXML messages–writing code that assembles messages or passing the message values to the QBFC foundation classes, which then assemble the actual messages for you-but either way the content of the messages sent to QuickBooks will be qbXML.

Most of the examples on this page show code that works directly with qbXML. If you’re using the QBFC class, you’ll construct the messages with different code, but the actual messages sent and received will be identical.

qbXML messages are structured according to standard XML conventions, using the following terms:

• The smallest part of a message is an element. Elements are name/value pairs, demarcated by tags. Sometimes they have associated attributes.
• Message elements are often grouped into meaningful containers called aggregates. A message is itself a top-level aggregate.
• The names of qbXML message are composed of the QuickBooks objects they operate on, the operations they perform, and a suffix. Request messages have the suffix Rq, and response messages have the suffix Rs. AccountAddRq, therefore is a request to add an account with the data contained in the request, AccountAddRs is the expected response.

In qbXML, statements for elements and aggregates:

• begin with their names in angled brackets: <AccountAdd>
• and end with the name, preceded by a backslash, also in angled brackets: </AccountAdd>

For example, the following is an AccountAddRq, which as its name indicates, is a request to add an account.

1
2
3
4
5
6
7

 <AccountAddRq requestID=”2”>
    <AccountAdd>
       <Name>Checking Account</Name>
       <AccountType>Bank</AccountType>
       <BankNumber>0350039560</BankNumber>
    </AccountAdd>
 </AccountAddRq>

In this example, AccountAdd is an aggregate that contains the Name, AccountType, and BankNumber elements. AccountAddRq is also an aggregate and is often referred to as the message aggregate, since it comprises the entire message, including its request ID attribute.