WebService::Buxfer - Interact with the Buxfer webservice

      use strict;
      use warnings;
      use WebService::Buxfer;
      my $bux = WebService::Buxfer->new(
              userid => 'nheinrichs',                 # Required
              password => 'my password',              # Required
              preload_accounts => 1,                  # Default
              inject_account_name => 1,               # Default
              debug => 0,                             # Default
              url => '',    # Default
      my $results = $bux->transactions;
      print "Transaction: ".Dumper($_)."\n" for (@$results);
      my $new_transactions = [
          'coffee 5.45 tags:drinks,coffee',       # Raw, Buxfer SMS format
          'Pay check +6952.32 status:pending',    # Raw, Buxfer SMS format
          {                                       # As a hashref
              description => 'Thai food with friends',
              amount => -3000,
              payer => 'me',
              tags => ['sustenance, 'thai food'],
              account => 'cash',
              date => '2009-01-03',
              status => 'default',
              participants => [ [andy, 1000], elena ],
      my @responses = $bux->add_transactions($new_transactions);
      print "Response: ".($_->buxfer_status)."\n" for (@responses);

    Buxfer is an online personal finance site: <>

    WebService::Buxfer provides access to the Buxfer webservices API.

    * preload_accounts - Whether to prefetch account details on login
    * inject_account_name - Whether to automatically inject an 'accountName'
    field into results that contain an internal Buxfer 'accountId' field.
    * debug - Enable debug output
    * url - The URL of the Buxfer API server. You probably don't need to
    change this.
    * _response - The WebService::Buxfer::Response object from the last call
    * _token - The value of the authentication token received from Buxfer

  new( \%options )
    Build a new WebService::Buxfer instance.

  GET methods
   transactions(\%params), analysis(\%params)
    Retrieve transactions (25 at a time.)

    Results can be restricted using the following parameters (see Buxfer API
    documentation for details):

    * accountId OR accountName
    * tagId OR tagName
    * startDate AND endDate OR month: date can be specified as "10 feb
    2008", or "2008-02-10". month can be specified as "feb08", "feb 08", or
    "feb 2008".
    * budgetId OR budgetName
    * contactId OR contactName
    * groupId OR groupName
    * page - the page of results you want to see ("transactions" only)

    NOTE: On any given day the format of the 'date' field in the
    transactions seems to change (sometimes I get '3 Jan' and sometimes '3
    Jan 08'.)

    This package makes no attempt to format or inflate dates or any other
    information returned from the API.

    Get Analysis graph URLs and rawData.

    Takes the same parameters as "transactions".

    Returns a hashref of Analysis information.

    Retrieve Buxfer accounts.

    In array context returns an array of hashrefs containing account

    In scalar context returns a hashref of account details keyed on the
    internal Buxfer accountId.

    i.e., { $accountId => { name => 'cash', ... }, ... }

   impacts, tags, budgets, groups, contacts
    Calls the given Buxfer API. See Buxfer docs for details.

    In array context returns an array of results.

    In scalar context returns a reference to the array of results.

  POST methods
   add_transactions(\@transactions, \%params)
    Accepts an array of transactions in raw format or as hashrefs and
    submits them to Buxfer using the "add_transaction" API call.

    Because the Buxfer API allows for submission of multiple transactions in
    a single API call, this method will combine transactions into batches
    based on the "max_transactions_per_submit" parameter prior to

    WebService::Buxfer will also wrap tags containing spaces in single
    quotes. HOWEVER, the quotes themselves will also end up as part of the

    This is the fault of Buxfer's parser: if the single quotes are omitted,
    the system will fail to parse/import the transaction properly.


    * max_transactions_per_submit - I was able to submit 1000 transactions
    in a single call, so that is the default.
    * format - Currently only 'sms' is supported

    In array context returns an array of responses.

    In scalar context returns a reference to the responses array.

    * Buxfer - <>
    * Buxfer API Documentation - <>

    Move some of the logic out of here and into

    Add a pager for flipping through transactions based on 25 results per
    page and numTransactions in the response.

    Automatically in/deflate DateTime objects

    Portions of this package borrowed/adapted from the WebService::Solr

    Thanks to Brian Cassidy and Kirk Beers for that package.

    Nathaniel Heinrichs <>

     Copyright (c) 2009 Nathaniel Heinrichs.
     This program is free software; you can redistribute it and/or
     modify it under the same terms as Perl itself.