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