QuickBooks Online via qbXML

From ConsoliBYTE Wiki
Jump to: navigation, search

Contents

DO NOT USE ANY OF THE INSTRUCTIONS BELOW - THEY ARE NOT VALID ANYMORE

Go back here instead: http://www.consolibyte.com/docs/index.php/QuickBooks

QuickBooks Online via qbXML

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

Note that if you're building a SaaS (software as a service) application, you should probably be using the Intuit Partner Platform instead of the qbXML gateway.


Connecting with the 'Desktop' model of communication

Connecting with the 'Hosted' model of communication

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

  • 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.
  • 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...)
  • Make an HTTP POST to https://webapps.quickbooks.com/j/AppGateway to request a session ticket
  • 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:

Log in to your QuickBooks Online Edition account Go to 'My Account' Click on 'Connection List' Choose the appropriate connection and click the 'Edit' button 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.” If it is not selected, select it. 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 via qbXML supports a considerably smaller subset of the API commands that desktop versions support. Intuit has no plans to update the qbXML interface any longer.

In particular, some things big "gotchas":

  • No support for InvoiceMod (modifying existing QuickBooks Online invoices)
  • No support for inventory/quantity on hand
  • No support for Purchase Orders

Slow CustomerAdd Requests

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