NAME

Net::FreshBooks::API - easy OO access to the FreshBooks.com API

VERSION

Version 0.03

SYNOPSIS

    use Net::FreshBooks::API;

    # auth_token and account_name come from FreshBooks
    my $fb = Net::FreshBooks::API->new(
        {   auth_token   => $auth_token,
            account_name => $account_name,
        }
    );

    # create a new client
    my $client = $fb->client->create(
        {   first_name   => 'Larry',
            last_name    => 'Wall',
            organization => 'Perl HQ',
            email        => 'larry@example.com',
        }
    );

    # we can now make changes to the client and save them
    $client->organization('Perl Foundation');
    $client->update;

    # or more quickly
    $client->update( { organization => 'Perl Foundation', } );

    # create an invoice for this client
    my $invoice = $fb->invoice(
        {   client_id => $client->client_id,
            number    => '00001',
        }
    );

    # add a line to the invoice
    $invoice->add_line(
        {   name      => 'Hawaiian shirt consulting',
            unit_cost => 60,
            quantity  => 4,
        }
    );

    # save the invoice and then send it
    $invoice->create;
    $invoice->send_by_email;

    ############################################
    # create a recurring item
    ############################################

    use Net::FreshBooks::API;
    use Net::FreshBooks::API::InvoiceLine;
    use DateTime;

    # auth_token and account_name come from FreshBooks
    my $fb = Net::FreshBooks::API->new(
        {   auth_token   => $auth_token,
            account_name => $account_name,
        }
    );

    # find the first client returned
    my $client = $fb->client->list->next;

    # create a line item
    my $line = Net::FreshBooks::API::InvoiceLine->new({
        name         => "Widget",
        description  => "Net::FreshBooks::API Widget",
        unit_cost    => '1.99',
        quantity     => 1,
        tax1_name    => "GST",
        tax1_percent => 5,
    });

    # create the recurring item
    my $recurring_item = $fb->recurring->create({
        client_id   => $client->client_id,
        date        => DateTime->now->add( days => 2 )->ymd, # YYYY-MM-DD
        frequency   => 'monthly',
        lines       => [ $line ],
        notes       => 'Created by Net::FreshBooks::API',
    });

    $recurring_item->po_number( 999 );
    $recurring_item->update;

    See also L<Net::FreshBooks::API::Base> for other available methods, such
    as create, update, get, list and delete.

WARNING

This code is still under development - any and all patches most welcome.

Especially lacking is the documentation - for now you'd better look at the test file 't/live-test.t' for examples of usage.

Also I've only implemented the clients and invoices as they were all I needed. If you need other details they should be very easy to add - please get in touch.

DESCRIPTION

FreshBooks.com is a website that lets you create, send and manage invoices. This module is an OO abstraction of their API that lets you work with Clients, Invoices etc as if they were standard Perl objects.

Repository: http://github.com/oalders/net-freshbooks-api/tree/master

METHODS

new

    my $fb = Net::FreshBooks::API->new(
        {   account_name => 'account_name',
            auth_token   => '123...def',
        }
    );

Create a new API object.

ping

  my $bool = $fb->ping(  );

Ping the server with a trivial request to see if a connection can be made. Returns true if the server is reachable and the authentication details are valid.

service_url

  my $url = $fb->service_url(  );

Returns a URI object that represents the service URL.

client, invoice, payment, recurring

  my $client = $fb->client->create({...});

Accessor to the various objects in the API.

ua

  my $ua = $fb->ua;

Return a LWP::UserAgent object to use when contacting the server.

delete_everything_from_this_test_account

    my $deletion_count
        = $fb->delete_everything_from_this_test_account();

Deletes all clients, invoices and payments from this account. This is convenient when testing but potentially very dangerous. To prevent accidential deletions this method has a very long name, and will croak if the account name does not end with 'test'.

As a general rule it is best to put this at the start of your test scripts rather than at the end. This will let you inspect your account at the end of the test script to see what is left behind.

AUTHOR

Edmund von der Burg <evdb@ecclestoad.co.uk>

Developed for HinuHinu http://www.hinuhinu.com/.

Recurring item support by:

Olaf Alders olaf@raybec.com

Developed for Raybec Communications http://www.raybec.com

LICENCE

Perl

SEE ALSO

WWW::FreshBooks::API - an alternative interface to FreshBooks.

http://developers.freshbooks.com/overview/ the FreshBooks API documentation.

cpanm Net::FreshBooks::API

perl -MCPAN -e shell
install Net::FreshBooks::API