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.

QuickBooks request processor

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

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.
qbdesktop/docs/develop/sdk_and_request_processor.png

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.

Note

Note

The request processor also supplies an API that allows event subscriptions, which allow for communications between application and QuickBooks without a QuickBooks session. For more information, see Subscribing to events and processing event notifications.

Request/response communications model

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.

qbdesktop/docs/develop/sdk_request_and_response.png
  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.

Messages are qbXML

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 Message structure

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

In qbXML, statements for elements and aggregates:

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.