4 use FS::Record qw( qsearch qsearchs );
10 FS::API - Freeside backend API
18 This module implements a backend API for advanced back-office integration.
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.
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
35 # needs to be able to:
40 # would like to be able to pass the phone number ( from svc_phone ) to the API for this query.
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
47 # long-term: package changes?
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.
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');
64 #default agentnum like signup_server-default_agentnum?
66 #same for refnum like signup_server-default_refnum
68 my $cust_main = new FS::cust_main ( {
69 'agentnum' => $agentnum,
70 'refnum' => $opt{refnum}
71 || $conf->config('signup_server-default_refnum'),
74 map { $_ => $opt{$_} } qw(
75 agentnum refnum agent_custid referral_custnum
77 address1 address2 city county state zip country
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
88 my @invoicing_list = $opt{'invoicing_list'}
89 ? split( /\s*\,\s*/, $opt{'invoicing_list'} )
91 push @invoicing_list, 'POST' if $opt{'postal_invoicing'};
93 $error = $cust_main->insert( {}, \@invoicing_list );
94 return { 'error' => $error } if $error;
96 return { 'error' => '',
97 'custnum' => $cust_main->custnum,
106 #some false laziness w/ClientAPI::Myaccount customer_info/customer_info_short
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
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
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');
125 my $cust_main = qsearchs('cust_main', { 'custnum' => $opt{custnum} })
126 or return { 'error' => 'Unknown custnum' };
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,
137 $return{$_} = $cust_main->get($_)
138 foreach ( @cust_main_editable_fields,
139 @location_editable_fields,
140 map "ship_$_", @location_editable_fields,
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 );
149 #generally, the more useful data from the cust_main record the better.
150 # well, tell me what you want
156 #I also monitor for changes to the additional locations that are applied to
157 # packages, and would like for those to be exportable as well. basically the
158 # location data passed with the custnum.
160 my( $class, %opt ) = @_;
161 my $conf = new FS::Conf;
162 return { 'error' => 'Incorrect shared secret' }
163 unless $opt{secret} eq $conf->config('api_shared_secret');
165 my @cust_location = qsearch('cust_location', { 'custnum' => $opt{custnum} });
169 'locations' => [ map $_->hashref, @cust_location ],
175 #Advertising sources?