X-Git-Url: http://git.freeside.biz/gitweb/?a=blobdiff_plain;f=FS%2FFS%2FAPI.pm;h=99e04774fd3f208ce5aec419c49e7dcad46bf26f;hb=918b627555b7fbce548a21aa1e46b686505c3930;hp=36587da596c8d5e34ed74c47659a4a7acab533e4;hpb=2fb037a3fdebcf220ce051ea1ba58efcfa2c5c49;p=freeside.git diff --git a/FS/FS/API.pm b/FS/FS/API.pm index 36587da59..99e04774f 100644 --- a/FS/FS/API.pm +++ b/FS/FS/API.pm @@ -1,5 +1,6 @@ package FS::API; +use strict; use FS::Conf; use FS::Record qw( qsearch qsearchs ); use FS::cust_main; @@ -28,7 +29,7 @@ integration with other back-office systems. If accessing this API remotely with XML-RPC or JSON-RPC, be careful to block the port by default, only allow access from back-office servers with the same security precations as the Freeside server, and encrypt the communication -channel (for exampple, with an SSH tunnel or VPN) rather than accessing it +channel (for example, with an SSH tunnel or VPN) rather than accessing it in plaintext. =head1 METHODS @@ -37,6 +38,31 @@ in plaintext. =item insert_payment +Adds a new payment to a customers account. Takes a hash reference as parameter with the following keys: + +=over 5 + +=item secret + +API Secret + +=item custnum + +Customer number + +=item payby + +Payment type + +=item paid + +Amount paid + +=item _date + + +Option date for payment + Example: my $result = FS::API->insert_payment( @@ -56,6 +82,8 @@ Example: print "paynum ". $result->{'paynum'}; } +=back + =cut #enter cash payment @@ -107,6 +135,26 @@ sub _by_phonenum { =item insert_credit +Adds a a credit to a customers account. Takes a hash reference as parameter with the following keys + +=over + +=item secret + +API Secret + +=item custnum + +customer number + +=item amount + +Amount of the credit + +=item _date + +The date the credit will be posted + Example: my $result = FS::API->insert_credit( @@ -125,6 +173,8 @@ Example: print "crednum ". $result->{'crednum'}; } +=back + =cut #Enter credit @@ -158,6 +208,8 @@ sub insert_credit_phonenum { =item insert_refund +Adds a a credit to a customers account. Takes a hash reference as parameter with the following keys: custnum,payby,refund + Example: my $result = FS::API->insert_refund( @@ -220,6 +272,133 @@ sub insert_refund_phonenum { =item new_customer +Creates a new customer. Takes a hash reference as parameter with the following keys: + +=over 4 + +=item secret + +API Secret + +=item first + +first name (required) + +=item last + +last name (required) + +=item ss + +(not typically collected; mostly used for ACH transactions) + +=item company + +Company name + +=item address1 (required) + +Address line one + +=item city (required) + +City + +=item county + +County + +=item state (required) + +State + +=item zip (required) + +Zip or postal code + +=item country + +2 Digit Country Code + +=item latitude + +latitude + +=item Longitude + +longitude + +=item geocode + +Currently used for third party tax vendor lookups + +=item censustract + +Used for determining FCC 477 reporting + +=item censusyear + +Used for determining FCC 477 reporting + +=item daytime + +Daytime phone number + +=item night + +Evening phone number + +=item fax + +Fax number + +=item mobile + +Mobile number + +=item invoicing_list + +comma-separated list of email addresses for email invoices. The special value 'POST' is used to designate postal invoicing (it may be specified alone or in addition to email addresses), +postal_invoicing +Set to 1 to enable postal invoicing + +=item payby + +CARD, DCRD, CHEK, DCHK, LECB, BILL, COMP or PREPAY + +=item payinfo + +Card number for CARD/DCRD, account_number@aba_number for CHEK/DCHK, prepaid "pin" for PREPAY, purchase order number for BILL + +=item paycvv + +Credit card CVV2 number (1.5+ or 1.4.2 with CVV schema patch) + +=item paydate + +Expiration date for CARD/DCRD + +=item payname + +Exact name on credit card for CARD/DCRD, bank name for CHEK/DCHK + +=item referral_custnum + +referring customer number + +=item agentnum + +Agent number + +=item agent_custid + +Agent specific customer number + +=item referral_custnum + +Referring customer number + + =cut #certainly false laziness w/ClientAPI::Signup new_customer/new_customer_minimal @@ -228,84 +407,27 @@ sub insert_refund_phonenum { sub new_customer { my( $class, %opt ) = @_; + my $conf = new FS::Conf; return { 'error' => 'Incorrect shared secret' } unless $opt{secret} eq $conf->config('api_shared_secret'); #default agentnum like signup_server-default_agentnum? + #$opt{agentnum} ||= $conf->config('signup_server-default_agentnum'); #same for refnum like signup_server-default_refnum + $opt{refnum} ||= $conf->config('signup_server-default_refnum'); - my $cust_main = new FS::cust_main ( { - 'agentnum' => $agentnum, - 'refnum' => $opt{refnum} - || $conf->config('signup_server-default_refnum'), - 'payby' => 'BILL', - - map { $_ => $opt{$_} } qw( - agentnum refnum agent_custid referral_custnum - last first company - daytime night fax mobile - payby payinfo paydate paycvv payname - ), - - } ); - - my @invoicing_list = $opt{'invoicing_list'} - ? split( /\s*\,\s*/, $opt{'invoicing_list'} ) - : (); - push @invoicing_list, 'POST' if $opt{'postal_invoicing'}; - - my ($bill_hash, $ship_hash); - foreach my $f (FS::cust_main->location_fields) { - # avoid having to change this in front-end code - $bill_hash->{$f} = $opt{"bill_$f"} || $opt{$f}; - $ship_hash->{$f} = $opt{"ship_$f"}; - } - - my $bill_location = FS::cust_location->new($bill_hash); - my $ship_location; - # we don't have an equivalent of the "same" checkbox in selfservice^Wthis API - # so is there a ship address, and if so, is it different from the billing - # address? - if ( length($ship_hash->{address1}) > 0 and - grep { $bill_hash->{$_} ne $ship_hash->{$_} } keys(%$ship_hash) - ) { - - $ship_location = FS::cust_location->new( $ship_hash ); - - } else { - $ship_location = $bill_location; - } - - $cust_main->set('bill_location' => $bill_location); - $cust_main->set('ship_location' => $ship_location); - - $error = $cust_main->insert( {}, \@invoicing_list ); - return { 'error' => $error } if $error; - - return { 'error' => '', - 'custnum' => $cust_main->custnum, - }; - + $class->API_insert( %opt ); } -=item customer_info +=back -=cut +=item customer_info -#some false laziness w/ClientAPI::Myaccount customer_info/customer_info_short +Returns general customer information. Takes a hash reference as parameter with the following keys: custnum and API secret -use vars qw( @cust_main_editable_fields @location_editable_fields ); -@cust_main_editable_fields = qw( - first last company daytime night fax mobile -); -# locale -# payby payinfo payname paystart_month paystart_year payissue payip -# ss paytype paystate stateid stateid_state -@location_editable_fields = qw( - address1 address2 city county state zip country -); +=cut sub customer_info { my( $class, %opt ) = @_; @@ -316,41 +438,21 @@ sub customer_info { my $cust_main = qsearchs('cust_main', { 'custnum' => $opt{custnum} }) or return { 'error' => 'Unknown custnum' }; - my %return = ( - 'error' => '', - 'display_custnum' => $cust_main->display_custnum, - 'name' => $cust_main->first. ' '. $cust_main->get('last'), - 'balance' => $cust_main->balance, - 'status' => $cust_main->status, - 'statuscolor' => $cust_main->statuscolor, - ); - - $return{$_} = $cust_main->get($_) - foreach @cust_main_editable_fields; - - for (@location_editable_fields) { - $return{$_} = $cust_main->bill_location->get($_) - if $cust_main->bill_locationnum; - $return{'ship_'.$_} = $cust_main->ship_location->get($_) - if $cust_main->ship_locationnum; - } + $cust_main->API_getinfo; +} - my @invoicing_list = $cust_main->invoicing_list; - $return{'invoicing_list'} = - join(', ', grep { $_ !~ /^(POST|FAX)$/ } @invoicing_list ); - $return{'postal_invoicing'} = - 0 < ( grep { $_ eq 'POST' } @invoicing_list ); +=item location_info - #generally, the more useful data from the cust_main record the better. - # well, tell me what you want +Returns location specific information for the customer. Takes a hash reference as parameter with the following keys: custnum,secret - return \%return; +=back -} +=cut #I also monitor for changes to the additional locations that are applied to # packages, and would like for those to be exportable as well. basically the # location data passed with the custnum. + sub location_info { my( $class, %opt ) = @_; my $conf = new FS::Conf; @@ -369,6 +471,5 @@ sub location_info { #Advertising sources? -=back 1;