forked from oalders/net-freshbooks-api
-
Notifications
You must be signed in to change notification settings - Fork 0
/
README
293 lines (221 loc) · 9.57 KB
/
README
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
NAME
Net::FreshBooks::API - Easy OO access to the FreshBooks.com API
VERSION
version 0.24
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 => '[email protected]',
}
);
# 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 "<[email protected]"> (Original Author)
Developed for HinuHinu <http://www.hinuhinu.com/>.
Recurring, Estimate and OAuth support by:
Olaf Alders [email protected]
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 <[email protected]>
* Olaf Alders <[email protected]>
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.