FS/FS/API.pm

   1 package FS::API;
   2
   3 use FS::Conf;
   4 use FS::Record qw( qsearchs );
   5 use FS::cust_main;
   6
   7 =head1 NAME
   8
   9 FS::API - Freeside backend API
  10
  11 =head1 SYNOPSIS
  12
  13   use FS::API;
  14
  15 =head1 DESCRIPTION
  16
  17 This module implements a backend API for advanced back-office integration.
  18
  19 In contrast to the self-service API, which authenticates an end-user and offers
  20 functionality to that end user, the backend API performs a simple shared-secret
  21 authentication and offers full, administrator functionality, enabling
  22 integration with other back-office systems.
  23
  24 If accessing this API remotely with XML-RPC or JSON-RPC, be careful to block
  25 the port by default, only allow access from back-office servers with the same
  26 security precations as the Freeside server, and encrypt the communication
  27 channel (for exampple, with an SSH tunnel or VPN) rather than accessing it
  28 in plaintext.
  29
  30 =head1 METHODS
  31
  32 =over 4
  33
  34 # needs to be able to:
  35 Enter cash payment
  36 Enter credit
  37 Enter cash refund.
  38
  39 # would like to be able to pass the phone number ( from svc_phone ) to the API for this query.
  40
  41 #---
  42
  43 #Customer data
  44 # pull customer info
  45 # The fields needed are:
  46 #
  47 # cust_main.custnum
  48 # cust_main.first
  49 # cust_main.last
  50 # cust_main.company
  51 # cust_main.address1
  52 # cust_main.address2
  53 # cust_main.city
  54 # cust_main.state
  55 # cust_main.zip
  56 # cust_main.daytime
  57 # cust_main.night
  58 # cust_main_invoice.dest
  59 #
  60 # at minimum
  61
  62 #Customer balances
  63
  64 #Advertising sources?
  65
  66 # "2 way syncing" ?  start with non-sync pulling info here, then if necessary
  67 # figure out how to trigger something when those things change
  68
  69 # long-term: package changes?
  70
  71 =item customer_info
  72
  73 =cut
  74
  75 #some false laziness w/ClientAPI::Myaccount customer_info/customer_info_short
  76
  77 use vars qw( @cust_main_editable_fields @location_editable_fields );
  78 @cust_main_editable_fields = qw(
  79   first last company daytime night fax mobile
  80 );
  81 #  locale
  82 #  payby payinfo payname paystart_month paystart_year payissue payip
  83 #  ss paytype paystate stateid stateid_state
  84 @location_editable_fields = qw(
  85   address1 address2 city county state zip country
  86 );
  87
  88 sub customer_info {
  89   my( $class, %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 $cust_main = qsearchs('cust_main', { 'custnum' => $opt{custnum} })
  95     or return { 'error' => 'Unknown custnum' };
  96
  97   my %return = (
  98     'error'           => '',
  99     'display_custnum' => $cust_main->display_custnum,
 100     'name'            => $cust_main->first. ' '. $cust_main->get('last'),
 101   );
 102
 103   $return{$_} = $cust_main->get($_)
 104     foreach @cust_main_editable_fields;
 105
 106   return \%return;
 107
 108 }
 109
 110 =back
 111
 112 1;