QuickBooks PHP Integrations using the QuickBooks Web Connector (traditional method)

See also: ConsoliBYTE QuickBooks PHP Integration Framework

You may also want to see the new OOP API method of integrating with the Web Connector

See here: Quick Start for the QuickBooks Web Connector

Your request and response functions are called by the framework to generate requests and handle responses from QuickBooks. So, you'll queue up some requests (i.e. add customer #15) and then when the Web Connector connects, your request function will get called and expect you to return a valid qbXML CustomerAddRq request for customer #15. After QuickBooks processes this, it will send back a response and your response handler will be called and expected to process the response (even if you just ignore the response and hope that all is OK).

The frameworks passes in a certain set of variables when it calls your request or response handler functions to help you build your request and process the response. The variables passed in are shown below, along with function signatures for reference.

function _your_request_function_name($requestID, $user, $action, $ID, $extra, &$err, $last_action_time, $last_actionident_time, $version, $locale)
{
  ...
  return $qbxml;  // return a valid qbXML request
  // return QUICKBOOKS_NOOP; // or return a NoOp to skip this request and process the next one instead
}

• string $requestID

You should include this in your qbXML request (it helps with debugging later).

• string $action

The QuickBooks action being performed. This corresponds to the $action parameter to the →enqueue() method. Typically, you'd use a QUICKBOOKS_*_* constant, such as QUICKBOOKS_ADD_CUSTOMER or QUICKBOOKS_QUERY_INVOICE, but you can use any string as long as it's been mapped correctly in your $map.

• mixed $ID

The unique identifier for the record. Generally you'd pass the primary key of the record you're dealing with to the →enqueue() method, and that primary key value will be passed back to you here. So for a customer, you'd probably pass in the customer ID value to →enqueue(), and it will be passed in as this parameter.

• array $extra

Any extra data you included with the queued item when you queued it up

• string $err

An error message, assign a value to $err if you want to report an error

• integer $last_action_time

A unix timestamp (seconds) indicating when the last action of this type was dequeued (i.e.: for CustomerAdd, the last time a customer was added, for CustomerQuery, the last time a CustomerQuery ran, etc.)

• integer $last_actionident_time

A unix timestamp (seconds) indicating when the combination of this action and ident was dequeued (i.e.: when the last time a CustomerQuery with ident of get-new-customers was dequeued)

• float $version

The max qbXML version your QuickBooks version supports

• string $locale

The locale of QuickBooks (i.e. “US”, “CA”, “UK”, etc.)

You should return a valid qbXML request string.

function _quickbooks_customer_add_response($requestID, $user, $action, $ID, $extra, &$err, $last_action_time, $last_actionident_time, $xml, $idents)
{
  ...
}

• string $requestID

The requestID you passed to QuickBooks previously

• string $action

The action that was performed

• mixed $ID

The unique identifier of the record

• $extra

• string $err

An error message, assign a valid to $err if you want to report an error

• integer $last_action_time

A unix timestamp (seconds) indicating when the last action of this type was dequeued (i.e.: for CustomerAdd, the last time a customer was added, for CustomerQuery, the last time a CustomerQuery ran, etc.)

• integer $last_actionident_time

A unix timestamp (seconds) indicating when the combination of this action and ident was dequeued (i.e.: when the last time a CustomerQuery with ident of get-new-customers was dequeued)

• string $xml

The complete qbXML response will be passed to your function here. This is a qbXML response from QuickBooks which you can then parse and do whatever you want with.

• array $idents

An array of identifiers that are contained in the qbXML response. Commonly used identifiers will be extracted and returned here. Commonly used identifers include:

• ListID
• EditSequence
• TxnID

There are actually two types of errors that can occur during QuickBooks integrations, but both can be handled gracefully using the same method with the Web Connector and our PHP framework. The two types of errors than can occur are:

1. Protocol level errors (you have a messed up XML request, PHP is throwing warnings/notices in your SOAP output, etc.)
2. Data logic errors (you tried to create a payment for $0.00, create an invoice for a customer that doesn't exist, etc.)

By default, any error that occurs will cause the Web Connector to stop processing requests and report the error. You'll write an error handler function for each error type you'd like to handle:

/** 
 * Try to handle an error 
 * 
 * @param string $requestID
 * @param string $user         This is the username of the connected Web Connector user
 * @param string $action       The action type that experienced an error (i.e. QUICKBOOKS_ADD_CUSTOMER, or QUICKBOOKS_QUERY_CUSTOMER, or etc.)
 * @param string $ID           The $ID value of the record that experienced an error (usually your primary key for this record)
 * @param array $extra 
 * @param string $err          If an error occurs **within the error handler**, put an error message here (i.e. if your error handler experienced an internal error), otherwise, leave this NULL
 * @param string $xml
 * @param string $errnum       The error number or error code which occurred
 * @param string $errmsg       The error message received from QuickBooks 
 * @return boolean             Return TRUE if the error was handled and you want to continue processing records, or FALSE otherwise
 */
function my_error_handler($requestID, $user, $action, $ID, $extra, &$err, $xml, $errnum, $errmsg)
{
    // ...
    // return true;     // return TRUE if you want the Web Connector to continue to process requests
    // return false;    // return FALSE if you want the Web Connector to stop processing requests and report the error
}

You can then register your error handler in the $errmap parameter to your QuickBooks_Server instance:

$errmap = array(
    // This is an array mapping the error number/code to the error handler function
    3070 => 'my_error_handler', 

    // You can also use static method error handlers if you don't like functions...
    // 3070 => 'MyStaticClass::myStaticMethod', 

    // ... or object instant error handlers.
    // 3070 => array( $MyObjectInstance, 'myMethod' ), 

    // You can also register a "catch-all" error handler to catch all errors:
    // '*' => 'my_catchall_error_handler', 
    );

The →enqueue() method is used with the QuickBooks Web Connector and a QuickBooks_Server component to queue up requests which need to be processed by the QuickBooks Web Connector/QuickBooks.

See these files in the .zip download also:

• docs/example_server.php
• docs/example_integration.php

The enqueue() method signature looks like this: →enqueue($action, $ident = null, $priority = 0, $extra = null, $user = null, $qbxml = null, $replace = true)

• $action

The type of action to queue up (i.e. QUICKBOOKS_ADD_CUSTOMER)

• $ident

The primary key of the record in your own database (i.e. the customer.id value in your own database)

• $priority

The priority of the request. When the Web Connector connects, it dequeues requests from highest to lowest priority (i.e. a queued up item with priority 100 runs before a queued up priority of 10, the default priority is 0)

This is useful when you want to ensure that one request runs before another. Example: Before you add an Invoice (InvoiceAddRq) you must ensure that the customer for the invoice gets added first (CustomerAddRq). Queue up your QUICKBOOKS_ADD_CUSTOMER request with a priority of 10, and your QUICKBOOKS_ADD_INVOICE request with a priority of 5.

• $extra

Any extra data you want to pass to the request handler function and response handler function (i.e. array( 'my', 'extra', 'data', 'here' ) ). This must be a serialize-able data type to be passed to the request/response handlers intact.

• $user

The username of the user to queue this up for (i.e. 'quickbooks', or whatever username you've used in your .QWC file). If you do not provide a username, the framework will use the first entry it finds in the quickbooks_queue SQL table. If you are using the framework with multiple usernames, you should always explicitly specify which username a request belongs to!

• $qbxml

You can pass a valid qbXML request here (used only internally, you probably won't use this)

• $replace

Pass in a TRUE if you want to replace any other queued up items with the same $action and $ident value, or FALSE to queue it up again anyway. The default is TRUE.

You can write your own custom authentication functions if you don't want to use the quickbooks_user SQL table to authenticate Web Connector users.

Register the function handler like this:

$handler_options = array(
	'authenticate_dsn' => 'function://your_function_name', 
	);

Your function should look like:

function your_function_name($username, $password, &$company_file, &$wait_before_next_update, &$min_run_every_n_seconds, $params)
{
	... do something here ...

	// If you wanted to set the company file path (so the Web Connector can run without 
	//  QuickBooks being open), you can set the by-reference $company_file_parameter:
	$company_file = 'C:/path/to/quickbooks/file.QBW';
	
	if ( they are a valid user )
	{
		// Valid username and password
		return true;
	}
	else
	{
		// Invalid username/password
		return false;
	}
}

You can see the raw SOAP XML in two ways:

1. Check your quickbooks_log table, it should log most outgoing/incoming XML messages
2. You can call your server like this:

$contents = $server->handle(true, true);

and then write $contents to a file opened in mode “a+” (make sure the file is writable)