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. Only access this API from a secure
28 network from other backoffice machines. DON'T use this API to create customer
31 If accessing this API remotely with XML-RPC or JSON-RPC, be careful to block
32 the port by default, only allow access from back-office servers with the same
33 security precations as the Freeside server, and encrypt the communication
34 channel (for example, with an SSH tunnel or VPN) rather than accessing it
41 =item insert_payment OPTION => VALUE, ...
43 Adds a new payment to a customers account. Takes a list of keys and values as
44 paramters with the following keys:
66 Option date for payment
72 my $result = FS::API->insert_payment(
73 'secret' => 'sharingiscaring',
79 '_date' => 1397977200, #UNIX timestamp
82 if ( $result->{'error'} ) {
83 die $result->{'error'};
86 print "paynum ". $result->{'paynum'};
93 my($class, %opt) = @_;
94 return _shared_secret_error() unless _check_shared_secret($opt{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 $class->_by_phonenum('insert_payment', %opt);
112 my($class, $method, %opt) = @_;
113 return _shared_secret_error() unless _check_shared_secret($opt{secret});
115 my $phonenum = delete $opt{'phonenum'};
117 my $svc_phone = qsearchs('svc_phone', { 'phonenum' => $phonenum } )
118 or return { 'error' => 'Unknown phonenum' };
120 my $cust_pkg = $svc_phone->cust_svc->cust_pkg
121 or return { 'error' => 'Unlinked phonenum' };
123 $opt{'custnum'} = $cust_pkg->custnum;
125 $class->$method(%opt);
128 =item insert_credit OPTION => VALUE, ...
130 Adds a a credit to a customers account. Takes a list of keys and values as
131 parameters with the following keys
149 The date the credit will be posted
155 my $result = FS::API->insert_credit(
156 'secret' => 'sharingiscaring',
161 '_date' => 1397977200, #UNIX timestamp
164 if ( $result->{'error'} ) {
165 die $result->{'error'};
168 print "crednum ". $result->{'crednum'};
175 my($class, %opt) = @_;
176 return _shared_secret_error() unless _check_shared_secret($opt{secret});
178 $opt{'reasonnum'} ||= FS::Conf->new->config('api_credit_reason');
180 #less "raw" than this? we are the backoffice API, and aren't worried
181 # about version migration ala cust_main/cust_location here
182 my $cust_credit = new FS::cust_credit { %opt };
183 my $error = $cust_credit->insert;
184 return { 'error' => $error,
185 'crednum' => $cust_credit->crednum,
189 # pass the phone number ( from svc_phone )
190 sub insert_credit_phonenum {
191 my($class, %opt) = @_;
192 $class->_by_phonenum('insert_credit', %opt);
195 =item apply_payments_and_credits
197 Applies payments and credits for this customer. Takes a list of keys and
198 values as parameter with the following keys:
214 #apply payments and credits
215 sub apply_payments_and_credits {
216 my($class, %opt) = @_;
217 return _shared_secret_error() unless _check_shared_secret($opt{secret});
219 my $cust_main = qsearchs('cust_main', { 'custnum' => $opt{custnum} })
220 or return { 'error' => 'Unknown custnum' };
222 my $error = $cust_main->apply_payments_and_credits( 'manual'=>1 );
223 return { 'error' => $error, };
226 =item insert_refund OPTION => VALUE, ...
228 Adds a a credit to a customers account. Takes a list of keys and values as
229 parmeters with the following keys: custnum, payby, refund
233 my $result = FS::API->insert_refund(
234 'secret' => 'sharingiscaring',
240 '_date' => 1397977200, #UNIX timestamp
243 if ( $result->{'error'} ) {
244 die $result->{'error'};
247 print "refundnum ". $result->{'crednum'};
254 my($class, %opt) = @_;
255 return _shared_secret_error() unless _check_shared_secret($opt{secret});
257 # when github pull request #24 is merged,
258 # will have to change over to default reasonnum like credit
259 # but until then, this will do
260 $opt{'reason'} ||= 'API refund';
262 #less "raw" than this? we are the backoffice API, and aren't worried
263 # about version migration ala cust_main/cust_location here
264 my $cust_refund = new FS::cust_refund { %opt };
265 my $error = $cust_refund->insert;
266 return { 'error' => $error,
267 'refundnum' => $cust_refund->refundnum,
271 # pass the phone number ( from svc_phone )
272 sub insert_refund_phonenum {
273 my($class, %opt) = @_;
274 $class->_by_phonenum('insert_refund', %opt);
279 # "2 way syncing" ? start with non-sync pulling info here, then if necessary
280 # figure out how to trigger something when those things change
282 # long-term: package changes?
284 =item new_customer OPTION => VALUE, ...
286 Creates a new customer. Takes a list of keys and values as parameters with the
297 first name (required)
305 (not typically collected; mostly used for ACH transactions)
311 =item address1 (required)
315 =item city (required)
323 =item state (required)
345 Currently used for third party tax vendor lookups
349 Used for determining FCC 477 reporting
353 Used for determining FCC 477 reporting
373 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),
375 Set to 1 to enable postal invoicing
377 =item referral_custnum
379 Referring customer number
391 Agent specific customer number
393 =item referral_custnum
395 Referring customer number
401 #certainly false laziness w/ClientAPI::Signup new_customer/new_customer_minimal
402 # but approaching this from a clean start / back-office perspective
403 # i.e. no package/service, no immediate credit card run, etc.
406 my( $class, %opt ) = @_;
407 return _shared_secret_error() unless _check_shared_secret($opt{secret});
409 #default agentnum like signup_server-default_agentnum?
410 #$opt{agentnum} ||= $conf->config('signup_server-default_agentnum');
412 #same for refnum like signup_server-default_refnum
413 $opt{refnum} ||= FS::Conf->new->config('signup_server-default_refnum');
415 $class->API_insert( %opt );
418 =item update_customer
420 Updates an existing customer. Passing an empty value clears that field, while
421 NOT passing that key/value at all leaves it alone. Takes a list of keys and
422 values as parameters with the following keys:
428 API Secret (required)
432 Customer number (required)
488 Comma-separated list of email addresses for email invoices. The special value
489 'POST' is used to designate postal invoicing (it may be specified alone or in
490 addition to email addresses),
492 Set to 1 to enable postal invoicing
494 =item referral_custnum
496 Referring customer number
510 sub update_customer {
511 my( $class, %opt ) = @_;
512 return _shared_secret_error() unless _check_shared_secret($opt{secret});
514 FS::cust_main->API_update( %opt );
517 =item customer_info OPTION => VALUE, ...
519 Returns general customer information. Takes a list of keys and values as
520 parameters with the following keys: custnum, secret
525 my( $class, %opt ) = @_;
526 return _shared_secret_error() unless _check_shared_secret($opt{secret});
528 my $cust_main = qsearchs('cust_main', { 'custnum' => $opt{custnum} })
529 or return { 'error' => 'Unknown custnum' };
531 $cust_main->API_getinfo;
536 Returns location specific information for the customer. Takes a list of keys
537 and values as paramters with the following keys: custnum, secret
541 #I also monitor for changes to the additional locations that are applied to
542 # packages, and would like for those to be exportable as well. basically the
543 # location data passed with the custnum.
546 my( $class, %opt ) = @_;
547 return _shared_secret_error() unless _check_shared_secret($opt{secret});
549 my @cust_location = qsearch('cust_location', { 'custnum' => $opt{custnum} });
553 'locations' => [ map $_->hashref, @cust_location ],
559 =item bill_now OPTION => VALUE, ...
561 Bills a single customer now, in the same fashion as the "Bill now" link in the
564 Returns a hash reference with a single key, 'error'. If there is an error,
565 the value contains the error, otherwise it is empty. Takes a list of keys and
566 values as parameters with the following keys:
572 API Secret (required)
576 Customer number (required)
583 my( $class, %opt ) = @_;
584 return _shared_secret_error() unless _check_shared_secret($opt{secret});
586 my $cust_main = qsearchs('cust_main', { 'custnum' => $opt{custnum} })
587 or return { 'error' => 'Unknown custnum' };
589 my $error = $cust_main->bill_and_collect( 'fatal' => 'return',
594 return { 'error' => $error,
600 #next.. Advertising sources?
607 sub _check_shared_secret {
608 shift eq FS::Conf->new->config('api_shared_secret');
611 sub _shared_secret_error {
612 return { 'error' => 'Incorrect shared secret' };