Howdy folks - a couple of small API changes to announce:

• invoice.get and invoice.list now return <recurring_id/>
• project.list can now be filtered by <task_id/>
• time_entry.create rounds hour values to hundredths of an hour (just like the web interface)
• Raised maximum request limit to 5000 requests/day
• A handful of other bug fixes and tweaks

As always, if you have questions or comments, please let us know on the developer forums.

The other day I was investigating an odd error using our development version of FreshBooks in Safari. Lines in an invoice were being reset in an odd way, and I couldn’t add more lines to an invoice as I was creating it. This worked perfectly in FireFox, but not in Safari.

Of course, the first step was to look at the page source. However, the page source looked entirely correct. All of the form elements were defined in the correct places, with the expected order. This is where fantastic tools like Web Inspector (found in the Safari Debug menu) and Firebug come in handy. On reproducing the bug, I managed to SEE the offending tag in its new location in the Web Inspector view. A whole set of input tags sitting at the start of a table!

It turns out that if you replace a table inside a div tag, Safari does some reparsing of your provided HTML. Say, you put a hidden input tag within a tr, but outside of a td. Normally this works fine, and document.forms[0].elements[] shows up in the way you’d expect. But when replacing the table via something like innerHTML, it barfs because the ONLY things allowed in a tr tag are th or td. Thus speaks the XHTML 1.0 transitional DTD:

<!ELEMENT tr (th|td)+>

What appears to happen, is that any input elements outside of a td get bubbled up the DOM until they find a place where they are allowed…in this case, immediately before the enclosing table.

Hence, you get strange results with:

myDiv.innerHTML = "<table border='1'><tbody>" +
"<tr><td><input type='text' value='First'></td>" +
" <input type='text' value='Second'></tr>" +
"</tbody></table>";

But not with:

myDiv.innerHTML = "<table border='1'><tbody>" +
"<tr><td><input type='text' value='First'>" +
" <input type='text' value='Second'></td></tr>" +
"</tbody></table>";

Hence, when adding form elements improperly, programmatically, and referencing them with document.forms[].elements[], you get Very Strange results.

So please, for your own sanity’s sake, nest your elements properly!

Afternoon gang! We’ve got a couple new API feature announcements to kick off 2008 - just 3 weeks after our last release.

Paging Metadata

Now when you submit an API request that returns more than one object (i.e. all *.list methods), you’ll also be returned paging metadata that describes the result set. This should help you better navigate large data sets returned by the API.

Here’s a sample new response from invoice.list:

<?xml version="1.0" encoding="utf-8"?>
<response status="ok">
  <invoices page="2" per_page="5" pages="8" total="37">
    <invoice>...</invoice>
    <invoice>...</invoice>
    <invoice>...</invoice>
    <invoice>...</invoice>
    <invoice>...</invoice>
  </invoices>
</response>

Now, we think this is a swell improvement, and our users have been pining for it. But it comes at a small cost – the introduction of these new top-level paging nodes could break existing integration code. This issue leads into our next announcement:

API Version Numbers

Now when you submit your API requests, you can optionally specify a version number as part of the request URL.

Old URL:

http://mycompany.freshbooks.com/api/xml-in

New URL:

http://mycompany.freshbooks.com/api/2.1/xml-in

To take advantage of these new response formats, you must specify version 2.1 as part of the request URL. If you do not specify a version number, the API will return the old, less-descriptive response format (version 2.0).

Deprecation Warning!

We will support both versions (2.1 and 2.0) until March 1st, 2008. This will give you nearly 8 weeks to migrate your applications to the new schema.

If you have questions, comments or concerns, please contact us.

Hey everyone – long time no see!

After almost three months of silence on this blog, I’m proud to announce that Timesheets (including Projects and Tasks) and Estimates have been added to the FreshBooks API, along with a slew of other features and minor tweaks. Below is a quick summary of the big ones:

Timesheets

Timesheets exposes three new data types – projects, tasks and time entries. Between the three of these, you’ll be able to create new time entries remotely, query for all time entries between a given date, filter down by project or task, and more.

Estimates

Finally, you can interact with estimates just like their older big brother (read: invoices). You can perform basic CRUD operations, poll for estimate URLs, and send them off via e-mail.

Editable invoice and estimate numbers

As of version 4.2, invoice and estimate numbers are now editable. The API is no exception – the <number> parameter will now hold the invoice/estimate number, as opposed to to <invoice/estimate_id>.

Start and stop recurring profiles

You can now start/stop recurring profiles via the API using the <stopped> parameter. Deleting would have the same effect, but you couldn’t get the profile back - now you’re golden.

Version 4.0 of FreshBooks is here, and along with it comes a number of changes/additions to the FreshBooks API.

Recurring Profiles

It’s been a long time coming – you can finally create and manage recurring profiles via the API.

Bigger Search Results

You can now pull up to 100 records from an individual list request, using a per_page value of 100. If left unsupplied, per_page will default to 25.

New Filters

You can now retrieve any invoices generated from a recurring profile using the invoice.list method.

Furthermore, invoice.list will now let you filter search results by status – i.e. ‘draft’, ‘paid’ and so on.

Misc Bug Fixes

If you create a new client via the API, and supply that client’s username and password, they won’t be prompted again for their account details after they’ve logged in. This should help FreshBooks users who are trying to synchronize client account data.

Interested in viewing your invoices and collected revenue in a nice looking graph? Now you can with our new graph generator.

A few months ago, we released our redesigned API which gave you the ability to access and update your FreshBooks information for your custom solutions.
At that time, I release a nice little tool to import your items to your FreshBooks account from comma delimited text. This month, I made this easy to use graph generator with the help of the LastXgraph PHP library and the FreshBooks API.

All you have to do is enable your API for your system and enter your API credentials. Next, click the large submit button and, presto!, a nice graphical representation of your invoices and collected revenue.

The source code is written in PHP is available in the sample code section of our developers section.

Symfony users rejoice: there’s now an easy-to-use plugin for integrating your Symfony applications with the FreshBooks API. In case you’re not familiar, Symfony is a web development framework for PHP:

… symfony aims to speed up the creation and maintenance of web applications, and to replace the repetitive coding tasks by power, control and pleasure.

Much appreciation to the author, Ian Ricketson, for sharing his work. In case you missed it, users have also contributed Ruby and Perl libraries.

If you’re a Ruby or Rails developer looking to get started with the FreshBooks API, I recommend taking a look at the latest sample code we’ve put together: invoice_getter.rb.

It uses FreshBooks.rb, a Ruby wrapper I’ve written, to fetch a particular invoice’s details and render it as HTML. A call to invoice.list populates a select box letting you choose from your last 25 invoices. It might be a useful starting point for businesses that want to customize and style their invoice formats.

For fun, I’ve coded invoice_getter.rb using Rack, the modular web server interface, so it can be either launched traditionally using Apache/CGI, or using Ruby’s WEBrick server. As a Rails enthusiast, I love working with WEBrick – you can quickly launch and re-start your app from the command-line, skipping the messiness of an Apache conf file.

If you’ve already got Ruby and RubyGems installed, you can quickly install Rack and launch invoice_getter.rb like so:

# gem install rack -–include-dependencies
...
Successfully installed rack-0.2.0
Installing ri documentation for rack-0.2.0…
Installing RDoc documentation for rack-0.2.0

# ruby invoice_getter.rb
[2007-07-09 10:50:34] INFO WEBrick 1.3.1
[2007-07-09 10:50:34] INFO ruby 1.8.6 (2007-03-13) [i386-mswin32]
[2007-07-09 10:50:34] INFO WEBrick::HTTPServer#start: pid =3944, port=3000

Now, fire up your web browser to http://localhost:3000 and you’re good to go.

In case you missed the link above, you can download the sample code here.

If you have enabled the API for your system and are ready get started, I highly recommend checking out our sample code collection. If you have PHP installed on your server, I recommend experimenting with the API Tester file. It serves as an excellent testing tool to get started with the API. Furthermore, the code contains functions that you can reuse to create your own custom solutions.

I was able to create a quick program in less than an hour that imports items into your FreshBooks system from a comma delimited text with some small changes to the API Tester file.

For those of you who want to get started quickly with the new API, here are the three steps to get started:

1. Click your white “Settings” link on the top right corner inside your system.
   
2. Click your blue “Enable FreshBooks API” link on the right hand side.
   
3. Click your checkbox to the left of “Yes, I agree to the API terms of service”.
   

If you have PHP installed on your server or website you get started quickly with our sample code. Enjoy.