Expense categories added!

Well that makes sense now. Now the little <category_id> on expense operations means something. With the introduction of Expense Categories to the API, you now have the flexibility to manipulate them freely.  This includes any taxes that may apply.

The taxation mechanism is flexible to your requirements, but it’s also a relationship that you are required to maintain.  <tax1> and <tax2> can be used to track your own tax ID against chosen categories, and then calculated and displayed on the individual expense via <tax1_name>, <tax1_percent> and <tax1_amount>.  Three more fields for <tax2_ now appear on expense.get operations as well, and match the preceeding format.

These changes have been reflected in the Expenses API documentation, and a new link for categories has been added.  Please feel free to discuss or ask questions in the forum.

Ch-ch-ch-changes… introducing <links/>

The object URI changes we made a while back appear to be helpful.  So much so, we’ve been getting some granular requests that are object specific, and we can see some of the benefits in bringing them to you.  But first, and a FreshBooks API first, we’ve added our first deprecation to the API.

I’ve secretly hated the look/feel/sound of our current URI responses in the form of <url> and <auth_url> on invoices, estimates and clients.  While they still exist today, you may notice a new property on the <url> and <auth_url> elements, and that is ‘deprecated=”true”‘.  Make use of them while you can, because in some future update, they will just vanish.  API version 3?  2.2? I promise nothing.  Consider this a 2 minute warning, of a sort.

The new format consists of a <links> parent which will contain <client_view>, replacing <url>, and <view>, replacing <auth_url>.  Your output should look something like this:

  <links>
    <client_view>https://sample.freshbooks.com/inv/514-24-d4622</client_view>
    <view>https://sample.freshbooks.com/inv/514-24-d4622-z</view>
  </links>

Links is part of the <invoice>, <estimate> and <client> response when you execute the appropriate .get operation successfully.

Our object specific update of the day is just for invoice.get and fits into the <links> response element.  The new link directly takes an authenticated administrator to the target invoice for editing.  It should look something like this:

  <links>
    <edit>https://sample.freshbooks.com/inv/514-24-d4622-e</edit>
  </links>

As always, comments and further suggestions are welcome and encouraged.

Expenses and Staff APIs are released!

At long last, I present to you, the people (the Freshies), the Expenses API!

<suitably long pause for applause… keep going I can wait.>

Notes on the Expenses API

We’re releasing the Expenses API in two phases. This phase contains the core Expenses data. The next phase will include Expense Categories. That will be out Very Soon(tm). (famous last words)

Expenses are also dependent on staff and client associations; so, in the expenses response, we’ve provided a staff_id and a client_id. You can use the Clients API to acquire client details, and the new Staff API to acquire staff details.

Notes on the Staff API

We’re also releasing the Staff API in phases. For now, the Staff API only has the staff.get and staff.list commands. That should be enough to make the Expenses API useable.

Please note that staff_id 1 is the administrative account.

Fun with SparkLines

If you have never heard of a sparkline, they are what Edward Tufte describes as “word sized graphics.” Said another way, they are little charts that you can use in the middle of a paragraph. Said yet another way, they are really cool.

Colin Ramsay, who runs Plastiscenic, and is a customer of ours, has created a really fun little application on our API. It displays a sparkline of revenue by month.

It’s a pretty compact way of seeing whether you are on track in your business or not. I’ll let Colin explain what it all means:

Ones in which invoice totals exceed the specified upper threshold are marked in green, and ones which are lower than the lower threshold are red. Everything else is black. To the side of the graph, there’s a numerical readout of the invoice totals from this month and the previous month, again coloured accordingly.

If you’re interested in using it for yourself, Colin has provided the source.

Dan is on the scene

Hello there Developers.  My names Dan.  I’m new developer on the API team! I’ve been lurking in the shadows, answering your support questions, getting up to speed on the back-end here at FreshBooks.

Now that the training wheels are off I’m going to be roaming around the API with Mike.  Keep your eyes peeled for fresh new integrations and additions to the API. We’ll be tackling things that are brought to our attention here on the blog as well as over at the developer community.

Object URI and You

Good day, eh.  There’s been a small update to the API that some of you might already have noticed.  We added an <auth_url /> element, in the style our existing <url /> tag, for invoices, estimates and clients.

The new <auth_url /> requires an authorized session to work, and is intended to provide an administrative link to your target object.  Since we didn’t have a client <url /> element in the client.get response, we’ve included that for consistency.

<auth_url /> will honour an existing administrative session, if you have already logged into the application in some way. It will NOT auto-magically direct you to a secure administrative page without prompting you for user and password if you haven’t already logged in.  So don’t get’em mixed.  <url /> is for client links, <auth_url /> is for you.

Summary:

• client.get:
  • <url /> added to response
  • <auth_url /> added to response
• estimate.get:
  • <auth_url /> added to response
• invoice.get:
  • <auth_url /> added to response

Our API documentation has been updated to include this element where necessary.

Introducing Mike

Allo Freshies!  My name is Mike (no, not McDerment), and I’ll be one of your API developers.  I say “one of your API developers” as we have a whole team now (there are two of us).  So be prepared for updates big and small.

Since I’m the second Mike in the office, I’ve been barraged with nicknames since I joined up.  Because my last name is Gauthier, there are a few variations I will respond to.  Mikey G or MG would work.  G-man?  Michael?  Embarrassing.  But since Mike McDerment doesn’t really post on the Developers blog, I can hope and dream of being just ‘Mike’ again.  We can keep that between us.

From here on in, we intend to post more frequently than we have.  Our last blog post was in June, and that’s just not cool.  Also, please feel free to get in touch with us via the developer forum.  My teammate Dan (introduction forthcoming) and I will be actively monitoring our community and addressing developments and concerns both here and there.

More apps using the API!

We now have several new apps that interact with FreshBooks. It’s great to see this kind of work starting to happen!

• Andrew finally had enough of seeing people enjoy the OSX widget and wrote a time-tracking gadget for the Vista Sidebar based off of the OSX widget! Not only does our widget provide a place for others to start, but we’re also going to help Andrew make it look pretty.
• Joel has written GetFresh, a new way for your clients to log into their FreshBooks accounts in order to pay you faster. For a small fee, you can download and configure the app, then send it to your customers. They can fill in their username and password, and with 2 clicks can be logged right into FreshBooks. Joel’s also included a screencast showing how to configure things.

Remember that the above apps are from 3rd parties, and FreshBooks is not responsible for their content or functionality. We’re just happy that people are building useful things for everyone, and want to share the news with everyone.

If you’ve got an idea for a widget, gadget, app, or script that would make your life easier, all I can say is that there is no time like the present. The API is here, it’s alive, and I’ll be kicking it into shape for you.

Once you’ve got your app running, you can count on us to take notice, and let everyone know about the excellent job you’ve done. We’re rooting for you!

FreshBooks API for staff time tracking is here, and more!

We’re happy to announce that we’ve extended the FreshBooks API to allow staff access to time tracking functions! Yes, that includes our OSX Widget, and other time tracker add-ons.

Notable features

• Each staff member receives a unique API token, just like the admin user. This identifies the staff member for any actions he or she takes via the API.
• We speak the same great API for both staff and the admin account! This means that time trackers that work with the admin account should continue to work seamlessly for your staff members.
• We respect the access restrictions you’ve set. Your staff members will be able to view and edit the same information (no more, and no less) through the API as they would be able through the application itself.
• This change shouldn’t affect any API applications you already had running. If it does, let us know!

How to find your staff token

First of all, the admin user has to enable the FreshBooks API. Then any staff member can browse over to his or her Profile page (link at the top, beside Help and Logout). The token and access URL will be displayed at the bottom of the page. The admin user can also find any staff member’s token, by Editing the staff member in question.

Caveats

Of course, there are always caveats. In order to release this feature as soon as possible for your use–while maintaining the same security you expect from FreshBooks–we’ve only implemented the client, project, task, and time_entry API methods. Staff members trying to access unimplemented features will receive an API error response.

And more!

We’ve made a few other updates to the API:

• client.get now returns the client’s current credit balance
• project.list and task.list now only return active, non-archived items, just like you expect when tracking time in your browser.

We’ll be updating the API docs today to reflect these changes. So go forth and track time, and let us know what you think. Enjoy!

Making Widgets with jQuery

You may have noticed that we recently released the FreshBooks Time Tracker widget. What you may not have noticed beneath its shiny exterior, is this fantastic helper library called jQuery. Here are some excellent reasons for using it…

Portability

While the FreshBooks widget is currently only for OSX’s Dashboard, a lot of the HTML element access and glitzy fades are pure jQuery, and should be portable to other widget facilities, and the FreshBooks website itself. It’s also nice to be able to use the same skills in widget creation as webpage creation.

Power

The $() construct is much, much more powerful than it at first appears. Take a closer look at the full power of selectors to see what I mean. And the skills you learn are re-usable, since jQuery implements CSS3-style selectors. When browsers get around to fully supporting them, you’ll already be at home. In addition, jQuery also makes dealing with XML (as returned by the FreshBooks API) and Ajax in general a whole lot easier!

Conciseness

jQuery also leads to shorter, more concise JavaScript. $("#submit") is so much easier to type than document.getElementById("submit"), and infinitely more flexible when you want to, say, operate on all of the images in a page with $("img"). You “chain” together various jQuery commands, such as css() and show() simply by applying them to the returned “wrapped set”, like $("img").css('opacity',0.5).

Peer Pressure

Apparently I’m not the only one who thought this would be a good idea. I just recently noticed an awesome SVN notifier widget which also includes jQuery. Perhaps the idea is catching on…