FS/FS/API.pm

   1 package FS::API;
   2
   3 use FS::Conf;
   4 use FS::Record qw( qsearch qsearchs );
   5 use FS::cust_main;
   6 use FS::cust_location;
   7 use FS::cust_pay;
   8 use FS::cust_credit;
   9 use FS::cust_refund;
  10
  11 =head1 NAME
  12
  13 FS::API - Freeside backend API
  14
  15 =head1 SYNOPSIS
  16
  17   use FS::API;
  18
  19 =head1 DESCRIPTION
  20
  21 This module implements a backend API for advanced back-office integration.
  22
  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.
  27
  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
  32 in plaintext.
  33
  34 =head1 METHODS
  35
  36 =over 4
  37
  38 =item insert_payment
  39
  40 Example:
  41
  42   my $result = FS::API->insert_payment(
  43     'secret'  => 'sharingiscaring',
  44     'custnum' => 181318,
  45     'payby'   => 'CASH',
  46     'paid'    => '54.32',
  47
  48     #optional
  49     '_date'   => 1397977200, #UNIX timestamp
  50   );
  51
  52   if ( $result->{'error'} ) {
  53     die $result->{'error'};
  54   } else {
  55     #payment was inserted
  56     print "paynum ". $result->{'paynum'};
  57   }
  58
  59 =cut
  60
  61 #enter cash payment
  62 sub insert_payment {
  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');
  67
  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,
  74          };
  75 }
  76
  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');
  83
  84   $class->_by_phonenum('insert_payment', %opt);
  85
  86 }
  87
  88 sub _by_phonenum {
  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');
  93
  94   my $phonenum = delete $opt{'phonenum'};
  95
  96   my $svc_phone = qsearchs('svc_phone', { 'phonenum' => $phonenum } )
  97     or return { 'error' => 'Unknown phonenum' };
  98
  99   my $cust_pkg = $svc_phone->cust_svc->cust_pkg
 100     or return { 'error' => 'Unlinked phonenum' };
 101
 102   $opt{'custnum'} = $cust_pkg->custnum;
 103
 104   $class->$method(%opt);
 105
 106 }
 107
 108 =item insert_credit
 109
 110 Example:
 111
 112   my $result = FS::API->insert_credit(
 113     'secret'  => 'sharingiscaring',
 114     'custnum' => 181318,
 115     'amount'  => '54.32',
 116
 117     #optional
 118     '_date'   => 1397977200, #UNIX timestamp
 119   );
 120
 121   if ( $result->{'error'} ) {
 122     die $result->{'error'};
 123   } else {
 124     #credit was inserted
 125     print "crednum ". $result->{'crednum'};
 126   }
 127
 128 =cut
 129
 130 #Enter credit
 131 sub insert_credit {
 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');
 136
 137   $opt{'reasonnum'} ||= $conf->config('api_credit_reason');
 138
 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,
 145          };
 146 }
 147
 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');
 154
 155   $class->_by_phonenum('insert_credit', %opt);
 156
 157 }
 158
 159 =item insert_refund
 160
 161 Example:
 162
 163   my $result = FS::API->insert_refund(
 164     'secret'  => 'sharingiscaring',
 165     'custnum' => 181318,
 166     'payby'   => 'CASH',
 167     'refund'  => '54.32',
 168
 169     #optional
 170     '_date'   => 1397977200, #UNIX timestamp
 171   );
 172
 173   if ( $result->{'error'} ) {
 174     die $result->{'error'};
 175   } else {
 176     #refund was inserted
 177     print "refundnum ". $result->{'crednum'};
 178   }
 179
 180 =cut
 181
 182 #Enter cash refund.
 183 sub insert_refund {
 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');
 188
 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';
 193
 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,
 200          };
 201 }
 202
 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');
 209
 210   $class->_by_phonenum('insert_refund', %opt);
 211
 212 }
 213
 214 #---
 215
 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
 218
 219 # long-term: package changes?
 220
 221 =item new_customer
 222
 223 =cut
 224
 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.
 228
 229 sub new_customer {
 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');
 234
 235   #default agentnum like signup_server-default_agentnum?
 236
 237   #same for refnum like signup_server-default_refnum
 238
 239   my $cust_main = new FS::cust_main ( {
 240       'agentnum'      => $agentnum,
 241       'refnum'        => $opt{refnum}
 242                          || $conf->config('signup_server-default_refnum'),
 243       'payby'         => 'BILL',
 244
 245       map { $_ => $opt{$_} } qw(
 246         agentnum refnum agent_custid referral_custnum
 247         last first company
 248         daytime night fax mobile
 249         payby payinfo paydate paycvv payname
 250       ),
 251
 252   } );
 253
 254   my @invoicing_list = $opt{'invoicing_list'}
 255                          ? split( /\s*\,\s*/, $opt{'invoicing_list'} )
 256                          : ();
 257   push @invoicing_list, 'POST' if $opt{'postal_invoicing'};
 258
 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"};
 264   }
 265
 266   my $bill_location = FS::cust_location->new($bill_hash);
 267   my $ship_location;
 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
 270   # address?
 271   if ( length($ship_hash->{address1}) > 0 and
 272           grep { $bill_hash->{$_} ne $ship_hash->{$_} } keys(%$ship_hash)
 273          ) {
 274
 275     $ship_location = FS::cust_location->new( $ship_hash );
 276
 277   } else {
 278     $ship_location = $bill_location;
 279   }
 280
 281   $cust_main->set('bill_location' => $bill_location);
 282   $cust_main->set('ship_location' => $ship_location);
 283
 284   $error = $cust_main->insert( {}, \@invoicing_list );
 285   return { 'error'   => $error } if $error;
 286
 287   return { 'error'   => '',
 288            'custnum' => $cust_main->custnum,
 289          };
 290
 291 }
 292
 293 =item customer_info
 294
 295 =cut
 296
 297 #some false laziness w/ClientAPI::Myaccount customer_info/customer_info_short
 298
 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
 302 );
 303 #  locale
 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
 308 );
 309
 310 sub customer_info {
 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');
 315
 316   my $cust_main = qsearchs('cust_main', { 'custnum' => $opt{custnum} })
 317     or return { 'error' => 'Unknown custnum' };
 318
 319   my %return = (
 320     'error'           => '',
 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,
 326   );
 327
 328   $return{$_} = $cust_main->get($_)
 329     foreach @cust_main_editable_fields;
 330
 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;
 336   }
 337
 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 );
 343
 344   #generally, the more useful data from the cust_main record the better.
 345   # well, tell me what you want
 346
 347   return \%return;
 348
 349 }
 350
 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.
 354 sub location_info {
 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');
 359
 360   my @cust_location = qsearch('cust_location', { 'custnum' => $opt{custnum} });
 361
 362   my %return = (
 363     'error'           => '',
 364     'locations'       => [ map $_->hashref, @cust_location ],
 365   );
 366
 367   return \%return;
 368 }
 369
 370 #Advertising sources?
 371
 372 =back
 373
 374 1;