PHP DevKit for QuickBooks - Documentation

From ConsoliBYTE Wiki
Jump to: navigation, search

Request and Response Functions for the 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.

Request functions

 
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 $user

The username of the Web Connector user that's asking for this request.

  • 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.

Response functions

 
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 $user

The username of the Web Connector user that's asking for this request.

  • 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