API Updates: Project Staff, Custom Emails and payment.delete

by Paul in API Additions, Development on October 23, 2009

On Wednesday we released some pretty exciting updates to our API and wanted to make sure you were aware of them.

Project Results

If you are an administrator or a staff member who is assigned as a project manager to a project, project.get and project.list methods now return the ids of users who are assigned to that project. Up until now it was impossible to determine if a user was assigned to a project when listing them. Because of this, our OS X time tracker for instance would list all projects that a user could see, not just the ones that they were assigned to. If the user clicked on "Submit" after selecting a project that they weren't assigned to, they would get an error because you can't track time to a project you aren't assigned to. What a headache! See the updated documentation for details.

Custom Emails

You can now send custom email messages with invoice.sendByEmail and estimate.sendByEmail. Just include both a subject and a message element in your request. You can use any of the variables that are available when customizing messages within FreshBooks (i.e. ::invoice link::, ::payment amount::, ::estimate link::). See examples on the invoice and estimate documentation pages.

Delete Payments

We've added a payment.delete method. This will allow you to permanently delete payments. If the payment being deleted was made against an invoice, the status of the invoice will be updated. Check out the documentation.

So there you go, three great new features!

0 comments

Staff API Access: No More Restrictions!

by Paul in API Additions, Integrations, Development on September 30, 2009

As of today, the FreshBooks API is fully functional for Staff members, not just Administrators. Ever since its debut, the API has used a more restrictive set of permissions than the application. This made things a little simpler for us, but it didn't help our users or third-party add-on developers. It meant that certain third-party applications simply weren't as useful for customers who had multiple staff members sharing a single FreshBooks account. We've received many requests from developers to open up permissions in the API so that they more closely follow the permission settings in the application. You have been heard!

Staff now have access to all of the API methods as long as they are given the appropriate permissions from the application settings. This means that if the invoices tab is enabled for staff in the application, they can view and edit invoices from the API for clients who they are assigned to. Likewise, if the estimates tab is enabled, they will have API access to estimates for clients who they are assigned to. Ditto for Recurring Profiles, Payments and Items.

We hope that this change will make existing applications more useful and encourage new kinds of third-party add-ons that were simply not possible before. Having the API be more consistent with the application should help make FreshBooks more useful for everybody.

1 comments

FreshBooks now supports OAuth

by Sunir in Integrations, Development on September 10, 2009

FreshBooks now supports OAuth to make it easier to build and manage its third-party addons.

Today, we're proud to announce that we now support OAuth, an increasingly popular open protocol for secure API authorization. OAuth is used by many cool services such as Google Docs, Netflix, and Twitter, and we're glad to join the club!

Over the past year, FreshBooks has grown a large collection of third-party add-ons. Supporting OAuth will make it easier for customers to manage third party add-ons' access to their FreshBooks data. Add-ons that support OAuth will no longer require customers to search for and then copy and paste their FreshBooks authentication token, which will be a huge relief to customers and third party integrations alike.

More importantly, instead of sharing one authentication token with all third-party add-ons, OAuth creates a separate relationship for each add-on uniquely, all behind the scenes. That means customers will be able to turn on and off access to each separate add-on without affecting any others. This gives customers important control over who has access to their data, and when.

We strongly recommend all third-party add-ons use OAuth for secure authorization since we may eventually require it for all future add-ons.

For more information about OAuth you can read the official OAuth documentation available at the OAuth.net site as well as the FreshBooks OAuth documentation. Also, stay tuned to the Developer Blog for all future updates about OAuth and the FreshBooks API.

2 comments

Javascript library for FreshBooks API

by Sunir in Development on May 20, 2009

Props to Milan Rukavina who has created a Javascript library for FreshBooks, available under the Apache License, version 2.0. The library allows web applications to make calls to FreshBooks through Javascript. However, because Javascript is not permitted to make cross-domain requests, you will need to install a server-side proxy or a flash-based proxy. See the project page for details.

1 comments

Are you using Keep-Alive?

by Taavi in Development on January 30, 2009

Do you use the FreshBooks API? Do you make multiple requests in a session? Is it painful waiting for each and every request to complete?

If so, you have to ask if you’re getting the best performance out of the API. When one piece of work at your end may entail 3-4 API requests, the average speed of making requests can have a big impact on your own application’s performance.

Our web servers are set up to allow HTTP persistent connections which eliminates the delay of opening a new HTTP connection (and renegotiating SSL!) for each API request.

In our own testing, this can result in up to 50% time savings over the course of a multi-request interaction! For example, cURL in PHP automatically takes advantage of persistent connections, if you don’t force it to make a new connection each time:

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $api_url);
curl_setopt($ch, CURLOPT_USERPWD, $token);
$request = get_first_request();
while ($request) {
  curl_setopt($ch, CURLOPT_POSTFIELDS, $request);
  $request = get_next_request($response = curl_exec($ch));
}
curl_close($ch);

Ben’s looking to update the FreshBooks Ruby wrapper to make use of persistent connections. Enjoy!

0 comments

Making Widgets with jQuery

by Taavi in Development on May 1, 2008

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…

0 comments

The Importance of Strict HTML

by Taavi in Development on March 3, 2008

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!

0 comments