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

How To Run a Stealth Rails Application

by Justin in FreshBooks on April 1, 2009

I’ve got a little secret to share about our technology stack here at FreshBooks.  Although by all appearances we are just another PHP shop, FreshBooks has actually been powered by Ruby on Rails for about three years now.  Here’s how we did it:

Back in late 2005 when Rails hit the mainstream, we were eager to do a complete bottom-up rewrite.  However, management was rather concerned that our customers would react negatively to such a radical technology change.  Would people trust their financial data with an unproven web framework that had only recently been publicly released?  To stay on the safe side, we decided to disguise the new Rails app to appear as though it was still the old PHP version.

Thanks to Rails’ flexibility, this was surprisingly easy to achieve.  The heart of the disguise is a single line added to our routes.rb file:

  map.connect ':fake_filename.php', :controller => 'php', :action => 'dispatch'

This takes what appear to be requests for php files and sends them over to our PhpController controller.  In the dispatch action, we lookup the “filename” that was requested and map it to an action and a controller to actually handle the request.

class PhpController < ApplicationController
  FILENAME_ROUTES = {
    'about' => { :controller => 'about', :action => 'index' },
    'pricing' => { :controller => 'pricing', :action => 'index' },
    # ...snip…
  }

  def dispatch
    redirect_to :controller => FILENAME_ROUTES[params[:fake_filename]][:controller], :action => FILENAME_ROUTES[params[:fake_filename]][:action]
  end
end

Sure, there is a little performance hit with the redirect, but we’ve found that most users don’t really notice.

We use Apache (with mod_proxy) to send requests to Webrick application servers.  Although it uses a lot of memory, our Webrick cluster has held up surprisingly well.  We’ve been meaning to switch to something more modern like FastCGI + lighttpd so we’ll keep you posted.

Anyway, I hope that this hasn’t come as too much of a shock to anyone. We’ve been running this setup for quite a while and felt it was time to come clean (although some people have suspected that this is what we were up to for some time now).

5 comments

Introducing Return to Merchant

by Owen in API Additions on March 26, 2009

For those of you out there who use FreshBooks as part of a storefront, we have a new feature just for you. FreshBooks invoices created through the API can now have a “return-to-merchant” link. When one of your customers pays an invoice that has a link, they’re given the option to return to your site via whatever URL you specify when you create the invoice. This feature is only available through the API (for now) - try it out and let us know what you think.

Creating an invoice with a return-to-merchant link.
If you already have code that creates new invoices, adding return-to-merchant links when creating an invoice means adding one more element to the <invoice /> element in your request: <return_uri>YOUR URL HERE</return_uri>. The URI from your API request will be used verbatim, so remember to include the http:// or https:// at the beginning.

<?xml version="1.0" encoding="utf-8"?>

  
    2

    
      
    

    http://invoices.example.com/thanks-for-paying
  

The <request_uri /> element is supported in invoice.update, and it’s returned from invoice.get requests.

What will your customers see?
The return-to-merchant link is shown to your customers only after they’ve paid their invoices. The payment summary page has an extra link, which will send them to… well, anywhere you want. We’ve also streamlined the payment landing page so that it acts more like the rest of FreshBooks: it now has a clear confirmation message, then the next steps to take, and finally extra information.

Recurring profiles can have return-to-merchant links too.
You can include <return_uri />s in recurring.create and recurring.update, too. When an invoice is created from a recurring profile, some variable substitution takes place, so that the generated link can include a reference back to the invoice.

Let’s say you set your recurring profile’s return_uri to

http://invoices.example.com/invoices/::invoice id::/paid

The invoice ID (invoice_id in the invoice.get API response) of the generated invoices will show up in each invoice’s <recurring_uri> - for example, if the generated invoice ID is 16, then the return-to-merchant link will point to

http://invoices.example.com/invoices/16/paid

This works with ::invoice number:: and the invoice_number of the generated invoices, too.

What about…
There are lots of things we’d like to do with this in the future to make the FreshBooks API support more scenarios. I’m sure some of you have software you’d like to have notified when a customer pays an invoice, for example - that comes up a lot with PayPal’s basic integration, which uses a similar “return to merchant” feature to implement notifications. We’d love to hear other ways of extending the API to better fit how you want to use FreshBooks.

0 comments