Monday, November 09, 2015

Implementing a weekly hours summary using the Freshbooks API

It's official: we're moving the accounting side of our business away from Quickbooks to Freshbooks. Shira handles the financial side of things, so the switch doesn't have a huge impact on me. It does mean that the home-grown Google Spreadsheets solution I was using for tracking my time is being replaced by the slicker Freshbooks UI. And so far, I'm OK with that. I'm even more OK with the fact that Freshbooks has a Linux command line time tracking solution, which I haven't setup yet, but am excited to play with.

While Freshbooks has many nifty features (and more importantly, it's far, far lighter weight than Quickbooks), one that a few of my customers like seems to be missing. I wrote some custom PHP code to mail folks a weekly summary of the hours I've spent on their projects. That way, we avoid any end of month surprises. Because my previous time tracking solution was Google Docs based, writing code to pull from the spreadsheets was easy. Luckily for me, Freshbooks offers an API and it's just as easy to use.

This last weekend I whipped up a quick PHP script that I could wire into cron. Once a week, it grabs the appropriate time entries from Freshbooks and sends them in an e-mail to the customer. You can view the code here. If you find yourself needing some feature Freshbooks is missing, perhaps it can be of some use to implement it?

Here's a few notes that may be handy if you want to try running this code yourself:

Supply your own .conf.php file. This file contains all the sensitive information about my configuration, so obviously I didn't check it into Freshbooks. It should have the following shape:

<?
define('FB_KEY', 'Your Freshbooks API Key');
define('FB_DOMAIN', 'The first part of your Freshbooks domain name');

define('EMAIL_FROM', 'accounting@yourcompany.com');
define('EMAIL_SHELL', 'email');

function all_customers() {
  return A(
    array('client_email' => 'contact@companya.com',
          'to'           => 'bob@companya.com,' .
                            'alice@companya.com,' .
                            'accounting@companya.com')
  );
}
?>

all_customers() returns an array of all the customers you want to e-mail.

Checkout lib/freshbooks.php to see the wrapper I wrote around the Freshbooks PHP API. I wanted to add a level of convenience around this very helpful library. Additionally, there were some assumptions I could handle at the API level (such as halting if the API returns an error), rather than letting my higher level code deal with them. See: fb_invoke(...) for the core helper function I wrote.

Don't get me wrong, the Freshbooks PHP API is really handy, especially because the Freshbooks API isn't REST based. The PHP API takes care of preparing and parsing XML messages, which while something I've done plenty of times in PHP, is nice to have already done for you.

Don't forget to customize snippets/email.php. Code under the snippets directory is where the formatting of the e-mail takes place. Unless you want to advertise my company, I'd suggest tweaking this so your company name is splashed across the e-mails.

Hope you find it helpful! Grab the code here.

No comments:

Post a Comment