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
38 =item insert_payment OPTION => VALUE, ...
40 Adds a new payment to a customers account. Takes a list of keys and values as
41 paramters with the following keys:
63 Option date for payment
69 my $result = FS::API->insert_payment(
70 'secret' => 'sharingiscaring',
76 '_date' => 1397977200, #UNIX timestamp
79 if ( $result->{'error'} ) {
80 die $result->{'error'};
83 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);
135 =item insert_credit OPTION => VALUE, ...
137 Adds a a credit to a customers account. Takes a list of keys and values as
138 parameters with the following keys
156 The date the credit will be posted
162 my $result = FS::API->insert_credit(
163 'secret' => 'sharingiscaring',
168 '_date' => 1397977200, #UNIX timestamp
171 if ( $result->{'error'} ) {
172 die $result->{'error'};
175 print "crednum ". $result->{'crednum'};
182 my($class, %opt) = @_;
183 my $conf = new FS::Conf;
184 return { 'error' => 'Incorrect shared secret' }
185 unless $opt{secret} eq $conf->config('api_shared_secret');
187 $opt{'reasonnum'} ||= $conf->config('api_credit_reason');
189 #less "raw" than this? we are the backoffice API, and aren't worried
190 # about version migration ala cust_main/cust_location here
191 my $cust_credit = new FS::cust_credit { %opt };
192 my $error = $cust_credit->insert;
193 return { 'error' => $error,
194 'crednum' => $cust_credit->crednum,
198 # pass the phone number ( from svc_phone )
199 sub insert_credit_phonenum {
200 my($class, %opt) = @_;
201 my $conf = new FS::Conf;
202 return { 'error' => 'Incorrect shared secret' }
203 unless $opt{secret} eq $conf->config('api_shared_secret');
205 $class->_by_phonenum('insert_credit', %opt);
209 =item insert_refund OPTION => VALUE, ...
211 Adds a a credit to a customers account. Takes a list of keys and values as
212 parmeters with the following keys: custnum, payby, refund
216 my $result = FS::API->insert_refund(
217 'secret' => 'sharingiscaring',
223 '_date' => 1397977200, #UNIX timestamp
226 if ( $result->{'error'} ) {
227 die $result->{'error'};
230 print "refundnum ". $result->{'crednum'};
237 my($class, %opt) = @_;
238 my $conf = new FS::Conf;
239 return { 'error' => 'Incorrect shared secret' }
240 unless $opt{secret} eq $conf->config('api_shared_secret');
242 # when github pull request #24 is merged,
243 # will have to change over to default reasonnum like credit
244 # but until then, this will do
245 $opt{'reason'} ||= 'API refund';
247 #less "raw" than this? we are the backoffice API, and aren't worried
248 # about version migration ala cust_main/cust_location here
249 my $cust_refund = new FS::cust_refund { %opt };
250 my $error = $cust_refund->insert;
251 return { 'error' => $error,
252 'refundnum' => $cust_refund->refundnum,
256 # pass the phone number ( from svc_phone )
257 sub insert_refund_phonenum {
258 my($class, %opt) = @_;
259 my $conf = new FS::Conf;
260 return { 'error' => 'Incorrect shared secret' }
261 unless $opt{secret} eq $conf->config('api_shared_secret');
263 $class->_by_phonenum('insert_refund', %opt);
269 # "2 way syncing" ? start with non-sync pulling info here, then if necessary
270 # figure out how to trigger something when those things change
272 # long-term: package changes?
274 =item new_customer OPTION => VALUE, ...
276 Creates a new customer. Takes a list of keys and values as parameters with the
287 first name (required)
295 (not typically collected; mostly used for ACH transactions)
301 =item address1 (required)
305 =item city (required)
313 =item state (required)
335 Currently used for third party tax vendor lookups
339 Used for determining FCC 477 reporting
343 Used for determining FCC 477 reporting
363 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),
365 Set to 1 to enable postal invoicing
369 CARD, DCRD, CHEK, DCHK, LECB, BILL, COMP or PREPAY
373 Card number for CARD/DCRD, account_number@aba_number for CHEK/DCHK, prepaid "pin" for PREPAY, purchase order number for BILL
377 Credit card CVV2 number (1.5+ or 1.4.2 with CVV schema patch)
381 Expiration date for CARD/DCRD
385 Exact name on credit card for CARD/DCRD, bank name for CHEK/DCHK
387 =item referral_custnum
389 Referring customer number
401 Agent specific customer number
403 =item referral_custnum
405 Referring customer number
411 #certainly false laziness w/ClientAPI::Signup new_customer/new_customer_minimal
412 # but approaching this from a clean start / back-office perspective
413 # i.e. no package/service, no immediate credit card run, etc.
416 my( $class, %opt ) = @_;
417 my $conf = new FS::Conf;
418 return { 'error' => 'Incorrect shared secret' }
419 unless $opt{secret} eq $conf->config('api_shared_secret');
421 #default agentnum like signup_server-default_agentnum?
423 #same for refnum like signup_server-default_refnum
425 my $cust_main = new FS::cust_main ( {
426 'agentnum' => $agentnum,
427 'refnum' => $opt{refnum}
428 || $conf->config('signup_server-default_refnum'),
430 'tagnum' => [ FS::part_tag->default_tags ],
432 map { $_ => $opt{$_} } qw(
433 agentnum salesnum refnum agent_custid referral_custnum
435 daytime night fax mobile
436 payby payinfo paydate paycvv payname
441 my @invoicing_list = $opt{'invoicing_list'}
442 ? split( /\s*\,\s*/, $opt{'invoicing_list'} )
444 push @invoicing_list, 'POST' if $opt{'postal_invoicing'};
446 my ($bill_hash, $ship_hash);
447 foreach my $f (FS::cust_main->location_fields) {
448 # avoid having to change this in front-end code
449 $bill_hash->{$f} = $opt{"bill_$f"} || $opt{$f};
450 $ship_hash->{$f} = $opt{"ship_$f"};
453 my $bill_location = FS::cust_location->new($bill_hash);
455 # we don't have an equivalent of the "same" checkbox in selfservice^Wthis API
456 # so is there a ship address, and if so, is it different from the billing
458 if ( length($ship_hash->{address1}) > 0 and
459 grep { $bill_hash->{$_} ne $ship_hash->{$_} } keys(%$ship_hash)
462 $ship_location = FS::cust_location->new( $ship_hash );
465 $ship_location = $bill_location;
468 $cust_main->set('bill_location' => $bill_location);
469 $cust_main->set('ship_location' => $ship_location);
471 $error = $cust_main->insert( {}, \@invoicing_list );
472 return { 'error' => $error } if $error;
474 return { 'error' => '',
475 'custnum' => $cust_main->custnum,
480 =item update_customer
481 Updates an existing customer. Passing an empty value clears that field, while NOT passing that key/value at all leaves it alone.
482 Takes a hash reference as parameter with the following keys:
488 API Secret (required)
492 Customer number (required)
548 comma-separated list of email addresses for email invoices. The special value '$
550 Set to 1 to enable postal invoicing
554 CARD, DCRD, CHEK, DCHK, LECB, BILL, COMP or PREPAY
558 Card number for CARD/DCRD, account_number@aba_number for CHEK/DCHK, prepaid "pi$
562 Credit card CVV2 number (1.5+ or 1.4.2 with CVV schema patch)
566 Expiration date for CARD/DCRD
570 Exact name on credit card for CARD/DCRD, bank name for CHEK/DCHK
572 =item referral_custnum
574 Referring customer number
588 sub update_customer {
590 my( $class, %opt ) = @_;
592 my $conf = new FS::Conf;
595 my $custnum = $opt{'custnum'}
596 or return { 'error' => "no customer record" };
598 my $cust_main = qsearchs('cust_main', { 'custnum' => $custnum } )
599 or return { 'error' => "unknown custnum $custnum" };
601 my $new = new FS::cust_main { $cust_main->hash };
603 $new->set( $_ => $opt{$_} )
604 foreach grep { exists $opt{$_} } qw(
605 agentnum salesnum refnum agent_custid referral_custnum
607 daytime night fax mobile
608 payby payinfo paydate paycvv payname
611 my @invoicing_list = $opt{'invoicing_list'}
612 ? split( /\s*\,\s*/, $opt{'invoicing_list'} )
613 : $cust_main->invoicing_list;
614 push @invoicing_list, 'POST' if $opt{'postal_invoicing'};
616 if ( exists( $opt{'address1'} ) ) {
617 my $bill_location = FS::cust_location->new({
618 map { $_ => $opt{$_} } @location_editable_fields
620 $bill_location->set('custnum' => $custnum);
621 my $error = $bill_location->find_or_insert;
622 die $error if $error;
624 # if this is unchanged from before, cust_main::replace will ignore it
625 $new->set('bill_location' => $bill_location);
628 if ( exists($opt{'ship_address1'}) ) {
629 my $ship_location = FS::cust_location->new({
630 map { $_ => $opt{"ship_$_"} } @location_editable_fields
633 $ship_location->set('custnum' => $custnum);
634 my $error = $ship_location->find_or_insert;
635 die $error if $error;
639 if ( !grep { length($opt{"ship_$_"}) } @location_editable_fields ) {
640 # Selfservice unfortunately tries to indicate "same as billing
641 # address" by sending all fields empty. Did this ever work?
643 my $ship_location = $cust_main->bill_location;
644 $new->set('ship_location' => $ship_location);
647 my $error = $new->replace( $cust_main, \@invoicing_list );
648 return { 'error' => $error } if $error;
650 return { 'error' => '',
657 Returns general customer information. Takes a list of keys and values as
658 parameters with the following keys: custnum, secret
662 #some false laziness w/ClientAPI::Myaccount customer_info/customer_info_short
664 use vars qw( @cust_main_editable_fields @location_editable_fields );
665 @cust_main_editable_fields = qw(
666 first last company daytime night fax mobile
669 # payby payinfo payname paystart_month paystart_year payissue payip
670 # ss paytype paystate stateid stateid_state
671 @location_editable_fields = qw(
672 address1 address2 city county state zip country
676 my( $class, %opt ) = @_;
677 my $conf = new FS::Conf;
678 return { 'error' => 'Incorrect shared secret' }
679 unless $opt{secret} eq $conf->config('api_shared_secret');
681 my $cust_main = qsearchs('cust_main', { 'custnum' => $opt{custnum} })
682 or return { 'error' => 'Unknown custnum' };
686 'display_custnum' => $cust_main->display_custnum,
687 'name' => $cust_main->first. ' '. $cust_main->get('last'),
688 'balance' => $cust_main->balance,
689 'status' => $cust_main->status,
690 'statuscolor' => $cust_main->statuscolor,
693 $return{$_} = $cust_main->get($_)
694 foreach @cust_main_editable_fields;
696 for (@location_editable_fields) {
697 $return{$_} = $cust_main->bill_location->get($_)
698 if $cust_main->bill_locationnum;
699 $return{'ship_'.$_} = $cust_main->ship_location->get($_)
700 if $cust_main->ship_locationnum;
703 my @invoicing_list = $cust_main->invoicing_list;
704 $return{'invoicing_list'} =
705 join(', ', grep { $_ !~ /^(POST|FAX)$/ } @invoicing_list );
706 $return{'postal_invoicing'} =
707 0 < ( grep { $_ eq 'POST' } @invoicing_list );
709 #generally, the more useful data from the cust_main record the better.
710 # well, tell me what you want
719 Returns location specific information for the customer. Takes a list of keys
720 and values as paramters with the following keys: custnum, secret
724 #I also monitor for changes to the additional locations that are applied to
725 # packages, and would like for those to be exportable as well. basically the
726 # location data passed with the custnum.
729 my( $class, %opt ) = @_;
730 my $conf = new FS::Conf;
731 return { 'error' => 'Incorrect shared secret' }
732 unless $opt{secret} eq $conf->config('api_shared_secret');
734 my @cust_location = qsearch('cust_location', { 'custnum' => $opt{custnum} });
738 'locations' => [ map $_->hashref, @cust_location ],
744 =item bill_now OPTION => VALUE, ...
746 Bills a single customer now, in the same fashion as the "Bill now" link in the
749 Returns a hash reference with a single key, 'error'. If there is an error,
750 the value contains the error, otherwise it is empty.
755 my( $class, %opt ) = @_;
756 my $conf = new FS::Conf;
757 return { 'error' => 'Incorrect shared secret' }
758 unless $opt{secret} eq $conf->config('api_shared_secret');
760 my $cust_main = qsearchs('cust_main', { 'custnum' => $opt{custnum} })
761 or return { 'error' => 'Unknown custnum' };
763 my $error = $cust_main->bill_and_collect( 'fatal' => 'return',
768 return { 'error' => $error,
774 #Advertising sources?