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
   8 =head1 NAME
   9
  10 FS::API - Freeside backend API
  11
  12 =head1 SYNOPSIS
  13
  14   use FS::API;
  15
  16 =head1 DESCRIPTION
  17
  18 This module implements a backend API for advanced back-office integration.
  19
  20 In contrast to the self-service API, which authenticates an end-user and offers
  21 functionality to that end user, the backend API performs a simple shared-secret
  22 authentication and offers full, administrator functionality, enabling
  23 integration with other back-office systems.
  24
  25 If accessing this API remotely with XML-RPC or JSON-RPC, be careful to block
  26 the port by default, only allow access from back-office servers with the same
  27 security precations as the Freeside server, and encrypt the communication
  28 channel (for exampple, with an SSH tunnel or VPN) rather than accessing it
  29 in plaintext.
  30
  31 =head1 METHODS
  32
  33 =over 4
  34
  35 # needs to be able to:
  36 Enter cash payment
  37 Enter credit
  38 Enter cash refund.
  39
  40 # would like to be able to pass the phone number ( from svc_phone ) to the API for this query.
  41
  42 #---
  43
  44 # "2 way syncing" ?  start with non-sync pulling info here, then if necessary
  45 # figure out how to trigger something when those things change
  46
  47 # long-term: package changes?
  48
  49
  50 =item new_customer
  51
  52 =cut
  53
  54 #certainly false laziness w/ClientAPI::Signup new_customer/new_customer_minimal
  55 # but approaching this from a clean start / back-office perspective
  56 #  i.e. no package/service, no immediate credit card run, etc.
  57
  58 sub new_customer {
  59   my( $class, %opt ) = @_;
  60   my $conf = new FS::Conf;
  61   return { 'error' => 'Incorrect shared secret' }
  62     unless $opt{secret} eq $conf->config('api_shared_secret');
  63
  64   #default agentnum like signup_server-default_agentnum?
  65
  66   #same for refnum like signup_server-default_refnum
  67
  68   my $cust_main = new FS::cust_main ( {
  69       'agentnum'      => $agentnum,
  70       'refnum'        => $opt{refnum}
  71                          || $conf->config('signup_server-default_refnum'),
  72       'payby'         => 'BILL',
  73
  74       map { $_ => $opt{$_} } qw(
  75         agentnum refnum agent_custid referral_custnum
  76         last first company
  77         address1 address2 city county state zip country
  78         latitude longitude
  79         geocode censustract censusyear
  80         ship_address1 ship_address2 ship_city ship_county ship_state ship_zip ship_country
  81         ship_latitude ship_longitude
  82         daytime night fax mobile
  83         payby payinfo paydate paycvv payname
  84       ),
  85
  86   } );
  87
  88   my @invoicing_list = $opt{'invoicing_list'}
  89                          ? split( /\s*\,\s*/, $opt{'invoicing_list'} )
  90                          : ();
  91   push @invoicing_list, 'POST' if $opt{'postal_invoicing'};
  92
  93   $error = $cust_main->insert( {}, \@invoicing_list );
  94   return { 'error'   => $error } if $error;
  95
  96   return { 'error'   => '',
  97            'custnum' => $cust_main->custnum,
  98          };
  99
 100 }
 101
 102 =item customer_info
 103
 104 =cut
 105
 106 #some false laziness w/ClientAPI::Myaccount customer_info/customer_info_short
 107
 108 use vars qw( @cust_main_editable_fields @location_editable_fields );
 109 @cust_main_editable_fields = qw(
 110   first last company daytime night fax mobile
 111 );
 112 #  locale
 113 #  payby payinfo payname paystart_month paystart_year payissue payip
 114 #  ss paytype paystate stateid stateid_state
 115 @location_editable_fields = qw(
 116   address1 address2 city county state zip country
 117 );
 118
 119 sub customer_info {
 120   my( $class, %opt ) = @_;
 121   my $conf = new FS::Conf;
 122   return { 'error' => 'Incorrect shared secret' }
 123     unless $opt{secret} eq $conf->config('api_shared_secret');
 124
 125   my $cust_main = qsearchs('cust_main', { 'custnum' => $opt{custnum} })
 126     or return { 'error' => 'Unknown custnum' };
 127
 128   my %return = (
 129     'error'           => '',
 130     'display_custnum' => $cust_main->display_custnum,
 131     'name'            => $cust_main->first. ' '. $cust_main->get('last'),
 132     'balance'         => $cust_main->balance,
 133     'status'          => $cust_main->status,
 134     'statuscolor'     => $cust_main->statuscolor,
 135   );
 136
 137   $return{$_} = $cust_main->get($_)
 138     foreach ( @cust_main_editable_fields,
 139               @location_editable_fields,
 140               map "ship_$_", @location_editable_fields,
 141             );
 142
 143   my @invoicing_list = $cust_main->invoicing_list;
 144   $return{'invoicing_list'} =
 145     join(', ', grep { $_ !~ /^(POST|FAX)$/ } @invoicing_list );
 146   $return{'postal_invoicing'} =
 147     0 < ( grep { $_ eq 'POST' } @invoicing_list );
 148
 149   #generally, the more useful data from the cust_main record the better.
 150   # well, tell me what you want
 151
 152   return \%return;
 153
 154 }
 155
 156
 157 #I also monitor for changes to the additional locations that are applied to
 158 # packages, and would like for those to be exportable as well.  basically the
 159 # location data passed with the custnum.
 160 sub location_info {
 161   my( $class, %opt ) = @_;
 162   my $conf = new FS::Conf;
 163   return { 'error' => 'Incorrect shared secret' }
 164     unless $opt{secret} eq $conf->config('api_shared_secret');
 165
 166   my @cust_location = qsearch('cust_location', { 'custnum' => $opt{custnum} });
 167
 168   my %return = (
 169     'error'           => '',
 170     'locations'       => [ map $_->hashref, @cust_location ],
 171   );
 172
 173   return \%return;
 174 }
 175
 176 #Advertising sources?
 177
 178 =back
 179
 180 1;