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.