QuickBooks Online via qbXML
Consolibyte (Talk | contribs) (Created page with "== 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 (s...") |
Consolibyte (Talk | contribs) |
||
| Line 185: | Line 185: | ||
* No support for Purchase Orders | * No support for Purchase Orders | ||
| − | ==== Slow CustomerAdd Requests === | + | ==== 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). | 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). | ||
Revision as of 16:01, 24 February 2012
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.
Open-source Frameworks with QuickBooks Online via qbXML Support
Sample QuickBooks Online via qbXML Code
Connecting with the 'Desktop' model of communication
- Register you application here: https://appreg.intuit.com/AppReg.aspx
- Visit this page to add the application to your Online Edition account: (make sure you change YOUR-APPLICATION-ID to your actual application ID)
- Intuit will display you the connection ticket that you'll then copy/paste into your application
Connecting with the 'Hosted' model of communication
- 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));)
- 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)
- 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
- openssl genrsa -out host.key 1024
- openssl req -new -nodes -key host.key -out host.csr
- Finish going through the app registration, saving the stuff it spits back out at you
- Visit this page to add the application to your Online Edition account: (make sure you change YOUR-APPLICATION-ID to your actual application ID)
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).
