fmQBO API Concepts

GENERAL API CONCEPTS

Even though our API protects you from the most difficult parts of working with QuickBooks Online API, it is still a good idea to understand the basics of how the API works in general.   This section will cover some of those concepts and how they are expressed in fmQBO.

REST Request

The QuickBooks API is considered a REST API, although it isn’t strictly true. It is close enough to be not worth arguing about.  The important thing to understand about REST APIs is that they use HTTP to ask servers for data and to send data to the server.  That means that somewhere at some point an http request will be made to the server. with fmQBO it’s no different.

You tell fmQBO to make an HTTP requests to the server API by calling a Script called “fmQBO Send (json)” in fmQBO.fmp12.  We pass that script parameter in the form of  JSON screen to tell it what kind of request we want to make.

Here is an example of what that JSON might look like:

{
  "method": "GET",
  "path": "/query",
  "query": [
    {
      "name": "query",
      "value": "SELECT * FROM Item"
    }
  ],
  "headers": [
    {
      "name": "Accept",
      "value": "application/json"
    },
    {
      "name": "Content-Type",
      "value": "text/plain"
    }
  ]
}

In this case we are sending a “GET” request to the “/query” path of the API. We also give it a query and some headers. This is pretty much the same for all requests that get made to an API. There is a “method”, a “path”, a “query”, some “headers” and sometimes a “requestbody” which we didn’t need here.

That is it. If you get that you can do anything with the QuickBooks API and fmQBO. But still writing those JSON strings can be a pain. Thats why we provide the json Custom Functions and fmQBODeveloper. Those two things together can make the process even easier.

Response

The api will respond with a “Response”, which will also be in JSON format.  You can see a full response  here.  The response will contain all the data and/or any error conditions that the QuickBooks API returns. As the developer you will use json Custom Functions we provide or any other means to parse that result so you can store the data in FileMaker system

JSON

The QuickBooks API can accept and return either JSON or XML. We chose to go with JSON for several reasons.  It’s more popular, easier to read, and because the BaseElements plugin can parse it and execute Javascript on it. That makes it incredibly powerful for us.

All data passed into and out of fmQBO will be in the form of JSON.  If you want to send an Invoice to Quickbooks you will have to create a JSON representation of that invoice and then send it.  If you want to get an Invoice from QuicksBooks it will come in the form of a JSON document. JSON is the other key piece along with HTTP request that form the core of most modern web APIs, QuickBooks Online included.

We have a whole section of the Docs dedicated to  working with JSON, and using the custom Functions we provide.  Plus fmQBO Developer can help you write much of this code.

Actions

The other piece to this puzzle are QuickBooks Actions.  QuickBooks documentation talks about Actions in terms of the types of things you can do to an entity like an invoice or customer.  These are specific to the QuickBooks API. There are 5 actions:

  • Query – do a Find
  • Read – retrieve a specific entity ( think record )
  • Update –  edit a specific entity
  • Delete – delete a specific entity
  • Create – make a new entity

In the end these get turned into HTTP Requests like we discussed above.  There we showed a what a Query Action looked like in our JSON format.  Looking at that example we can see that a Query is a GET request.  All the other actions map to HTTP requests in the same way.  You can look at the QuickBooks Online documentation to map those actions to requests. Or you can just use fmQBODeveloper to create the request for you.

Sometimes you will need to string to Actions ( and their underlying requests ) together to accomplish your goal.  For example, if you want to Update an Item, you will almost certainly have to Read that item first.  This is because items can’t be sparsely updated ( see below ). So you are going to need to READ the item, change the properties you want to change and then send it back with an UPDATE.

Sparse

You will see the word “Sparse” around a lot. It comes back as a property on most responses.  And you might need to set the “sparse” property from time to time on an entity before you send it back.

If an entity allows Sparse Updates, what that means is that you can pass back a simple JSON object containing only the properties you want to change.  You don’t need to include the properties you are not going to change. If an entity does not support Sparse updates you need to pass all the properties back.  Any properties that are missing are set to empty. Invoices allow sparse updates, Items do not. See the  Intuit documentation for the latest information on what what each entity allows.

SyncTokens

SyncTokens in QuickBooks Online are analogous to FileMaker’s record Modification Count.  Each time a entity is updated, the SyncToken is incremented.  You can use it to see if an Entity has been updated since the last time you looked at it.

If you try to update an Entity with a stale SyncToken it will fail.  The reason is that the system assumes that somebody else updated the record since you last grabbed it and it would be unsafe to allow the update to go through.  Thats why you often have to do a read before you do an update, so you can get the current sync token.

Still need help? Contact Us Contact Us