5 use FS::Record qw( qsearch qsearchs );
14 FS::API - Freeside backend API
22 This module implements a backend API for advanced back-office integration.
24 In contrast to the self-service API, which authenticates an end-user and offers
25 functionality to that end user, the backend API performs a simple shared-secret
26 authentication and offers full, administrator functionality, enabling
27 integration with other back-office systems.
29 If accessing this API remotely with XML-RPC or JSON-RPC, be careful to block
30 the port by default, only allow access from back-office servers with the same
31 security precations as the Freeside server, and encrypt the communication
32 channel (for example, with an SSH tunnel or VPN) rather than accessing it
39 =item insert_payment OPTION => VALUE, ...
41 Adds a new payment to a customers account. Takes a list of keys and values as
42 paramters with the following keys:
64 Option date for payment
70 my $result = FS::API->insert_payment(
71 'secret' => 'sharingiscaring',
77 '_date' => 1397977200, #UNIX timestamp
80 if ( $result->{'error'} ) {
81 die $result->{'error'};
84 print "paynum ". $result->{'paynum'};
91 my($class, %opt) = @_;
92 my $conf = new FS::Conf;
93 return { 'error' => 'Incorrect shared secret' }
94 unless $opt{secret} eq $conf->config('api_shared_secret');
96 #less "raw" than this? we are the backoffice API, and aren't worried
97 # about version migration ala cust_main/cust_location here
98 my $cust_pay = new FS::cust_pay { %opt };
99 my $error = $cust_pay->insert( 'manual'=>1 );
100 return { 'error' => $error,
101 'paynum' => $cust_pay->paynum,
105 # pass the phone number ( from svc_phone )
106 sub insert_payment_phonenum {
107 my($class, %opt) = @_;
108 my $conf = new FS::Conf;
109 return { 'error' => 'Incorrect shared secret' }
110 unless $opt{secret} eq $conf->config('api_shared_secret');
112 $class->_by_phonenum('insert_payment', %opt);
117 my($class, $method, %opt) = @_;
118 my $conf = new FS::Conf;
119 return { 'error' => 'Incorrect shared secret' }
120 unless $opt{secret} eq $conf->config('api_shared_secret');
122 my $phonenum = delete $opt{'phonenum'};
124 my $svc_phone = qsearchs('svc_phone', { 'phonenum' => $phonenum } )
125 or return { 'error' => 'Unknown phonenum' };
127 my $cust_pkg = $svc_phone->cust_svc->cust_pkg
128 or return { 'error' => 'Unlinked phonenum' };
130 $opt{'custnum'} = $cust_pkg->custnum;
132 $class->$method(%opt);
136 =item insert_credit OPTION => VALUE, ...
138 Adds a a credit to a customers account. Takes a list of keys and values as
139 parameters with the following keys
157 The date the credit will be posted
163 my $result = FS::API->insert_credit(
164 'secret' => 'sharingiscaring',
169 '_date' => 1397977200, #UNIX timestamp
172 if ( $result->{'error'} ) {
173 die $result->{'error'};
176 print "crednum ". $result->{'crednum'};
183 my($class, %opt) = @_;
184 my $conf = new FS::Conf;
185 return { 'error' => 'Incorrect shared secret' }
186 unless $opt{secret} eq $conf->config('api_shared_secret');
188 $opt{'reasonnum'} ||= $conf->config('api_credit_reason');
190 #less "raw" than this? we are the backoffice API, and aren't worried
191 # about version migration ala cust_main/cust_location here
192 my $cust_credit = new FS::cust_credit { %opt };
193 my $error = $cust_credit->insert;
194 return { 'error' => $error,
195 'crednum' => $cust_credit->crednum,
199 # pass the phone number ( from svc_phone )
200 sub insert_credit_phonenum {
201 my($class, %opt) = @_;
202 my $conf = new FS::Conf;
203 return { 'error' => 'Incorrect shared secret' }
204 unless $opt{secret} eq $conf->config('api_shared_secret');
206 $class->_by_phonenum('insert_credit', %opt);
210 =item insert_refund OPTION => VALUE, ...
212 Adds a a credit to a customers account. Takes a list of keys and values as
213 parmeters with the following keys: custnum, payby, refund
217 my $result = FS::API->insert_refund(
218 'secret' => 'sharingiscaring',
224 '_date' => 1397977200, #UNIX timestamp
227 if ( $result->{'error'} ) {
228 die $result->{'error'};
231 print "refundnum ". $result->{'crednum'};
238 my($class, %opt) = @_;
239 my $conf = new FS::Conf;
240 return { 'error' => 'Incorrect shared secret' }
241 unless $opt{secret} eq $conf->config('api_shared_secret');
243 # when github pull request #24 is merged,
244 # will have to change over to default reasonnum like credit
245 # but until then, this will do
246 $opt{'reason'} ||= 'API refund';
248 #less "raw" than this? we are the backoffice API, and aren't worried
249 # about version migration ala cust_main/cust_location here
250 my $cust_refund = new FS::cust_refund { %opt };
251 my $error = $cust_refund->insert;
252 return { 'error' => $error,
253 'refundnum' => $cust_refund->refundnum,
257 # pass the phone number ( from svc_phone )
258 sub insert_refund_phonenum {
259 my($class, %opt) = @_;
260 my $conf = new FS::Conf;
261 return { 'error' => 'Incorrect shared secret' }
262 unless $opt{secret} eq $conf->config('api_shared_secret');
264 $class->_by_phonenum('insert_refund', %opt);
270 # "2 way syncing" ? start with non-sync pulling info here, then if necessary
271 # figure out how to trigger something when those things change
273 # long-term: package changes?
275 =item new_customer OPTION => VALUE, ...
277 Creates a new customer. Takes a list of keys and values as parameters with the
288 first name (required)
296 (not typically collected; mostly used for ACH transactions)
302 =item address1 (required)
306 =item city (required)
314 =item state (required)
336 Currently used for third party tax vendor lookups
340 Used for determining FCC 477 reporting
344 Used for determining FCC 477 reporting
364 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),
366 Set to 1 to enable postal invoicing
370 CARD, DCRD, CHEK, DCHK, LECB, BILL, COMP or PREPAY
374 Card number for CARD/DCRD, account_number@aba_number for CHEK/DCHK, prepaid "pin" for PREPAY, purchase order number for BILL
378 Credit card CVV2 number (1.5+ or 1.4.2 with CVV schema patch)
382 Expiration date for CARD/DCRD
386 Exact name on credit card for CARD/DCRD, bank name for CHEK/DCHK
388 =item referral_custnum
390 Referring customer number
402 Agent specific customer number
404 =item referral_custnum
406 Referring customer number
412 #certainly false laziness w/ClientAPI::Signup new_customer/new_customer_minimal
413 # but approaching this from a clean start / back-office perspective
414 # i.e. no package/service, no immediate credit card run, etc.
417 my( $class, %opt ) = @_;
419 my $conf = new FS::Conf;
420 return { 'error' => 'Incorrect shared secret' }
421 unless $opt{secret} eq $conf->config('api_shared_secret');
423 #default agentnum like signup_server-default_agentnum?
424 #$opt{agentnum} ||= $conf->config('signup_server-default_agentnum');
426 #same for refnum like signup_server-default_refnum
427 $opt{refnum} ||= $conf->config('signup_server-default_refnum');
429 $class->API_insert( %opt );
432 =item update_customer
434 Updates an existing customer. Passing an empty value clears that field, while
435 NOT passing that key/value at all leaves it alone. Takes a list of keys and
436 values as parameters with the following keys:
442 API Secret (required)
446 Customer number (required)
502 Comma-separated list of email addresses for email invoices. The special value
503 'POST' is used to designate postal invoicing (it may be specified alone or in
504 addition to email addresses),
506 Set to 1 to enable postal invoicing
510 CARD, DCRD, CHEK, DCHK, LECB, BILL, COMP or PREPAY
514 Card number for CARD/DCRD, account_number@aba_number for CHEK/DCHK, prepaid
515 "pin" for PREPAY, purchase order number for BILL
519 Credit card CVV2 number (1.5+ or 1.4.2 with CVV schema patch)
523 Expiration date for CARD/DCRD
527 Exact name on credit card for CARD/DCRD, bank name for CHEK/DCHK
529 =item referral_custnum
531 Referring customer number
545 sub update_customer {
546 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 FS::cust_main->API_update( %opt );
555 =item customer_info OPTION => VALUE, ...
557 Returns general customer information. Takes a list of keys and values as
558 parameters with the following keys: custnum, secret
563 my( $class, %opt ) = @_;
564 my $conf = new FS::Conf;
565 return { 'error' => 'Incorrect shared secret' }
566 unless $opt{secret} eq $conf->config('api_shared_secret');
568 my $cust_main = qsearchs('cust_main', { 'custnum' => $opt{custnum} })
569 or return { 'error' => 'Unknown custnum' };
571 $cust_main->API_getinfo;
576 Returns location specific information for the customer. Takes a list of keys
577 and values as paramters with the following keys: custnum, secret
581 #I also monitor for changes to the additional locations that are applied to
582 # packages, and would like for those to be exportable as well. basically the
583 # location data passed with the custnum.
586 my( $class, %opt ) = @_;
587 my $conf = new FS::Conf;
588 return { 'error' => 'Incorrect shared secret' }
589 unless $opt{secret} eq $conf->config('api_shared_secret');
591 my @cust_location = qsearch('cust_location', { 'custnum' => $opt{custnum} });
595 'locations' => [ map $_->hashref, @cust_location ],
601 =item bill_now OPTION => VALUE, ...
603 Bills a single customer now, in the same fashion as the "Bill now" link in the
606 Returns a hash reference with a single key, 'error'. If there is an error,
607 the value contains the error, otherwise it is empty. Takes a list of keys and
608 values as parameters with the following keys:
614 API Secret (required)
618 Customer number (required)
625 my( $class, %opt ) = @_;
626 my $conf = new FS::Conf;
627 return { 'error' => 'Incorrect shared secret' }
628 unless $opt{secret} eq $conf->config('api_shared_secret');
630 my $cust_main = qsearchs('cust_main', { 'custnum' => $opt{custnum} })
631 or return { 'error' => 'Unknown custnum' };
633 my $error = $cust_main->bill_and_collect( 'fatal' => 'return',
638 return { 'error' => $error,
644 #Advertising sources?