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 example, with an SSH tunnel or VPN) rather than accessing it
40 Adds a new payment to a customers account. Takes a hash reference as parameter with the following keys:
63 Option date for payment
67 my $result = FS::API->insert_payment(
68 'secret' => 'sharingiscaring',
74 '_date' => 1397977200, #UNIX timestamp
77 if ( $result->{'error'} ) {
78 die $result->{'error'};
81 print "paynum ". $result->{'paynum'};
90 my($class, %opt) = @_;
91 my $conf = new FS::Conf;
92 return { 'error' => 'Incorrect shared secret' }
93 unless $opt{secret} eq $conf->config('api_shared_secret');
95 #less "raw" than this? we are the backoffice API, and aren't worried
96 # about version migration ala cust_main/cust_location here
97 my $cust_pay = new FS::cust_pay { %opt };
98 my $error = $cust_pay->insert( 'manual'=>1 );
99 return { 'error' => $error,
100 'paynum' => $cust_pay->paynum,
104 # pass the phone number ( from svc_phone )
105 sub insert_payment_phonenum {
106 my($class, %opt) = @_;
107 my $conf = new FS::Conf;
108 return { 'error' => 'Incorrect shared secret' }
109 unless $opt{secret} eq $conf->config('api_shared_secret');
111 $class->_by_phonenum('insert_payment', %opt);
116 my($class, $method, %opt) = @_;
117 my $conf = new FS::Conf;
118 return { 'error' => 'Incorrect shared secret' }
119 unless $opt{secret} eq $conf->config('api_shared_secret');
121 my $phonenum = delete $opt{'phonenum'};
123 my $svc_phone = qsearchs('svc_phone', { 'phonenum' => $phonenum } )
124 or return { 'error' => 'Unknown phonenum' };
126 my $cust_pkg = $svc_phone->cust_svc->cust_pkg
127 or return { 'error' => 'Unlinked phonenum' };
129 $opt{'custnum'} = $cust_pkg->custnum;
131 $class->$method(%opt);
137 Adds a a credit to a customers account. Takes a hash reference as parameter with the following keys
155 The date the credit will be posted
159 my $result = FS::API->insert_credit(
160 'secret' => 'sharingiscaring',
165 '_date' => 1397977200, #UNIX timestamp
168 if ( $result->{'error'} ) {
169 die $result->{'error'};
172 print "crednum ". $result->{'crednum'};
181 my($class, %opt) = @_;
182 my $conf = new FS::Conf;
183 return { 'error' => 'Incorrect shared secret' }
184 unless $opt{secret} eq $conf->config('api_shared_secret');
186 $opt{'reasonnum'} ||= $conf->config('api_credit_reason');
188 #less "raw" than this? we are the backoffice API, and aren't worried
189 # about version migration ala cust_main/cust_location here
190 my $cust_credit = new FS::cust_credit { %opt };
191 my $error = $cust_credit->insert;
192 return { 'error' => $error,
193 'crednum' => $cust_credit->crednum,
197 # pass the phone number ( from svc_phone )
198 sub insert_credit_phonenum {
199 my($class, %opt) = @_;
200 my $conf = new FS::Conf;
201 return { 'error' => 'Incorrect shared secret' }
202 unless $opt{secret} eq $conf->config('api_shared_secret');
204 $class->_by_phonenum('insert_credit', %opt);
210 Adds a a credit to a customers account. Takes a hash reference as parameter with the following keys: custnum,payby,refund
214 my $result = FS::API->insert_refund(
215 'secret' => 'sharingiscaring',
221 '_date' => 1397977200, #UNIX timestamp
224 if ( $result->{'error'} ) {
225 die $result->{'error'};
228 print "refundnum ". $result->{'crednum'};
235 my($class, %opt) = @_;
236 my $conf = new FS::Conf;
237 return { 'error' => 'Incorrect shared secret' }
238 unless $opt{secret} eq $conf->config('api_shared_secret');
240 # when github pull request #24 is merged,
241 # will have to change over to default reasonnum like credit
242 # but until then, this will do
243 $opt{'reason'} ||= 'API refund';
245 #less "raw" than this? we are the backoffice API, and aren't worried
246 # about version migration ala cust_main/cust_location here
247 my $cust_refund = new FS::cust_refund { %opt };
248 my $error = $cust_refund->insert;
249 return { 'error' => $error,
250 'refundnum' => $cust_refund->refundnum,
254 # pass the phone number ( from svc_phone )
255 sub insert_refund_phonenum {
256 my($class, %opt) = @_;
257 my $conf = new FS::Conf;
258 return { 'error' => 'Incorrect shared secret' }
259 unless $opt{secret} eq $conf->config('api_shared_secret');
261 $class->_by_phonenum('insert_refund', %opt);
267 # "2 way syncing" ? start with non-sync pulling info here, then if necessary
268 # figure out how to trigger something when those things change
270 # long-term: package changes?
274 Creates a new customer. Takes a hash reference as parameter with the following keys:
284 first name (required)
292 (not typically collected; mostly used for ACH transactions)
298 =item address1 (required)
302 =item city (required)
310 =item state (required)
332 Currently used for third party tax vendor lookups
336 Used for determining FCC 477 reporting
340 Used for determining FCC 477 reporting
360 comma-separated list of email addresses for email invoices. The special value 'POST' is used to designate postal invoicing (it may be specified alone or in addition to email addresses),
362 Set to 1 to enable postal invoicing
366 CARD, DCRD, CHEK, DCHK, LECB, BILL, COMP or PREPAY
370 Card number for CARD/DCRD, account_number@aba_number for CHEK/DCHK, prepaid "pin" for PREPAY, purchase order number for BILL
374 Credit card CVV2 number (1.5+ or 1.4.2 with CVV schema patch)
378 Expiration date for CARD/DCRD
382 Exact name on credit card for CARD/DCRD, bank name for CHEK/DCHK
384 =item referral_custnum
386 referring customer number
394 Agent specific customer number
396 =item referral_custnum
398 Referring customer number
403 #certainly false laziness w/ClientAPI::Signup new_customer/new_customer_minimal
404 # but approaching this from a clean start / back-office perspective
405 # i.e. no package/service, no immediate credit card run, etc.
408 my( $class, %opt ) = @_;
409 my $conf = new FS::Conf;
410 return { 'error' => 'Incorrect shared secret' }
411 unless $opt{secret} eq $conf->config('api_shared_secret');
413 #default agentnum like signup_server-default_agentnum?
415 #same for refnum like signup_server-default_refnum
417 my $cust_main = new FS::cust_main ( {
418 'agentnum' => $agentnum,
419 'refnum' => $opt{refnum}
420 || $conf->config('signup_server-default_refnum'),
423 map { $_ => $opt{$_} } qw(
424 agentnum refnum agent_custid referral_custnum
426 daytime night fax mobile
427 payby payinfo paydate paycvv payname
432 my @invoicing_list = $opt{'invoicing_list'}
433 ? split( /\s*\,\s*/, $opt{'invoicing_list'} )
435 push @invoicing_list, 'POST' if $opt{'postal_invoicing'};
437 my ($bill_hash, $ship_hash);
438 foreach my $f (FS::cust_main->location_fields) {
439 # avoid having to change this in front-end code
440 $bill_hash->{$f} = $opt{"bill_$f"} || $opt{$f};
441 $ship_hash->{$f} = $opt{"ship_$f"};
444 my $bill_location = FS::cust_location->new($bill_hash);
446 # we don't have an equivalent of the "same" checkbox in selfservice^Wthis API
447 # so is there a ship address, and if so, is it different from the billing
449 if ( length($ship_hash->{address1}) > 0 and
450 grep { $bill_hash->{$_} ne $ship_hash->{$_} } keys(%$ship_hash)
453 $ship_location = FS::cust_location->new( $ship_hash );
456 $ship_location = $bill_location;
459 $cust_main->set('bill_location' => $bill_location);
460 $cust_main->set('ship_location' => $ship_location);
462 $error = $cust_main->insert( {}, \@invoicing_list );
463 return { 'error' => $error } if $error;
465 return { 'error' => '',
466 'custnum' => $cust_main->custnum,
475 Returns general customer information. Takes a hash reference as parameter with the following keys: custnum and API secret
479 #some false laziness w/ClientAPI::Myaccount customer_info/customer_info_short
481 use vars qw( @cust_main_editable_fields @location_editable_fields );
482 @cust_main_editable_fields = qw(
483 first last company daytime night fax mobile
486 # payby payinfo payname paystart_month paystart_year payissue payip
487 # ss paytype paystate stateid stateid_state
488 @location_editable_fields = qw(
489 address1 address2 city county state zip country
493 my( $class, %opt ) = @_;
494 my $conf = new FS::Conf;
495 return { 'error' => 'Incorrect shared secret' }
496 unless $opt{secret} eq $conf->config('api_shared_secret');
498 my $cust_main = qsearchs('cust_main', { 'custnum' => $opt{custnum} })
499 or return { 'error' => 'Unknown custnum' };
503 'display_custnum' => $cust_main->display_custnum,
504 'name' => $cust_main->first. ' '. $cust_main->get('last'),
505 'balance' => $cust_main->balance,
506 'status' => $cust_main->status,
507 'statuscolor' => $cust_main->statuscolor,
510 $return{$_} = $cust_main->get($_)
511 foreach @cust_main_editable_fields;
513 for (@location_editable_fields) {
514 $return{$_} = $cust_main->bill_location->get($_)
515 if $cust_main->bill_locationnum;
516 $return{'ship_'.$_} = $cust_main->ship_location->get($_)
517 if $cust_main->ship_locationnum;
520 my @invoicing_list = $cust_main->invoicing_list;
521 $return{'invoicing_list'} =
522 join(', ', grep { $_ !~ /^(POST|FAX)$/ } @invoicing_list );
523 $return{'postal_invoicing'} =
524 0 < ( grep { $_ eq 'POST' } @invoicing_list );
526 #generally, the more useful data from the cust_main record the better.
527 # well, tell me what you want
536 Returns location specific information for the customer. Takes a hash reference as parameter with the following keys: custnum,secret
542 #I also monitor for changes to the additional locations that are applied to
543 # packages, and would like for those to be exportable as well. basically the
544 # location data passed with the custnum.
547 my( $class, %opt ) = @_;
548 my $conf = new FS::Conf;
549 return { 'error' => 'Incorrect shared secret' }
550 unless $opt{secret} eq $conf->config('api_shared_secret');
552 my @cust_location = qsearch('cust_location', { 'custnum' => $opt{custnum} });
556 'locations' => [ map $_->hashref, @cust_location ],
562 #Advertising sources?