1NAME
2 Net::FreshBooks::API - Easy OO access to the FreshBooks.com API
3
4VERSION
5 version 0.24
6
7SYNOPSIS
8 use Net::FreshBooks::API;
9
10 # Authenticate with OAuth (recommended)
11 my $fb = Net::FreshBooks::API->new(
12 { consumer_key => $consumer_key, # your account_name
13 consumer_secret => $consumer_secret,
14 access_token => $access_token,
15 access_token_secret => $access_token_secret,
16 account_name => $account_name, # user's account name
17 }
18 );
19
20
21 # Or, use auth_token and account_name supplied by FreshBooks
22 my $fb = Net::FreshBooks::API->new(
23 { auth_token => $auth_token,
24 account_name => $account_name,
25 }
26 );
27
28 # create a new client
29 my $client = $fb->client->create(
30 { first_name => 'Larry',
31 last_name => 'Wall',
32 organization => 'Perl HQ',
33 email => 'larry@example.com',
34 }
35 );
36
37 # we can now make changes to the client and save them
38 $client->organization( 'Perl Foundation' );
39 $client->update;
40
41 # or more quickly
42 $client->update( { organization => 'Perl Foundation', } );
43
44 # create an invoice for this client
45 my $invoice = $fb->invoice(
46 { client_id => $client->client_id,
47 number => '00001',
48 }
49 );
50
51 # add a line to the invoice
52 $invoice->add_line(
53 { name => 'Hawaiian shirt consulting',
54 unit_cost => 60,
55 quantity => 4,
56 }
57 );
58
59 # save the invoice and then send it
60 $invoice->create;
61 $invoice->send_by_email;
62
63 ############################################
64 # create a recurring item
65 ############################################
66
67 use Net::FreshBooks::API;
68 use Net::FreshBooks::API::InvoiceLine;
69 use DateTime;
70
71 # auth_token and account_name come from FreshBooks
72 my $fb = Net::FreshBooks::API->new(
73 { auth_token => $auth_token,
74 account_name => $account_name,
75 }
76 );
77
78 # find the first client returned
79 my $client = $fb->client->list->next;
80
81 # create a line item
82 my $line = Net::FreshBooks::API::InvoiceLine->new(
83 { name => "Widget",
84 description => "Net::FreshBooks::API Widget",
85 unit_cost => '1.99',
86 quantity => 1,
87 tax1_name => "GST",
88 tax1_percent => 5,
89 }
90 );
91
92 # create the recurring item
93 my $recurring_item = $fb->recurring->create(
94 { client_id => $client->client_id,
95 date => DateTime->now->add( days => 2 )->ymd, # YYYY-MM-DD
96 frequency => 'monthly',
97 lines => [$line],
98 notes => 'Created by Net::FreshBooks::API',
99 }
100 );
101
102 $recurring_item->po_number( 999 );
103 $recurring_item->update;
104
105 See also Net::FreshBooks::API::Base for other available methods, such as
106 create, update, get, list and delete.
107
108DESCRIPTION
109 <http://www.freshbooks.com> is a website that lets you create, send and
110 manage invoices. This module is an OO abstraction of their API that lets
111 you work with Clients, Invoices etc as if they were standard Perl
112 objects.
113
114 Repository: <http://github.com/oalders/net-freshbooks-api/tree/master>
115
116 OAUTH
117 OAuth is the recommended method of authentication, but it can take a few
118 days for FreshBooks to approve your OAuth application. In the meantime,
119 you can get started right away by using an auth_token.
120
121 Once your application has been approved, your consumer_key will be your
122 FreshBooks account name and your consumer_key_secret will be provided to
123 you by FreshBooks in your account. If you need to generate an
124 access_token and access_token_secret, you can so so by running the
125 oauth.pl script in the /examples directory which is included with this
126 distribution.
127
128METHODS
129 new
130 Create a new API object using OAuth:
131
132 my $fb = Net::FreshBooks::API->new(
133 { consumer_key => $consumer_key, # same as account_name
134 consumer_secret => $consumer_secret,
135 access_token => $access_token,
136 access_token_secret => $access_token_secret,
137 }
138 );
139
140 Create a new API object the old (discouraged) way:
141
142 # auth_token and account_name come from FreshBooks
143 my $fb = Net::FreshBooks::API->new(
144 { auth_token => $auth_token,
145 account_name => $account_name,
146 }
147 );
148
149 client
150 Returns a Net::FreshBooks::API::Client object.
151
152 estimate
153 Creates and returns a new Net::FreshBooks::API::Estimate object.
154
155 gateway
156 Creates and returns a new Net::FreshBooks::API::Gateway object.
157
158 invoice
159 Creates and returns a new Net::FreshBooks::API::Invoice object.
160
161 language
162 Creates and returns a new Net::FreshBooks::API::Language object.
163
164 payment
165 Creates and returns a new Net::FreshBooks::API::Payment object.
166
167 recurring
168 Creates and returns a new Net::FreshBooks::API::Recurring object.
169
170 ping
171 my $bool = $fb->ping( );
172
173 Ping the server with a trivial request to see if a connection can be
174 made. Returns true if the server is reachable and the authentication
175 details are valid.
176
177 service_url
178 my $url = $fb->service_url( );
179
180 Returns a URI object that represents the service URL.
181
182 verbose
183 Setting verbose to a true value will allow you to inspect the XML which
184 is being sent to FreshBooks
185
186 ua
187 my $ua = $fb->ua;
188
189 Return a LWP::UserAgent object to use when contacting the server.
190
191 delete_everything_from_this_test_account
192 my $deletion_count
193 = $fb->delete_everything_from_this_test_account();
194
195 Deletes all clients, invoices and payments from this account. This is
196 convenient when testing but potentially very dangerous. To prevent
197 accidential deletions this method has a very long name, and will croak
198 if the account name does not end with 'test'.
199
200 As a general rule it is best to put this at the start of your test
201 scripts rather than at the end. This will let you inspect your account
202 at the end of the test script to see what is left behind.
203
204OAUTH METHODS
205 OAUTH ACCESSOR/MUTATOR METHODS
206 The following OAuth methods are getter/setter methods, which can
207 optionally also be passed to new(). Required or optional is used in the
208 context of OAuth connections. If you are not connecting via OAuth then
209 you can safely ignore these options.
210
211 account_name( $account_name )
212 Required. Account name is the account name of the user who wishes to
213 connect to your app.
214
215 For example, if "acmeinc" is attempting to connect to your "widgets"
216 app:
217
218 # acme usually logs in via https://acmeinc.freshbooks.com
219 $fb->account_name( 'acmeinc' );
220
221 consumer_key( $consumer_key )
222 Required. The consumer key will be provided to you by FreshBooks, but
223 it's generally just the name of your account.
224
225 # account name is "mycompany"
226 # https://mycompany.freshbooks.com
227
228 $fb->consumer_key( 'mycompany' );
229
230 (In the case where you are logging in to your own app, consumer_key and
231 account_name will have the same value.)
232
233 consumer_secret( $secret )
234 Required. The consumer_secret is provided to you by FreshBooks. You'll
235 need to log in to your account to access it.
236
237 access_token( $access_token )
238 Optional. If you do not have an access_token, you'll need to acquire one
239 with your code and then set this parameter before you request restricted
240 URLs.
241
242 access_token_secret( $access_token_secret )
243 Optional. If you do not have an access_token_secret, you'll need to
244 acquire one with your code and then set this parameter before you
245 request restricted URLs.
246
247 account_name_ok
248 Returns true if $fb->account_name appears to be valid.
249
250 OAUTH ACCESSOR METHODS
251 oauth
252 Returns a Net::FreshBooks::API::OAuth object. This is a subclass of
253 Net::OAuth::Simple See Net::FreshBooks::API::OAuth as well as the
254 scripts in the /examples folder of this distribution for use cases.
255
256WARNING
257 This code is still under development - any and all patches most welcome.
258
259 The documentation is by no means complete. Feel free to look at the test
260 files for more examples of usage.
261
262 Up to this point, only clients, invoices and recurring items have been
263 implemented, but other functionality may be added as needed. If you need
264 other details, they should be very easy to add. Please get in touch.
265
266AUTHOR CREDITS
267 Edmund von der Burg "<evdb@ecclestoad.co.uk"> (Original Author)
268
269 Developed for HinuHinu <http://www.hinuhinu.com/>.
270
271 Recurring, Estimate and OAuth support by:
272
273 Olaf Alders olaf@raybec.com
274
275 Developed for Raybec Communications <http://www.raybec.com>
276
277SEE ALSO
278 WWW::FreshBooks::API - an alternative interface to FreshBooks.
279
280 <http://developers.freshbooks.com> the FreshBooks API documentation.
281
282AUTHORS
283 * Edmund von der Burg <evdb@ecclestoad.co.uk>
284
285 * Olaf Alders <olaf@wundercounter.com>
286
287COPYRIGHT AND LICENSE
288 This software is copyright (c) 2011 by Edmund von der Burg & Olaf
289 Alders.
290
291 This is free software; you can redistribute it and/or modify it under
292 the same terms as the Perl 5 programming language system itself.
293
294