The QuickBooks Integrator is a toolkit for QuickBooks developers that provides for quick and easy development of fully integrated QuickBooks solutions. It eliminates the complexity of developing integrated accounting solutions by providing easy-to-use components that facilitate tasks such as adding, updating or retrieving customer information, vendor information, employee information, transactions etc.

How it Works

The QuickBooks Integrator consists of easy-to-use components, suitable for use in client or server applications that need to interact with QuickBooks.

QuickBooks Integrator provides simple interfaces to the QuickBooks API. Internally, the package generates and parses XML documents and uses COM to exchange them with QuickBooks. The Integrator handles the details of the XML processing and COM interop, allowing you, the developer, to focus on your business requirements.

QuickBooks Integrator is built on top of the QBXML SDK provided within QuickBooks, and therefore requires QuickBooks 2002 or later. Additionally, the integrator is not supported by QuickBooks Basic; These components will only work with QuickBooks Pro or higher. Applications built with the QuickBooks Integrator will only work on machines with appropriate versions of QuickBooks installed.

The package has no dependencies other than QuickBooks 2002 Pro or better. End users do not need to download the integrator, the MSXML parser, or any other utilities to run applications built with the components.

How To Use The Package

Nearly all of the QuickBooks Integrator components represent a business object such as a customer, invoice, or bill, and can be used to store information and communicate with QuickBooks.

Different operations are supported for different components. Each object may be added to QuickBooks with Add, retrieved with Get, or deleted with Delete.

"Entity objects" are objects representing people or corporations with whom the QuickBooks user does business. The Integrator offers Customer, Vendor, and Employee objects. These objects may be retrieved by name with GetByName, and modified and updated with the Update method. Use caution when updating, however; in general only contact information such as the name and address may be updated. The description for each property specifies whether or not it may be updated.

Transaction objects represent common business transactions such as a Bill, an Invoice, a PurchaseOrder, etc. All transaction objects have an array of Items, used to list items bought or sold in the transaction, and many have an array of Expenses, used to itemize expenses that may be charged to expense account. Transaction objects may be added or retrieved, and may also be voided where appropriate with the Cancel method.

The ObjSearch component is used to query the QuickBooks database using a combination of query filters. See the documentation for ObjSearch for more information on how this is done.

The QuickBooks Connection

Each component may connect with QuickBooks in a variety of ways. By default, each component is configured to interactively connect to a copy of QuickBooks running on the same machine. However, a variety of QB connection properties may be set to customize the type of connection. QuickBooks Integrator can be configured to connect to QuickBooks even if the UI is not running, and can also be configured to share access with other applications and end-users, or to lock them out.

Developers can choose any name for their application, and applications certified by Intuit can be configured to provide a copy of their certificate to QuickBooks for verification. And, the components also support the QuickBooks API for error tracking and recovery, through the use of unique request IDs.

Please see the appropriate QBConnection properties (all prefixed with "QB") for more details.

About the Properties

Each component's properties are set to default values when the component is created. However, any communication with QuickBooks will reset all property values, excluding the QBConnection properties. All information returned in the QuickBooks response will be set in the component, and all information not returned will be reset to its default in the component.

So for example, to get information about a customer, the Get method of a Customer object should be used. Then each of the properties will contain appropriate information, or a default value if the information has not been specified.

Note that even Adding an object to QuickBooks will alter the state of the component. Defaults not set by the component may be set by QuickBooks, and QuickBooks will frequently fill out descriptions, compute totals, and so on. This is the same behavior as when new objects are added through the QuickBooks UI.

Every time QuickBooks returns data, the QBResponseAggregate will be populated with the XML data returned from QuickBooks. This is a convenient way to encapsulate and save all the relevant information concerning a QuickBooks object. This property may also be set, to initialize a component as if it had just been returned with QuickBooks.

Additional properties are available as special fields. In general, special fields are properties that are unusual and/or infrequently used. To keep the API simple, access to special fields is offered though the SetSpecialField and GetSpecialField methods.

About Reference Properties

Many properties are reference properties: They refer to entities or items that already exist in QuickBooks. For example, when you add an Invoice, you must specify the Customer being invoiced. QuickBooks will only allow customers that have been added to its database, so you must either ensure that the Customer has been added to QuickBooks, or add the customer yourself before adding the invoice.

All reference properties are represented by two properties: a Name and an Id. The properties are redundant, so whichever is known may be specified. Moreover, setting either will reset the other to an empty string, ensuring that there is never any conflict between the two.

Whenever data is returned from QuickBooks, both the Name and the Id will always be returned, and user application may read either or both. You should consider storing the Id rather than the Name: Unlike the Name it cannot ever be changed by QuickBooks users or other integrated applications, and will always be valid unless the object is deleted.

Items and Expenses

All transaction objects have item lines, and expense transactions have expense lines as well. These are used in the QuickBooks Integrator components in the same way that they are used in QuickBooks.

Item lines are used to record the purchase or sale of tangible items or services. In QuickBooks Integrator, item lines are represented by a collection of array properties. The ItemCount property controls the size of each array, and the Item reference property (i.e., ItemId/ItemName) refers to each item. The quantity is given by ItemQuantity, the total is given by ItemAmount, and the unit cost or rate is given by ItemCost (payment transactions) or ItemRate (transactions with customers).

Other optional properties may be present as well; the list of properties varies slightly with different components, corresponding to the QuickBooks UI.

Example:

Transaction1.ItemCount = 2 Transaction1.ItemName(0) = "Wood Door:Exterior" 'Transaction1.ItemCost(0) = 5000 Transaction1.ItemQuantity(0) = 4 'Transaction1.ItemAmount(0) = 20000 'Transaction1.ItemDescription(0) = "Default" Transaction1.ItemName(1) = "Cabinets - Custom" Transaction1.ItemAmount(1) = 16400 Transaction1.Add()

Expense lines are used to charge an expense to an expense account. Common examples might include rent, gasoline, freight, etc. The number of expenses is controlled with ExpenseCount, and the ExpenseAccount (Name/Id) and ExpenseAmount should be specified for each expense. ExpenseClass (Name/Id), ExpenseCustomer* (Name/Id), and ExpenseMemo are optional.

Example:

Transaction1.ExpenseCount = 1 Transaction1.ExpenseAccountName = "Freight & Delivery" Transaction1.ExpenseAmount = "9500"

All transactions must have at least one item and/or expense line.

More Information

This is just a brief overview of the components included. Please download the fully functional trials available on this website for more information.