Integration with QuickBooks Online Edition

Additional documentation is provided in the QuickBooks SDK. Chapter 7, Page 87 of QBSDK_ProGuide.pdf

Open-source Frameworks with QuickBooks Online Edition Support

Sample Code

Brief Overview

Connecting with the 'Desktop' model of communication

  1. Register you application here: https://appreg.intuit.com/AppReg.aspx
  2. Visit this page to add the application to your Online Edition account: (make sure you change YOUR-APPLICATION-ID to your actual application ID)
  3. Intuit will display you the connection ticket that you'll then copy/paste into your application

Connecting with the 'Hosted' model of communication

  1. Create a page on your website (i.e.: https://www.your-domain.com/page.ext) which receives an HTTP POST from Intuit. You should receive the POST data and write all of the POST data to a database or a file. This is the 'callback url' you use during the application registration process. (i.e. if you're using PHP: $fp = fopen('file.txt', 'w+'); fwrite($fp, print_r($_POST, true));)
  2. Register your application here: https://appreg.intuit.com/AppReg.aspx (you'll only get part-way through the process before you need to generate a CSR)
  3. Generate a CSR on your server. You can do this with the following two commands. The [Common Name] for the CSR should be in the form of: your-https-hostname.com:your-application-login
    1. openssl genrsa -out host.key 1024
    2. openssl req -new -nodes -key host.key -out host.csr
  4. Finish going through the app registration, saving the stuff it spits back out at you
  5. Visit this page to add the application to your Online Edition account: (make sure you change YOUR-APPLICATION-ID to your actual application ID)
  6. QuickBooks Online Edition will ask the user what type of Login Security to use, and ask the user to turn on login security. You must select “No. Anyone who can log into [Application Name] can use the connection”.
  7. Check the file/database that the script you wrote in step 1. wrote to. Intuit should have issued an HTTP POST with a connection ticket to that URL.
  8. Concatenate the key and the certificate generated by Intuit for your CSR (key first, certificate second). This is the .PEM file you will need to send to Intuit when making requests. (Note: I'm not sure if this is PHP-specific, or if other languages use this format as well…)
  9. Make an HTTP POST to https://webapps.quickbooks.com/j/AppGateway to request a session ticket
  10. Issue further HTTP POSTs to that same URL with the new session ticket

Notes

You can inspect an existing CSR with this command: openssl req -in server.csr -noout -text

You can inspect an existing certificate with this command: openssl x509 -text -in /Users/kpalmer/cert.pem

If you get an error that says “ARSC260: Login name not found. Check your CN= entries applogin value”, try generating your CSR again without entering an e-mail address. For some reason entering an e-mail address borks the CSR sometimes.

If you get an error that says “2000: Host in certificate does not match connected host”, check that your reverse DNS entries point to the correct server. You can check your reverse DNS with this command: host xxx.xxx.xxx.xxx (where xxx.xxx.xxx.xxx is your IP server's address)

If you get “2020: Session Authentication required” messages whenever you try to POST to the QBOE gateway, your user probably didn't choose the “No. Anyone who can log into [Application Name] can use the connection.” security option when prompted to turn on login security during the QBOE setup.

Example qbXML for Online Edition

Example request to get a session ticket when running in HOSTED mode:

<?xml version="1.0" ?>
<?qbxml version="6.0"?>
<QBXML>
	<SignonMsgsRq>
		<SignonAppCertRq>
			<ClientDateTime>2007-01-02T01:02:35</ClientDateTime>
			<ApplicationLogin>login goes here</ApplicationLogin>
			<ConnectionTicket>connection ticket goes here</ConnectionTicket>
			<Language>English</Language>
			<AppID>application id goes here</AppID>
			<AppVer>1</AppVer>
		</SignonAppCertRq>
	</SignonMsgsRq>
</QBXML>

Example request to get a session ticket when running in DESKTOP mode:

<?xml version="1.0" ?>
<?qbxml version="6.0"?> 
<QBXML>
	<SignonMsgsRq>
		<SignonDesktopRq>
			<ClientDateTime>2009-10-09T07:10:10</ClientDateTime> 
			<ApplicationLogin>application login goes here</ApplicationLogin> 
			<ConnectionTicket>connection ticket goes here</ConnectionTicket> 
			<Language>English</Language> 
			<AppID>application id goes here</AppID> 
			<AppVer>1</AppVer> 
		</SignonDesktopRq> 
	</SignonMsgsRq> 
</QBXML>

Example query for a customer:

<?xml version="1.0" ?> 
<?qbxml version="6.0"?> 
<QBXML> 
	<SignonMsgsRq>
		<SignonTicketRq> 
			<ClientDateTime>2006-09-20T15:49:26</ClientDateTime> 
			<SessionTicket>session ticket goes here</SessionTicket>
			<Language>English</Language> 
			<AppID>application id goes here</AppID>
			<AppVer>1</AppVer> 
		</SignonTicketRq> 
	</SignonMsgsRq> 
	<QBXMLMsgsRq onError="continueOnError"> 
		<CustomerQueryRq requestID="2" /> 
	</QBXMLMsgsRq> 
</QBXML>

Example response from that query:

	

<!DOCTYPE QBXML PUBLIC '-//INTUIT//DTD QBXML QBO 6.0//EN' 'http://webapps.quickbooks.com/dtds/qbxmlops60.dtd'>

<QBXML>
	<SignonMsgsRs>
		<SignonTicketRs statusCode="0" statusSeverity="INFO">
			<ServerDateTime>2009-01-31T16:10:46</ServerDateTime>
			<SessionTicket>session ticket goes here</SessionTicket>
		</SignonTicketRs>
	</SignonMsgsRs>
	<QBXMLMsgsRs>
		<CustomerQueryRs requestID="2" statusCode="0" statusSeverity="Info" statusMessage="Status OK">
			<CustomerRet>
				<ListID>1</ListID>
				<TimeCreated>2009-01-31T08:06:01</TimeCreated>
				<TimeModified>2009-01-31T08:06:01</TimeModified>
				<EditSequence>0</EditSequence>
				<Name>Keith Palmer Jr.</Name>
				<FullName>Keith Palmer Jr.</FullName>
				<Sublevel>0</Sublevel>
				<FirstName>Keith</FirstName>
				<LastName>Palmer</LastName>
				<Suffix>Jr.</Suffix>
				<BillAddress>
					<Addr1>56 Cowles Road</Addr1>
					<City>Willington</City>
					<State>CT</State>
					<PostalCode>06279</PostalCode>
					<Country>USA</Country>
				</BillAddress>
				<PrintAs>Keith Palmer Jr.</PrintAs>
				<Balance>0.00</Balance>
				<TotalBalance>0.00</TotalBalance>
				<IsStatementWithParent>false</IsStatementWithParent>
				<DeliveryMethod>Print</DeliveryMethod>
			</CustomerRet>
		</CustomerQueryRs>
	</QBXMLMsgsRs>
</QBXML>

Frequently Asked Questions

Why am I getting a "Session Authentication required" error message?

You're trying to communicate with QuickBooks Online Edition via PHP / .NET / Java / etc., and you get this error message:

<QBXML>
 <SignonMsgsRs>
   <SignonAppCertRs statusCode="2020" statusSeverity="ERROR" statusMessage="Session Authentication required">
     <ServerDateTime>2009-11-23T11:24:34</ServerDateTime>
   </SignonAppCertRs>
 </SignonMsgsRs>
</QBXML>

This error message means that you have login security turned on in QuickBooks Online Edition. Login Security prohibits automated access to QuickBooks Online Edition programatically. If you want to be able to access QuickBooks Online Edition programatically, you have to turn this off.

To do this, you can:

  1. Log in to your QuickBooks Online Edition account
  2. Go to 'My Account'
  3. Click on 'Connection List'
  4. Choose the appropriate connection and click the 'Edit' button
  5. For programmatic access to QuickBooks Online Edition, this option must be chosen: “Login Security: No. Anyone who can run {your application name here} can use the connection.”
  6. If it is not selected, select it.
  7. If it is un-selectable, you must create a new connection to your application, making sure to turn off login security when creating the connection.

Known Bugs/Limitations of QuickBooks Online Edition

Limited API

QuickBooks Online Edition supports a considerably smaller subset of the API commands that desktop versions support

Very slow CustomerAdd / CustomerAddRq / CustomerMod / CustomerModRq when not using a <DeliveryMethod>

If you issue a CustomerAdd or CustomerMod to QuickBooks Online Edition, but do not include a <DeliveryMethod> tag, the request will process very slowly, often causing time-outs. The fix is to simply add a <DeliveryMethod> tag to your request. Your request will then process very quickly. The difference is substantial (2 minutes versus 2 seconds).

college essay

quickbooks_online_edition.txt · Last modified: 2013/01/21 12:44 (external edit)