As the title suggests, the FreshBooks.rb project can now be found at Rubyforge. If you’ve got any bug reports, feature requests, or just want to ping me about the software – please use the tools there.

Why the change? Well, now you can now install FreshBooks.rb as a gem. It’s as easy as:

gem install freshbooks

Lastly, the latest release now includes support for recurring profiles.

At the urging of my FreshBooks cohorts, I submitted a panel proposal to SXSW Interactive for 2008. The idea: get a bunch of developers from leading web 2.0 companies to talk about the design and implementation decisions behind their web service APIs.

So, why me? Well, one of my primary duties at FreshBooks is continued development on the FreshBooks API. I’ve had a pretty big hand in designing the request and response structure, determining which methods make the cut, writing the API documentation, and so on. It was a great learning experience, and I think it’d be great to pass that knowledge on (with the help of some others, of course) to other would-be API developers.

Whether you’re attending SXSW next year or not (hopefully you are), you can vote for the panel here. Please forgive my suspect choice of panel name :)

FreshBooks happened to re-release their API today. It’s a pretty significant overhaul, and I’ve re-written my Ruby wrapper to reflect the changes. The code is still in it’s early stages, but if you want to check it out, you can pull it from my Subversion server:

svn co svn://benlog.org/pub/freshbooks

It’s also got a new name: FreshBooks.rb. The old name (FreshBooks API for Ruby) was a little long winded.

Update: Fixed up a few bugs pointed out by Flinn. Thanks for the heads up.

Technology moves fast – on the web, even faster. If you’re a developer, how do you stay on top of new techniques, tools, and languages? Below I’ve shared some resources that help me stay current.

You can check out the article over at Fresh Thinking.

I’ve put together a little Ruby API wrapper for the FreshBooks public API. In case you’re not familiar with it, FreshBooks is an online invoicing app designed for small to medium-sized businesses. I don’t know how many FreshBooks users use/develop in Ruby, but hopefully someone’ll find it handy.

I guess I should mention that I’ve accepted a software development position at FreshBooks, which I’ll be starting very shortly. The FreshBooks team is a good group of talented folk, and I think it’ll be a real blast working with them. I wrote this library to get a little head start on things – plus it was fun :)

If you’ve got any comments, suggestions, or bug fixes for the code, please let me know below.

Note: FreshBooks.rb has moved to Rubyforge.

FreshBooks.rb is a set of Ruby classes and methods that make it easy to build applications that interact directly with your FreshBooks account through their public API. Specifically, you can add and edit clients, create invoices, and inquire about payment status – all without the messiness of building/parsing your own XML messages.

License

This work is distributed under the MIT License. Use/modify the code however you like.

Download

You can grab the files from my public Subversion repository:

svn co svn://benlog.org/pub/freshbooks

Below is some basic documentation for the most common use cases. You can read more about the API from the official documentation.

FYI – This documentation is deprecated. Please see the new page at Rubyforge.

Create a new client

require 'freshbooks'

account = Freshbooks.new 'your_company', 'username', 'password'

client = Freshbooks::Client.new

client.first_name    = 'Donna'
client.last_name     = 'Changstein'
client.username      = 'dchangstein'
client.email_address = 'dchangstein@xyz.com'
client.orgname       = 'XYZ Corp'

response = account.add_client(client)

# Print the result of our action
puts response.message unless response.success?

Basically, class attribute names are the same for each object as specified in the API, except that where the API uses CamelCase, I’ve used underscores in an attempt to stick with Ruby coding conventions.

Modify a client

client.last_name = 'Chang'

account.modify_client(client)

Just in case your client relocates, or in Donna Changstein’s case, decides to masquerade as a Chinese woman.

Create an invoice

It turns out Ms. Chang has run up quite a tab. It’s time we bill her for our services.

invoice = Freshbooks::Invoice.new

invoice.username     = 'dchangstein' # same as the username above
invoice.date         = '2007-01-02'
invoice.po_number    = '123466444'
invoice.status       = 'pending'
invoice.total        = '44.00'
invoice.paid         = '0.00'
invoice.payment_date = '2007-01-13'

# Invoice addresses are actually a nested Freshbooks::Address object
invoice.address.address1 = '123 Main St'
invoice.address.city     = 'New York'

# Add some items
invoice.items << Freshbooks::Item.new( 
  :cost => 23.00, :qty => 1, :amount => 23.00 )

invoice.items << Freshbooks::Item.new(
  :cost => 10.50, :qty => 2, :amount => 21.00 )

response = account.add_invoice(invoice)

# Print the secure link to our newly created invoice
puts response.invoice.direct_link if response.success?

You’ll notice I’ve used a hash to initialize each of my item attributes. You can do this for invoices and clients too – perfect for your Rails applications.

invoice = Freshbooks::Invoice.new params[:invoice]

Invoice inquiry

response = account.invoice_inquiry(1)

if response.success?
  invoice = response.invoice

  # Output each item attached to this inquiry
  invoice.items.each { |item| puts item.name }
end

This is just a small display of the stuff you can do with the library. I’ve put up some rdoc-generated documentation, but you’ll benefit most by looking at the code and FreshBooks’ official API documentation to get the full score.

Any comments? Send them to the inaugural blog post.