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

  1. serverVersion and clientVersion. Pleasantries.
  2. authenticate. You say whether there's any work.
  3. sendRequestXML, then receiveResponseXML, around and around until you say you're done.
  4. 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:message warns the user and lets them continue, E:message stops the session cold, and O:version carries on and names the version you were hoping for.

authenticate

It sends
strUserName and strPassword, 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.

sendRequestXML

It sends
ticket, strHCPResponse, strCompanyFileName, qbXMLCountry, qbXMLMajorVers and qbXMLMinorVers.
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 getLastError what 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.

receiveResponseXML

It sends
ticket, response, hresult and message.
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 calls closeConnection. A negative number means something went wrong on your side, and it calls getLastError.

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.

Every statusCode and hresult, with its message

connectionError

It sends
ticket, hresult and message.
You answer
done to 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.

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: NoOp makes the Web Connector wait five seconds and call sendRequestXML again.

closeConnection

It sends
ticket.
You answer
A message shown as the session's final status. OK does 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.