QuickBooks Web Connector Overview

From ConsoliBYTE Wiki
Jump to: navigation, search

Contents

QuickBooks Web Connector Overview

About the QuickBooks Web Connector

The QuickBooks Web Connector is a software application that runs on Microsoft Windows that enables specially designed web-based applications to exchange data with QuickBooks products.

The Web Connector offers and automated way to transfer data between web applications (shopping carts, CMS, etc.) and QuickBooks. It supports two-way communication (i.e. moving data from the web to QuickBooks, and moving data from QuickBooks to the web) and is the recommended way to connect websites to QuickBooks (vs. IIF files or CSV/Excel imports/exports).

Open-Source Web Connector Frameworks

The frameworks listed below are open-source implementations of the Web Connector protocol which may be helpful if you're creating your own code to talk to QuickBooks or need a starting point:

  1. QuickBooks PHP Framework
  2. QuickBooks Visual Basic .NET Framework

Technical Overview of the Web Connector

The Web Connector is really just a proxy or a relay that sits between QuickBooks and your own application. The Web Connector itself doesn't really contain any QuickBooks related logic or know how to tell QuickBooks to do anything, it's just a helper application.

The Web Connector is the only Intuit-supported solution to integrating with QuickBooks from a web application. Basically, you build a SOAP server / Web Service which speaks a specific set of methods. The Web Connector then is installed on the machine running QuickBooks, and polls your web service asking “Hey, got anything for me to do?” Your web service can then respond with qbXML requests (examples of qbXML here: [QuickBooks qbXML Examples][1]) which tell the Web Connector “Add this customer: …” or “Send me invoices which match: …” or etc. etc. etc. The Web Connector then relays those requests to QuickBooks, QuickBooks processes them, and the response is relayed back to your web service. Your web service might then process the response somehow, and then send the next request over to the Web Connector. This can continue in a loop for as long as you like, continuing to send requests to QuickBooks and receiving the responses.

 
COMPUTER 1:
 - Your web server (Apache + PHP, Tomcat + Java, IIS + ASP .NET, etc.)
 - A web service (SOAP server) that you create
 
COMPUTER 2:
 - QuickBooks
 - QuickBooks Web Connector
 

The Web Connector is installed on the machine running QuickBooks. You tell it where it can reach your web application and it then goes through a process as follows when you tell it to start:

 
 // Web Connector asks your SOAP service to authenticate
 Web Connector => SOAP server:   authenticate with the username "xyz" and the password "bla" (authenticate)
     If authentication is successful, the SOAP server returns a ticket value and the process continues
 
 // Web Connector asks for something to do
 Web Connector => SOAP server:   hey SOAP server, what do you have for me to do?  (sendRequestXML)
     SOAP server generates and returns a qbXML request
 
 // Web Connector relays that request to QuickBooks, and receives a response from QuickBooks
 Web Connector => QuickBooks:    hey QuickBooks, the SOAP server gave me this request, can you please process it? 
     QuickBooks processes the request, and returns a response to the Web Connector
 
 // Web Connector relays the response from QuickBooks back to the SOAP server
 Web Connector => SOAP server:   hey SOAP server, here is the response for that last request from QuickBooks (receiveResponseXML)
     SOAP server processes the response, handling any errors and doing whatever with the response
     SOAP server returns a percentage done, if it's less than 100%, this process continues... 
 
 // The process starts over, with the Web Connector asking the SOAP server for the next request... 
 Web Connector => SOAP server:   hey SOAP server, what else do you have for me to do? (sendRequestXML)
     SOAP server generates and returns a qbXML request 
 
 ... and so on and so forth ...
 

All of the logic is held within your application. Your application is responsible for building qbXML requests, and handling the qbXML responses that QuickBooks sends back.

The transport between the Web Connector and your application happens over a secure HTTPS connection via the SOAP/Web Service protocol. Thus, the Web Connector can talk to web applications programmed in any programming language that can be handle requests over HTTPS, including PHP, Perl, CGI, .NET, Ruby, Python, Java, etc.

The transport between the Web Connector and QuickBooks is via COM, which requires that the Web Connector has direct access (either local file or over a shared network drive) to the QuickBooks company file (.QBW file).

Web Connector Incompatibilities

The Web Connector has been reported as incompatible with *lighttpd* version 1.4. If you're getting “417: Expectation Failed.” messages or other strange HTTP messages from lighttpd v1.4, you should consider upgrading to v1.5.

It should also be noted that QBWC v2 and Quickbooks Point of Sale do not get along. If you are trying to integrate this framework with POS it is advised to utilize the QBWC v1.5 as opposed to 2+ (Note: some framework functions may not work or may not work correctly with version 1.5 - This is a flaw in the QBWC software -)

Developing a Web Service for the Web Connector

The basic process:

  1. string clientVersion()

The Web Connector connects to your SOAP server, sending clientVersion(), you can ignore this call for now.

  1. string serverVersion()

The Web Connector connects to your SOAP server, sending serverVersion(), you can ignore this call for now.

3. array authenticate(string strUserName, string strPassword)

The Web Connector connects to your SOAP server, sending authenticate().

You should check the username and password sent to ensure the username and password are valid (you should be storing a list of valid usernames/passwords somewhere on your server). If the username and password are invalid, send back an array:

array(

 ,       // a session ID/ticket would normally go here, but since it's not a valid login, we don't have one
 'nvu',    // for non-valid username

) If the username and password are valid, you need to generate a session ID (a “ticket”) and store this ticket in your database. Every subsequent call to the Web Connector methods will include this ticket string, and you'll check to ensure the ticket is valid on every subsequent call.

You should then check to see if there is anything to do. You should be maintaining a queue of things to do within your SOAP server. If there is *nothing* to do, you should return this array:

array(

 'a valid ticket string goes here',    // send the session ID/ticket here
 'none',                               // indicates that the login was valid, but there's nothing to do

) If there is *something* to do, then you should return this array:

array(

 'a valid ticket string goes here',   // send the session ID/ticket here
 'C:/path/to/your/company/file.QBW',  // you can send *either* an empty string to use the currently open QuickBooks company file, or specify a specific company file to use by sending the full path to that company file
 '10',                                // this is *optional*, you may send an empty string or an integer indicating the number of minutes to wait before doing the next update
 '120',                               // this is *optional*, you may send an empty string or an integer indicating the minimum number of seconds the web connector should allow between update sessions

) Here is what the actual SOAP XML requests and responses should look like:

Example SOAP Request and SOAP Response for authenticate() 4. string sendRequestXML(string ticket, string strHCPResponse, string strCompanyFileName, string qbXMLCountry, int qbXMLMajorVers, int qbXMLMinorVer)

If the previous call to authenticate() succeeded *and* there were things to do in the queue, the Web Connector will call this method. You will receive as parameters:

 string ticket                The ticket string you returned from authenticate(). You should use this to check and ensure the session is still valid. 
 
 string strHCPResponse        This will be a big XML document with all sorts of information about your company file
 string strCompanyFileName    The full file path of the company, i.e. C:/path/to/company/file.QBW
 string qbXMLCountry 

 integer qbXMLMajorVers       Maximum qbXML major version supported, example: If QuickBooks supports qbXML version 6.1, this will be 6. 
 integer qbXMLMinorVers       Maximum qbXML minor version supported, example: If QuickBooks supports qbXML version 6.1, this will be 1.

You should check your internal queue of things to do, and pull the next item out of the queue. You should return a valid qbXML XML request for that queue item as a string.

Here is what the actual SOAP XML requests and responses should look like:

Example SOAP Request and SOAP Response for sendRequestXML() 5. integer receiveResponseXML(string ticket, string response, string hresult, string message)

The Web Connector will now pass you a qbXML response to the last qbXML request that was issued.

You should do whatever necessary with the qbXML response, and then return an integer indicating the progress made so far during this session.

If an error has occurred within the SOAP server, return a -1. The Web Connector will next call connectionError().

If there are no more items in the queue, return a 100 (100% finished). The Web Connector will next call closeConnection().

If there are more items in the queue, you can return any number 0 to 99 inclusive which indicates the percentage done this session is (returning 65 indicates 65% done, etc.). The Web Connector will next call sendRequestXML(), so that you can send the next request for the next item in the queue.

Here is what the actual SOAP XML requests and responses should look like:

Example SOAP Request and SOAP Response for receiveResponseXML() 6. string connectionError(string ticket, string hresult, string message)

This method will *only* get called if some sort of error occurs.

Here is what the actual SOAP XML requests and responses should look like:

Example SOAP Request and SOAP Response for connectionError() 7. string getLastError(string ticket)

This method will *only* get called if some sort of error occurs.

Here is what the actual SOAP XML requests and responses should look like:

Example SOAP Request and SOAP Response for getLastError() 8. string closeConnection(string ticket)

Once this method is called, the session has ended and the Web Connector will stop making requests. This will always be the *last* SOAP service call that gets issued.

Here is what the actual SOAP XML requests and responses should look like:

Example SOAP Request and SOAP Response for closeConnection() Pseudocode for the SOAP Web Service

Pseudocode is here:

For some additional tips, see: http://idnforums.intuit.com/messageview.aspx?catid=56&threadid=10753&enterthread=y

Where is the Web Connector WSDL File?

You can find it here: http://developer.intuit.com/uploadedFiles/Support/QBWebConnectorSvc.wsdl.

Do You Really Need an SSL Certificate?

Maybe. You don't technically need one, but it's a really good idea.

If you don't have a valid SSL certificate, you'll probably get an error like this:

QBWC 1048: QuickBooks web Connector could not verify the web application server certificate.

To deploy the Web Connector on a production site, you really should have a real SSL certificate issued by a trusted third-party vendor. Not using an SSL certificate or using a self-signed certificate means your data could possibly be insecure/intercepted by a third-party. You probably don't want a third-party to have access to all of your financial data.

”Wildcard SSL certificates” DO work.

You can get away without having a third-party SSL certificate by:

  • Not using an SSL certificate at all and using a domain name which contains the string 'localhost' in it: If you edit your 'hosts' file on Windows, you can tell Windows that, for instance, 'localhost2' points to the IP address of your server. As long as the Web Connector sees that your domain name has the string 'localhost' in it, then it will not require an SSL certificate. Do not use just 'localhost', use something like 'localhost2' or 'localhost-really-this-other-machine'. The name 'localhost' is reserved and always points back to the machine itself.

OR

  • Using a self-signed SSL certificate, and importing the certificate and CA certificate. See here: Self-Signed Certificates with the Web Connector

OR

  • Pointing your .QWC file to any httpS:// website at all, loading your .QWC file into the Web Connector, and then editing the Windows registry to change the URL to your actual URL.

Example .QWC File

QuickBooks Web Connector .QWC files are actually just plain text files (XML) with a .QWC file extension. You can edit .QWC files using Windows Notepad or any other text editor.

 
<?xml version="1.0"?>
<QBWCXML>
  <AppName>QuickBooks Integrator</AppName>
  <AppID></AppID>
  <AppURL>https://secure.domain.com/quickbooks/server.php</AppURL>
  <AppDescription></AppDescription>
  <AppSupport>http://www.domain.com/quickbooks/support.php</AppSupport>
  <UserName>username</UserName>
  <OwnerID>{90A44FB7-33D9-4815-AC85-AC86A7E7D1EB}</OwnerID>
  <FileID>{57F3B9B6-86F1-4FCC-B1FF-967DE1813D20}</FileID>
  <QBType>QBFS</QBType>
  <Scheduler>
    <RunEveryNMinutes>2</RunEveryNMinutes>
  </Scheduler>
  <IsReadOnly>false</IsReadOnly>
</QBWCXML>
 

.QWC File Notes

<AppName> This is displayed to the user in the Web Connector GUI <AppSupport>…</AppSupport> Must contain a valid URL to a valid page which returns a 200 OK HTTP response when visited. <AppURL>…</AppURL> Must contain a valid URL to your SOAP server, https://... if it's remote, http://localhost/… if it's local. <FileID>…</FileID> You can make this up as long as it follows the GUID format (uppercase HEX chars only!): {6904A826-7368-11DC-8317-F7AD55D89593}. It has something to do with DataExt elements; most simple integrations can just make this up. <OwnerID>…</OwnerID> Same as above <QBType>…</QBType> Specifies the type of Quickbooks you want to connect to with the web connector (ie “QBFS” or “QBPOS”) <Scheduler>…</Scheduler> This is an optional element, use this to schedule the Web Connector to run every so often automatically <IsReadOnly>…</IsReadOnly> If you set this to true, your application will not be able to add, modify, or delete data in QuickBooks. See Also

  • Using a self-signed certificate and importing the certificate and CA certificate.

Can the Web Connector exchange data if QuickBooks is *not* open?

Yes, the Web Connector *can* exchange data when QuickBooks is not open if:

When you initially install the application, you tell it to allow access even if QuickBooks is not open *and* For QuickBooks Pro, Premier, or Enterprise: You specify the full path to your company file (e.g.: C:/path/to/company/file.QBW) in the response from the authenticate() web service method. For QuickBooks Point-of-Sale: You must specify the connection string (e.g.: Computer Name=qbposserver;Company Data=My Company;Version=9) in the response from the authenticate() web service method. If you don't know this, the “POS SDK Test” utility included with the QuickBooks POS SDK can generate this for you. Note that the above comments apply only after you've initially set up the connection. The very first time you add your .QWC file to QuickBooks, you MUST have QuickBooks open.

Setting the Web Connector to use VERBOSE logging mode

You can do this by:

  • Exit the Web Connector
  • Running regedit (Start > Run > regedit.exe)
  • Navigating to: \HKEY_CURRENT_USER\Software\Intuit\QBWebConnector
  • Change the 'Level' key to VERBOSE
  • Start the Web Connector, and run your sync

Where does the Web Connector store data?

In the Windows Registry here: My Computer/HKEY_CURRENT_USER/Software/Intuit/QBWebConnector/

What Should I do with the Web Connector Responses?

When you get a response back from the Web Connector, at the very least you probably want to:

Check for any errors that occurred, and handle them appropriately Store the returned QuickBooks ListID, TxnID, or FullName element for use in future requests How Long Can I Spend Processing QuickBooks Responses?

The Web Connector has a built-in, hard-coded (at least as far as I know) time-out of 2 minutes from the time it sends a response, until the time it receives a response. That means that when QuickBooks sends you it's response, you have exactly 2 minutes to *both receive all of the data via HTTP, _AND_ to process that response*. If it takes you longer than that, the Web Connector will time out and give you an error indicating the connection has timed out.

It is not unusual to encounter this time limit when transferring and/or processing a large number of records returned from a CustomerQuery or an InvoiceQuery or etc. etc. etc.. If you are encountering this error, you should implement your request using QuickBooks iterators to break the response into smaller, faster to process chunks. Another alternative would be to run the processing as separate thread in the background. (or with PHP shutdown functions, or as a forked process, or launched as a separate process, or etc. etc. etc.)

You can find some examples of using iterators to in qbXML requests on the QuickBooks qbXML Examples page.

Does the Web Connector Require a Separate License / QuickBooks User?

Nope, it *does not* count as a separate QuickBooks user, so even if you only have a single-user license, you can still use the Web Connector. Multiple user support in QuickBooks is just for letting multiple users access a single QuickBooks Company data file over a LAN (or on the same PC at the same time). In the Enterprise Edition, you can also set different permissions for different users.

What Does "Unique OwnerID/FileID Required" mean?

Each application that accesses QuickBooks uses a unique OwnerID/FileID combination to attach to QuickBooks. If you get this error message, and you're really, really, super, 100% sure that you don't already have the application installed in the Web Connector (is it under a different Windows user account? are you sure it's not in the Web Connector already?), you can get around this error message by:

  • Open Notepad
  • File > Open
  • Change the 'Files of Type' drop-down to 'All Files'
  • Choose your .QWC file
  • Change a single character in the OwnerID string, and a single character in the FileID string. You can change any of the 0-9, A-F characters to any other character in the range 0-9, A-F. It does not matter which character you change. If the rest of the characters are lowercase, make it lowercase. If the rest of the characters are UPPERCASE, make your new character UPPERCASE.
  • File > Save
  • Re-load the modified file into the Web Connector

Can the Web Connector run as a Windows Service

No.

What Does the Web Connector Look Like?

If I Was Going To Re-write The Web Connector...

- The ability to disable auto-run for a particular snap-in that users should never be able to auto-run

- The ability to set a minimum auto-run time for a particular snap-in

- The ability to set the auto-run frequency in the qwc file and not allow the user to edit it in the UI (password protected?)

- Not require SSL

- Run as a Windows service (hrm… not do-able apparently due to QuickBooks limitations)

- A new UI that's not total crap

- Ability to auto-load from a URL

- Ability to 'push' configuration changes into it from a URL

- “Heartbeat” functionality - have it keep pinging a host so that we know the Web Connector is running

- Ability to 'package' a pre-configured web connector app so the end-user just installs it and leaves it, no config required on their end

- Open the QB file in Single-User or Multi-User mode and abort if it's not available

- Scheduled shut-down times/start-up times/times when it won't connect to QuickBooks

- The ability to disable auto-run for a particular snap-in that users should never be able to auto-run

- The ability to set a minimum auto-run time for a particular snap-in

- The ability to set the auto-run frequency in the qwc file and not allow the user to edit it in the UI

- Logging that's not completely useless

- Ability to support real-time connections