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 #generally, the more useful data from the cust_main record the better.
  45
  46
  47 # "2 way syncing" ?  start with non-sync pulling info here, then if necessary
  48 # figure out how to trigger something when those things change
  49
  50 # long-term: package changes?
  51
  52 =item customer_info
  53
  54 =cut
  55
  56 #some false laziness w/ClientAPI::Myaccount customer_info/customer_info_short
  57
  58 use vars qw( @cust_main_editable_fields @location_editable_fields );
  59 @cust_main_editable_fields = qw(
  60   first last company daytime night fax mobile
  61 );
  62 #  locale
  63 #  payby payinfo payname paystart_month paystart_year payissue payip
  64 #  ss paytype paystate stateid stateid_state
  65 @location_editable_fields = qw(
  66   address1 address2 city county state zip country
  67 );
  68
  69 sub customer_info {
  70   my( $class, %opt ) = @_;
  71   my $conf = new FS::Conf;
  72   return { 'error' => 'Incorrect shared secret' }
  73     unless $opt{secret} eq $conf->config('api_shared_secret');
  74
  75   my $cust_main = qsearchs('cust_main', { 'custnum' => $opt{custnum} })
  76     or return { 'error' => 'Unknown custnum' };
  77
  78   my %return = (
  79     'error'           => '',
  80     'display_custnum' => $cust_main->display_custnum,
  81     'name'            => $cust_main->first. ' '. $cust_main->get('last'),
  82     'balance'         => $cust_main->balance,
  83     'status'          => $cust_main->status,
  84     'statuscolor'     => $cust_main->statuscolor,
  85   );
  86
  87   $return{$_} = $cust_main->get($_)
  88     foreach ( @cust_main_editable_fields,
  89               @location_editable_fields,
  90               map "ship_$_", @location_editable_fields,
  91             );
  92
  93   my @invoicing_list = $cust_main->invoicing_list;
  94   $return{'invoicing_list'} =
  95     join(', ', grep { $_ !~ /^(POST|FAX)$/ } @invoicing_list );
  96   $return{'postal_invoicing'} =
  97     0 < ( grep { $_ eq 'POST' } @invoicing_list );
  98
  99   return \%return;
 100
 101 }
 102
 103 #I also monitor for changes to the additional locations that are applied to
 104 # packages, and would like for those to be exportable as well.  basically the
 105 # location data passed with the custnum.
 106 sub location_info {
 107   my( $class, %opt ) = @_;
 108   my $conf = new FS::Conf;
 109   return { 'error' => 'Incorrect shared secret' }
 110     unless $opt{secret} eq $conf->config('api_shared_secret');
 111
 112   my @cust_location = qsearch('cust_location', { 'custnum' => $opt{custnum} });
 113
 114   my %return = (
 115     'error'           => '',
 116     'locations'       => [ @cust_location ],
 117   );
 118
 119   return \%return;
 120 }
 121
 122 #Advertising sources?
 123
 124 =back
 125
 126 1;