The QuickBooks Web Connector's SOAP calls
You don't call QuickBooks. QuickBooks calls you. Your app is the server, the Web Connector is the client, and it calls one URL with eight SOAP methods, in mostly the same order, forever.
The good news is that it's only eight. The less good news is that what you return from each one is a tiny, stringly-typed oddity.
How a session goes
-
serverVersionandclientVersion. Pleasantries. -
authenticate. You say whether there's any work. -
sendRequestXML, thenreceiveResponseXML, around and around until you say you're done. -
closeConnection. Everybody goes home.
When something breaks, you get
connectionError
or
getLastError
where the next step should have been. Every call after
authenticate
carries the ticket you handed out there. Hold on to that ticket: it's the only thing telling one session from another.
serverVersion
- You answer
- Whatever you like. The Web Connector shows it to the user, and an empty string is fine. Enjoy this one.
clientVersion
- It sends
-
strVersion: the Web Connector's own version. - You answer
-
An empty string to carry on, which is almost always what you want.
W:messagewarns the user and lets them continue,E:messagestops the session cold, andO:versioncarries on and names the version you were hoping for.
authenticate
- It sends
-
strUserNameandstrPassword, the way your user saved them for your QWC file. - You answer
-
An array of strings. The first is a ticket you make up for this session. The second is one of:
-
nvu: not a valid user. Session over. -
none: valid, but there's nothing to do. Session over. -
busy: come back later. - An empty string: use whatever company file QuickBooks has open.
- A company file's full path: use that one.
-
Two optional elements can follow: the third is how many seconds to postpone the next run by, the fourth a minimum number of seconds between runs. If you have nothing to put in one, leave it out entirely. Don't send it empty. The Web Connector's own release notes record a crash on an empty third element, and you don't want to be the one who finds out whether they fixed it.
One more thing. The Web Connector polls on a schedule, and the overwhelming majority of those polls find no work. Make this call cheap. If you're running a slow password hash on every single knock at the door, you've built a very polite denial-of-service attack against yourself.
- A QWC file with RunEveryNSeconds leaves the Web Connector's Every_Min column blank rather than showing "Real Time", and a postponement in the authenticate answer still holds the entry to that delay
- With unattended access granted, the Web Connector opens the company file itself when QuickBooks is closed, runs the session and exits it, so a closed QuickBooks is not a connection error for that app
sendRequestXML
- It sends
-
ticket,strHCPResponse,strCompanyFileName,qbXMLCountry,qbXMLMajorVersandqbXMLMinorVers. - You answer
-
One qbXML document, as a string, for QuickBooks to run. An empty string means you've got nothing, and the Web Connector goes and asks
getLastErrorwhat happened.
strHCPResponse
only shows up on the first call of a session, so grab it while it's there. It holds QuickBooks' answers to a host, company and preferences query: the edition, the qbXML versions it speaks, and how the file is set up. You will want every bit of that the day a customer's QuickBooks refuses something yours happily accepted.
strCompanyFileName
is the file this session is actually running against.
Check it's the one you expect before you send a single request.
Users have more than one company file, they open the wrong one, and writing one company's invoices into another's books is a support call nobody enjoys.
A document can carry several requests. And anything that could return a lot of records should be iterated, a page at a time, across calls. Ask for everything at once and you'll learn how large an XML string can get.
- A character Windows-1252 has above 0x7F (é, ©, –, ’, a no-break space) fails the whole document with 0x80040400 when written as itself, and is stored exactly when written as a reference (é); a character Windows-1252 doesn't have is stored as its nearest match, or ?
- QuickBooks Desktop refuses onError="rollbackOnError" for the whole document, though the XSD allows it
- With onError="stopOnError", QuickBooks answers every request after the first failure with 3231 instead of leaving it out
- An iterated query by ListID or FullName answers 3150 for a missing MaxReturned, which the XSD forbids beside an id, so an iterator can never be combined with an id
receiveResponseXML
- It sends
-
ticket,response,hresultandmessage. - You answer
-
A whole number. 0 to 99 is how far along you are, and the Web Connector comes back with another
sendRequestXML. 100 means you're finished, and it callscloseConnection. A negative number means something went wrong on your side, and it callsgetLastError.
response
is QuickBooks' qbXML answer to what you sent. Here's the trap:
a response arriving is not the same as your request working.
Every request inside it has its own
statusCode, and QuickBooks will cheerfully hand you a well-formed document full of refusals.
When QuickBooks couldn't answer at all,
response
comes back empty, and
hresult
and
message
say why.
connectionError
- It sends
-
ticket,hresultandmessage. - You answer
-
doneto give up on this session, or a company file's path to try again with that file.
This is the Web Connector telling you it couldn't get a session with QuickBooks in the first place: QuickBooks is closed, a dialog box is sitting open on someone's screen, or a different company file is open. Where I've seen it, it came straight after
authenticate, before any request went out, so nothing was run and nothing was lost.
Most of these are not bugs. They're a person at a desk. Tell your user what to do in plain words, because "0x8004040A" will not help them.
- Two Web Connector entries on different company files both run when QuickBooks has no company open or is closed altogether, each file opened in turn; with one file open in QuickBooks, the other entry gets connectionError 0x8004040A and its request stays retryable
- When the QuickBooks the Web Connector starts never finishes opening the company file, the Web Connector waits on "Connecting to QuickBooks..." with no timeout and calls nothing, blocking every entry behind it; ending the QuickBooks process gives connectionError 0x80040402
getLastError
- It sends
-
ticket. - You answer
-
A message the Web Connector shows your user, so write it for a human. There's one magic word:
NoOpmakes the Web Connector wait five seconds and callsendRequestXMLagain.
closeConnection
- It sends
-
ticket. - You answer
-
A message shown as the session's final status.
OKdoes nicely.
That ticket is done. The next session starts all over again at
authenticate, in a few minutes, and a few minutes after that, for as long as your customer keeps their computer on.
See it run
The simulator walks through these calls for an invoice, with the SOAP on both sides. Or, if eight methods and a queue already sound like a second job: QuBe Sync runs the SOAP server for you and hands you a JSON API.