4 use FS::Record qw( qsearch qsearchs );
13 FS::API - Freeside backend API
21 This module implements a backend API for advanced back-office integration.
23 In contrast to the self-service API, which authenticates an end-user and offers
24 functionality to that end user, the backend API performs a simple shared-secret
25 authentication and offers full, administrator functionality, enabling
26 integration with other back-office systems.
28 If accessing this API remotely with XML-RPC or JSON-RPC, be careful to block
29 the port by default, only allow access from back-office servers with the same
30 security precations as the Freeside server, and encrypt the communication
31 channel (for exampple, with an SSH tunnel or VPN) rather than accessing it
42 my $result = FS::API->insert_payment(
43 'secret' => 'sharingiscaring',
49 '_date' => 1397977200, #UNIX timestamp
52 if ( $result->{'error'} ) {
53 die $result->{'error'};
56 print "paynum ". $result->{'paynum'};
63 my($class, %opt) = @_;
64 my $conf = new FS::Conf;
65 return { 'error' => 'Incorrect shared secret' }
66 unless $opt{secret} eq $conf->config('api_shared_secret');
68 #less "raw" than this? we are the backoffice API, and aren't worried
69 # about version migration ala cust_main/cust_location here
70 my $cust_pay = new FS::cust_pay { %opt };
71 my $error = $cust_pay->insert( 'manual'=>1 );
72 return { 'error' => $error,
73 'paynum' => $cust_pay->paynum,
77 # pass the phone number ( from svc_phone )
78 sub insert_payment_phonenum {
79 my($class, %opt) = @_;
80 my $conf = new FS::Conf;
81 return { 'error' => 'Incorrect shared secret' }
82 unless $opt{secret} eq $conf->config('api_shared_secret');
84 $class->_by_phonenum('insert_payment', %opt);
89 my($class, $method, %opt) = @_;
90 my $conf = new FS::Conf;
91 return { 'error' => 'Incorrect shared secret' }
92 unless $opt{secret} eq $conf->config('api_shared_secret');
94 my $phonenum = delete $opt{'phonenum'};
96 my $svc_phone = qsearchs('svc_phone', { 'phonenum' => $phonenum } )
97 or return { 'error' => 'Unknown phonenum' };
99 my $cust_pkg = $svc_phone->cust_svc->cust_pkg
100 or return { 'error' => 'Unlinked phonenum' };
102 $opt{'custnum'} = $cust_pkg->custnum;
104 $class->$method(%opt);
112 my $result = FS::API->insert_credit(
113 'secret' => 'sharingiscaring',
118 '_date' => 1397977200, #UNIX timestamp
121 if ( $result->{'error'} ) {
122 die $result->{'error'};
125 print "crednum ". $result->{'crednum'};
132 my($class, %opt) = @_;
133 my $conf = new FS::Conf;
134 return { 'error' => 'Incorrect shared secret' }
135 unless $opt{secret} eq $conf->config('api_shared_secret');
137 $opt{'reasonnum'} ||= $conf->config('api_credit_reason');
139 #less "raw" than this? we are the backoffice API, and aren't worried
140 # about version migration ala cust_main/cust_location here
141 my $cust_credit = new FS::cust_credit { %opt };
142 my $error = $cust_credit->insert;
143 return { 'error' => $error,
144 'crednum' => $cust_credit->crednum,
148 # pass the phone number ( from svc_phone )
149 sub insert_credit_phonenum {
150 my($class, %opt) = @_;
151 my $conf = new FS::Conf;
152 return { 'error' => 'Incorrect shared secret' }
153 unless $opt{secret} eq $conf->config('api_shared_secret');
155 $class->_by_phonenum('insert_credit', %opt);
163 my $result = FS::API->insert_refund(
164 'secret' => 'sharingiscaring',
170 '_date' => 1397977200, #UNIX timestamp
173 if ( $result->{'error'} ) {
174 die $result->{'error'};
177 print "refundnum ". $result->{'crednum'};
184 my($class, %opt) = @_;
185 my $conf = new FS::Conf;
186 return { 'error' => 'Incorrect shared secret' }
187 unless $opt{secret} eq $conf->config('api_shared_secret');
189 # when github pull request #24 is merged,
190 # will have to change over to default reasonnum like credit
191 # but until then, this will do
192 $opt{'reason'} ||= 'API refund';
194 #less "raw" than this? we are the backoffice API, and aren't worried
195 # about version migration ala cust_main/cust_location here
196 my $cust_refund = new FS::cust_refund { %opt };
197 my $error = $cust_refund->insert;
198 return { 'error' => $error,
199 'refundnum' => $cust_refund->refundnum,
203 # pass the phone number ( from svc_phone )
204 sub insert_refund_phonenum {
205 my($class, %opt) = @_;
206 my $conf = new FS::Conf;
207 return { 'error' => 'Incorrect shared secret' }
208 unless $opt{secret} eq $conf->config('api_shared_secret');
210 $class->_by_phonenum('insert_refund', %opt);
216 # "2 way syncing" ? start with non-sync pulling info here, then if necessary
217 # figure out how to trigger something when those things change
219 # long-term: package changes?
225 #certainly false laziness w/ClientAPI::Signup new_customer/new_customer_minimal
226 # but approaching this from a clean start / back-office perspective
227 # i.e. no package/service, no immediate credit card run, etc.
230 my( $class, %opt ) = @_;
231 my $conf = new FS::Conf;
232 return { 'error' => 'Incorrect shared secret' }
233 unless $opt{secret} eq $conf->config('api_shared_secret');
235 #default agentnum like signup_server-default_agentnum?
237 #same for refnum like signup_server-default_refnum
239 my $cust_main = new FS::cust_main ( {
240 'agentnum' => $agentnum,
241 'refnum' => $opt{refnum}
242 || $conf->config('signup_server-default_refnum'),
245 map { $_ => $opt{$_} } qw(
246 agentnum refnum agent_custid referral_custnum
248 daytime night fax mobile
249 payby payinfo paydate paycvv payname
254 my @invoicing_list = $opt{'invoicing_list'}
255 ? split( /\s*\,\s*/, $opt{'invoicing_list'} )
257 push @invoicing_list, 'POST' if $opt{'postal_invoicing'};
259 my ($bill_hash, $ship_hash);
260 foreach my $f (FS::cust_main->location_fields) {
261 # avoid having to change this in front-end code
262 $bill_hash->{$f} = $opt{"bill_$f"} || $opt{$f};
263 $ship_hash->{$f} = $opt{"ship_$f"};
266 my $bill_location = FS::cust_location->new($bill_hash);
268 # we don't have an equivalent of the "same" checkbox in selfservice^Wthis API
269 # so is there a ship address, and if so, is it different from the billing
271 if ( length($ship_hash->{address1}) > 0 and
272 grep { $bill_hash->{$_} ne $ship_hash->{$_} } keys(%$ship_hash)
275 $ship_location = FS::cust_location->new( $ship_hash );
278 $ship_location = $bill_location;
281 $cust_main->set('bill_location' => $bill_location);
282 $cust_main->set('ship_location' => $ship_location);
284 $error = $cust_main->insert( {}, \@invoicing_list );
285 return { 'error' => $error } if $error;
287 return { 'error' => '',
288 'custnum' => $cust_main->custnum,
297 #some false laziness w/ClientAPI::Myaccount customer_info/customer_info_short
299 use vars qw( @cust_main_editable_fields @location_editable_fields );
300 @cust_main_editable_fields = qw(
301 first last company daytime night fax mobile
304 # payby payinfo payname paystart_month paystart_year payissue payip
305 # ss paytype paystate stateid stateid_state
306 @location_editable_fields = qw(
307 address1 address2 city county state zip country
311 my( $class, %opt ) = @_;
312 my $conf = new FS::Conf;
313 return { 'error' => 'Incorrect shared secret' }
314 unless $opt{secret} eq $conf->config('api_shared_secret');
316 my $cust_main = qsearchs('cust_main', { 'custnum' => $opt{custnum} })
317 or return { 'error' => 'Unknown custnum' };
321 'display_custnum' => $cust_main->display_custnum,
322 'name' => $cust_main->first. ' '. $cust_main->get('last'),
323 'balance' => $cust_main->balance,
324 'status' => $cust_main->status,
325 'statuscolor' => $cust_main->statuscolor,
328 $return{$_} = $cust_main->get($_)
329 foreach @cust_main_editable_fields;
331 for (@location_editable_fields) {
332 $return{$_} = $cust_main->bill_location->get($_)
333 if $cust_main->bill_locationnum;
334 $return{'ship_'.$_} = $cust_main->ship_location->get($_)
335 if $cust_main->ship_locationnum;
338 my @invoicing_list = $cust_main->invoicing_list;
339 $return{'invoicing_list'} =
340 join(', ', grep { $_ !~ /^(POST|FAX)$/ } @invoicing_list );
341 $return{'postal_invoicing'} =
342 0 < ( grep { $_ eq 'POST' } @invoicing_list );
344 #generally, the more useful data from the cust_main record the better.
345 # well, tell me what you want
351 #I also monitor for changes to the additional locations that are applied to
352 # packages, and would like for those to be exportable as well. basically the
353 # location data passed with the custnum.
355 my( $class, %opt ) = @_;
356 my $conf = new FS::Conf;
357 return { 'error' => 'Incorrect shared secret' }
358 unless $opt{secret} eq $conf->config('api_shared_secret');
360 my @cust_location = qsearch('cust_location', { 'custnum' => $opt{custnum} });
364 'locations' => [ map $_->hashref, @cust_location ],
370 #Advertising sources?