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 #generally, the more useful data from the cust_main record the better.
 217
 218
 219 # "2 way syncing" ?  start with non-sync pulling info here, then if necessary
 220 # figure out how to trigger something when those things change
 221
 222 # long-term: package changes?
 223
 224 =item customer_info
 225
 226 =cut
 227
 228 #some false laziness w/ClientAPI::Myaccount customer_info/customer_info_short
 229
 230 use vars qw( @cust_main_editable_fields @location_editable_fields );
 231 @cust_main_editable_fields = qw(
 232   first last company daytime night fax mobile
 233 );
 234 #  locale
 235 #  payby payinfo payname paystart_month paystart_year payissue payip
 236 #  ss paytype paystate stateid stateid_state
 237 @location_editable_fields = qw(
 238   address1 address2 city county state zip country
 239 );
 240
 241 sub customer_info {
 242   my( $class, %opt ) = @_;
 243   my $conf = new FS::Conf;
 244   return { 'error' => 'Incorrect shared secret' }
 245     unless $opt{secret} eq $conf->config('api_shared_secret');
 246
 247   my $cust_main = qsearchs('cust_main', { 'custnum' => $opt{custnum} })
 248     or return { 'error' => 'Unknown custnum' };
 249
 250   my %return = (
 251     'error'           => '',
 252     'display_custnum' => $cust_main->display_custnum,
 253     'name'            => $cust_main->first. ' '. $cust_main->get('last'),
 254     'balance'         => $cust_main->balance,
 255     'status'          => $cust_main->status,
 256     'statuscolor'     => $cust_main->statuscolor,
 257   );
 258
 259   $return{$_} = $cust_main->get($_)
 260     foreach @cust_main_editable_fields;
 261
 262   for (@location_editable_fields) {
 263     $return{$_} = $cust_main->bill_location->get($_)
 264       if $cust_main->bill_locationnum;
 265     $return{'ship_'.$_} = $cust_main->ship_location->get($_)
 266       if $cust_main->ship_locationnum;
 267   }
 268
 269   my @invoicing_list = $cust_main->invoicing_list;
 270   $return{'invoicing_list'} =
 271     join(', ', grep { $_ !~ /^(POST|FAX)$/ } @invoicing_list );
 272   $return{'postal_invoicing'} =
 273     0 < ( grep { $_ eq 'POST' } @invoicing_list );
 274
 275   return \%return;
 276
 277 }
 278
 279 #I also monitor for changes to the additional locations that are applied to
 280 # packages, and would like for those to be exportable as well.  basically the
 281 # location data passed with the custnum.
 282 sub location_info {
 283   my( $class, %opt ) = @_;
 284   my $conf = new FS::Conf;
 285   return { 'error' => 'Incorrect shared secret' }
 286     unless $opt{secret} eq $conf->config('api_shared_secret');
 287
 288   my @cust_location = qsearch('cust_location', { 'custnum' => $opt{custnum} });
 289
 290   my %return = (
 291     'error'           => '',
 292     'locations'       => [ @cust_location ],
 293   );
 294
 295   return \%return;
 296 }
 297
 298 #Advertising sources?
 299
 300 =back
 301
 302 1;