Introduction

Welcome to QuickBooks Integrator, a comprehensive suite of Internet-enabled components for QuickBooks (QBXML) Integration. Includes easy-to-use components for accessing QuickBooks constructs and automating accounting tasks. Supports connectivity with all Windows based QuickBooks applications.

Included Components

Account	The Account component manages QuickBooks accounts.
Address	An Address represents a geographical address.
AdjustInventory	The AdjustInventory component is used to adjust your inventory.
Bill	A Bill indicates that the QuickBooks company owes money to a VENDOR . A Bill is the opposite of a VENDORCREDIT .
BillPayment	The BILLPAYMENT component provides the functionality found in the Pay Bills form in the QuickBooks UI.
CCCharge	A CCCharge is used to record point-of-receipt credit card charges.
CCCredit	A CCCredit is used to record credit card refunds.
CertMgr	The CertMgr component is used to manage the digital certificates installed on a system.
Check	A Check is used to record point-of-receipt payments.
Company	The Company component is used to retrieve information about the QuickBooks company.
CreditMemo	A CreditMemo indicates that a CUSTOMER is owed money by the QuickBooks company. A CreditMemo is the opposite of an INVOICE .
Customer	A Customer is anyone who buys goods or services from the QuickBooks company.
Deposit	A Deposit is used to record and query deposits to an account.
Employee	An Employee is anyone who works for the QuickBooks company.
Estimate	An Estimate is a description of a sale that the company proposes to make to a CUSTOMER .
Invoice	An Invoice indicates that a CUSTOMER owes money to the QuickBooks company. An Invoice is the opposite of a CREDITMEMO .
Item	The Item component is used to add any of eight types of items to QuickBooks's item list. It may also get item data, and in some cases, may modify it as well.
ItemReceipt	the ITEMRECEIPT component allows you to add and edit an item receipt transaction, which is a transaction entered in QuickBooks when a shipment is received from a vendor.
JournalEntry	A JournalEntry represents a general journal entry made directly in the company's chart of accounts.
LineItemGroups	Generates a group aggregate for use in another component's Update request.
ObjSearch	ObjSearch is used to search the QuickBooks database.
PriceLevel	A PriceLevel is used to specify custom pricing.
PurchaseOrder	A PurchaseOrder is used to order goods from a VENDOR .
QBConnector	The QBCONNECTOR component is a utility that allows you to connect your QuickBooks Integrator applications to remote QuickBooks instances.
QBLists	Used to add various List Items.
QBObject	A generic QuickBooks object, allowing users to extend the product's functionality.
QBWCServer	The QBWCServer component is used to communicate with QuickBooks Web Connector from your application.
ReceivePayment	The ReceivePayment component is used to receive payments from customers.
SalesOrder	A SalesOrder is used in place of an INVOICE when not all goods have been shipped.
SalesReceipt	A SalesReceipt is used to record point-of-sale payments.
StatementCharge	The STATEMENTCHARGE component allows you to add and modify individual charges on a customer's statement.
TimeTracking	The TimeTracking component is used to track employees' time.
Vendor	A Vendor is anyone from whom the QuickBooks company buys goods or services.
VendorCredit	A VendorCredit indicates that the QuickBooks company is owed money by a VENDOR . A VendorCredit is the opposite of a BILL .

Additional Information

You will always find the latest information about QuickBooks Integrator at our web site: www.4dpayments.com. We offer free, fully-functional 30-day trials for all of our products, and our technical support staff are happy to answer any questions you may have during your evaluation.

Please direct all technical questions to support@4dpayments.com. To help support technicians assist you as quickly as possible, please provide an detailed and accurate description of your problem, the results you expected, and the results that you received while using our product. For questions about licensing and pricing, and all other general inquiries, please contact sales@4dpayments.com.

Thank You!

Thank you for choosing QuickBooks Integrator for your development needs. We realize that you have a choice among development tools, and that by choosing us you are counting on us to be a key component in your business. We work around the clock to provide you with ongoing enhancements, support, and innovative products; and we will always do our best to exceed your expectations!

Introduction to /n software QuickBooks Integrator

/n software QuickBooks Integrator consists of thirty-two easy-to-use components, suitable for use in client or server applications that need to interact with QuickBooks.

/n software 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. /n software QuickBooks Integrator handles the details of the XML processing and COM interop, allowing you, the developer, to focus on your business requirements.

/n software QuickBooks Integrator is built on top of the QBXML SDK provided within QuickBooks, and therefore requires QuickBooks 2002 or later. Applications built with /n software 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. (Certain functionality requires later editions of QuickBooks.) End users do not need to download the SDK, the MSXML parser, or any other utilities to run applications built with /n software QuickBooks Integrator.

Note for Silverlight Usage:

Normally you would make a connection to QuickBooks by using the qbconnector.exe included in the toolkit. The qbconnector.exe would run on the machine where QuickBooks is installed. You would then set QBConnectionString to configure the component to connect to the qbconnector.exe.

However, if your application is a Silverlight 4 application running out of browser with elevated permissions you can connect directly to QuickBooks without using the qbconnector.exe. In this case the component must be used in a background thread of the application or be used with the BeginXXX and EndXXX method calls.

How To Use The Package

Nearly all of the 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. These are accessed through the Customer, Vendor, and Employee components. 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.

Note for Silverlight Usage:

Normally you would make a connection to QuickBooks by using the qbconnector.exe included in the toolkit. The qbconnector.exe would run on the machine where QuickBooks is installed. You would then set QBConnectionString to configure the component to connect to the qbconnector.exe.

However, if your application is a Silverlight 4 application running out of browser with elevated permissions you can connect directly to QuickBooks without using the qbconnector.exe. In this case the component must be used in a background thread of the application or be used with the BeginXXX and EndXXX method calls.

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. The components 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. Furthermore, the components can also be configured to connect to QuickBooks behind the scenes, or to connect and disconnect on demand. See the help for the QBConnectionString property for details on how to connect using the component. The sections below discuss various connection options.

QuickBooks Gateway (aka Remote Connector for QuickBooks)

Remote Connector for QuickBooks is a distributable 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).

The Remote Connector application 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. Remote Connector then communicates with QuickBooks via COM, and returns the QuickBooks response (or an error message) in the HTTP reply.

Remote Connector for QuickBooks is distributed with the /n software QuickBooks Integrator and it will be installed on your machine automatically when you install the toolkit.

More details on the operation of this application can be found on https://4dpayments.com/quickbooks-gateway/.

Accessing the Remote Connector for QuickBooks with your application

To use Remote Connector for QuickBooks you will need to set the QBConnectionString property for any instance of a control that needs to connect: controlname.QBConnectionString = "URL='http://www.foo.com:8167' User='Foo' Password='Bar'"

This will instruct the control to direct its request to Remote Connector instead of the local instance of Quickbooks.

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

The QBConnector Component

The QBConnector object in the /n software Quickbooks Integrator toolkit can be used to build a Remote Connector application that is integrated more closely with your application, includes your own graphical user-interface, or is branded in your name.

Connection to Remote Connector for QuickBooks using SSL

If you have configured SSL in Remote Connector for QuickBooks, you will need to export your public key certificate for any connecting applications. You should add the following code (or something similar) in your application: controlname.QBConnectionString = "URL='https://www.foo.com:8167' User='Foo' Password='Bar'" controlname.Config("SSLAcceptServerCertFile=c:\exported_cert.cer")

You may also use the SSLServerAuthentication event of the component to accept the server certificate. Note that if you use SSL, all clients must use SSL (HTTPS) to make connections.

Note for Silverlight Usage:

Normally you would make a connection to QuickBooks by using the qbconnector.exe included in the toolkit. The qbconnector.exe would run on the machine where QuickBooks is installed. You would then set QBConnectionString to configure the component to connect to the qbconnector.exe.

However, if your application is a Silverlight 4 application running out of browser with elevated permissions you can connect directly to QuickBooks without using the qbconnector.exe. In this case the component must be used in a background thread of the application or be used with the BeginXXX and EndXXX method calls.

About The Properties

Each component's properties is 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 Config method. 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

Items and Expenses

All transaction objects have item lines, and expense transactions have expense lines as well. These are used 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. 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" 'must be defined in company file! 'Transaction1.ItemCost(0) = "50.00" 'assign or use QB default Transaction1.ItemQuantity(0) = 4 'if not assigned, assumed to be 1 'Transaction1.ItemAmount(0) = "200.00" 'this will be calculated by QuickBooks 'Transaction1.ItemDescription(0) = "Default" 'may be assigned by QuickBooks Transaction1.ItemName(1) = "Cabinets - Custom" Transaction1.ItemAmount(1) = "164.00" 'simply assign the total amount 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 = "95.00"

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

Required Properties

When adding a new object to QuickBooks, the following properties are minimally required. Starred properties are reference properties, and either the corresponding Name or Id must be set.

Items refers to the collection of Item array properties. ItemCount must be set to a nonzero value, and Item* or ItemGroup* must be set. Expenses refers to the collection of Expense array properties. ExpenseAccount* and ExpenseAmount must be set.

Account	AccountName, AccountType
Bill	Vendor*, TransactionDate, Items or Expenses
CCCharge	Account*, Payee*, TransactionDate, Items or Expenses
CCCredit	Account*, Payee*, TransactionDate, Items or Expenses
Check	Account*, Payee*, TransactionDate, Items or Expenses
CreditMemo	Customer*, Items
Customer	CustomerName
Employee	EmployeeName
Estimate	Customer*, Items
Invoice	Customer*, Items
Item	Varies; see documentation for details.
JournalEntry	DebitLines, CreditLines
PurchaseOrder	Items
ReceivePayment	Customer*
SalesOrder	Customer*, Items
SalesReceipt	Items
TimeTracking	Employee*, Duration
Vendor	VendorName
VendorCredit	Vendor*, TransactionDate, Items or Expenses

Stars indicate reference properties. Either the Name or Id may be specified. Requirements for other methods are the same across the package. See the method documentation for further details.

Usage in 64-bit environments

Because the /n software QuickBooks Integrator communicates directly with Quickbooks and Quickbooks does not currently have native 64-bit support, applications that communicate with Quickbooks must be run in 32-bit mode when running on a 64-bit architecture.

On 64-bit machines, you will either need to use the QBConnector.exe provided with the installation to bridge the connection to Quickbooks via a 32-bit application, or you will need to target the X86 processor when compiling your application to create a 32-bit application.