NAME
    Net::FreshBooks::API - Easy OO access to the FreshBooks.com API

VERSION
    version 0.23

SYNOPSIS
        use Net::FreshBooks::API;

        # Authenticate with OAuth (recommended)
        my $fb = Net::FreshBooks::API->new(
            {   consumer_key        => $consumer_key,       # your account_name
                consumer_secret     => $consumer_secret,
                access_token        => $access_token,
                access_token_secret => $access_token_secret,
                account_name        => $account_name,       # user's account name
            }
        );


        # Or, use auth_token and account_name supplied by 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 Net::FreshBooks::API::Base for other available methods, such as
    create, update, get, list and delete.

DESCRIPTION
    <http://www.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>

  OAUTH
    OAuth is the recommended method of authentication, but it can take a few
    days for FreshBooks to approve your OAuth application. In the meantime,
    you can get started right away by using an auth_token.

    Once your application has been approved, your consumer_key will be your
    FreshBooks account name and your consumer_key_secret will be provided to
    you by FreshBooks in your account. If you need to generate an
    access_token and access_token_secret, you can so so by running the
    oauth.pl script in the /examples directory which is included with this
    distribution.

METHODS
  new
    Create a new API object using OAuth:

        my $fb = Net::FreshBooks::API->new(
            {   consumer_key        => $consumer_key,       # same as account_name
                consumer_secret     => $consumer_secret,
                access_token        => $access_token,
                access_token_secret => $access_token_secret,
            }
        );

    Create a new API object the old (discouraged) way:

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

  client
    Returns a Net::FreshBooks::API::Client object.

  estimate
    Creates and returns a new Net::FreshBooks::API::Estimate object.

  gateway
    Creates and returns a new Net::FreshBooks::API::Gateway object.

  invoice
    Creates and returns a new Net::FreshBooks::API::Invoice object.

  language
    Creates and returns a new Net::FreshBooks::API::Language object.

  payment
    Creates and returns a new Net::FreshBooks::API::Payment object.

  recurring
    Creates and returns a new Net::FreshBooks::API::Recurring 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.

  verbose
    Setting verbose to a true value will allow you to inspect the XML which
    is being sent to FreshBooks

  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.

OAUTH METHODS
  OAUTH ACCESSOR/MUTATOR METHODS
    The following OAuth methods are getter/setter methods, which can
    optionally also be passed to new(). Required or optional is used in the
    context of OAuth connections. If you are not connecting via OAuth then
    you can safely ignore these options.

   account_name( $account_name )
    Required. Account name is the account name of the user who wishes to
    connect to your app.

    For example, if "acmeinc" is attempting to connect to your "widgets"
    app:

        # acme usually logs in via https://acmeinc.freshbooks.com
        $fb->account_name( 'acmeinc' );

   consumer_key( $consumer_key )
    Required. The consumer key will be provided to you by FreshBooks, but
    it's generally just the name of your account.

        # account name is "mycompany"
        # https://mycompany.freshbooks.com

        $fb->consumer_key( 'mycompany' );

    (In the case where you are logging in to your own app, consumer_key and
    account_name will have the same value.)

   consumer_secret( $secret )
    Required. The consumer_secret is provided to you by FreshBooks. You'll
    need to log in to your account to access it.

   access_token( $access_token )
    Optional. If you do not have an access_token, you'll need to acquire one
    with your code and then set this parameter before you request restricted
    URLs.

   access_token_secret( $access_token_secret )
    Optional. If you do not have an access_token_secret, you'll need to
    acquire one with your code and then set this parameter before you
    request restricted URLs.

   account_name_ok
    Returns true if $fb->account_name appears to be valid.

  OAUTH ACCESSOR METHODS
  oauth
    Returns a Net::FreshBooks::API::OAuth object. This is a subclass of
    Net::OAuth::Simple See Net::FreshBooks::API::OAuth as well as the
    scripts in the /examples folder of this distribution for use cases.

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

    The documentation is by no means complete. Feel free to look at the test
    files for more examples of usage.

    Up to this point, only clients, invoices and recurring items have been
    implemented, but other functionality may be added as needed. If you need
    other details, they should be very easy to add. Please get in touch.

AUTHOR CREDITS
    Edmund von der Burg "<evdb@ecclestoad.co.uk"> (Original Author)

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

    Recurring, Estimate and OAuth support by:

    Olaf Alders olaf@raybec.com

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

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

    <http://developers.freshbooks.com> the FreshBooks API documentation.

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

    *   Olaf Alders <olaf@wundercounter.com>

COPYRIGHT AND LICENSE
    This software is copyright (c) 2011 by Edmund von der Burg & Olaf
    Alders.

    This is free software; you can redistribute it and/or modify it under
    the same terms as the Perl 5 programming language system itself.

