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