X-Git-Url: http://git.freeside.biz/gitweb/?a=blobdiff_plain;f=FS%2FFS%2FAPI.pm;h=77dbf877ad0033bc655e601eeaa1afefa38d4d91;hb=37874e97c78c3a5561686426cd7514c261841d5d;hp=98c1a938d5e5b42c29946bdf863b9f3d4d723f22;hpb=c2fdce8923a09f4a586323adbb7bd0f0dfc587f2;p=freeside.git diff --git a/FS/FS/API.pm b/FS/FS/API.pm index 98c1a938d..77dbf877a 100644 --- a/FS/FS/API.pm +++ b/FS/FS/API.pm @@ -1,8 +1,9 @@ package FS::API; use FS::Conf; -use FS::Record qw( qsearchs ); +use FS::Record qw( qsearch qsearchs ); use FS::cust_main; +use FS::cust_location; use FS::cust_pay; use FS::cust_credit; use FS::cust_refund; @@ -36,6 +37,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( @@ -55,6 +81,8 @@ Example: print "paynum ". $result->{'paynum'}; } +=back + =cut #enter cash payment @@ -106,6 +134,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( @@ -124,6 +172,8 @@ Example: print "crednum ". $result->{'crednum'}; } +=back + =cut #Enter credit @@ -157,6 +207,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( @@ -212,36 +264,216 @@ sub insert_refund_phonenum { #--- -#Customer data -# pull customer info -# The fields needed are: -# -# cust_main.custnum -# cust_main.first -# cust_main.last -# cust_main.company -# cust_main.address1 -# cust_main.address2 -# cust_main.city -# cust_main.state -# cust_main.zip -# cust_main.daytime -# cust_main.night -# cust_main_invoice.dest -# -# at minimum - -#Customer balances - -#Advertising sources? - # "2 way syncing" ? start with non-sync pulling info here, then if necessary # figure out how to trigger something when those things change # long-term: package changes? +=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 +# but approaching this from a clean start / back-office perspective +# i.e. no package/service, no immediate credit card run, etc. + +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? + + #same for refnum like 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, + }; + +} + +=back + =item customer_info +Returns general customer information. Takes a hash reference as parameter with the following keys: custnum and API secret + =cut #some false laziness w/ClientAPI::Myaccount customer_info/customer_info_short @@ -270,15 +502,64 @@ sub customer_info { '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; + } + + 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 ); + + #generally, the more useful data from the cust_main record the better. + # well, tell me what you want + return \%return; } + +=item location_info + +Returns location specific information for the customer. Takes a hash reference as parameter with the following keys: custnum,secret + =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; + return { 'error' => 'Incorrect shared secret' } + unless $opt{secret} eq $conf->config('api_shared_secret'); + + my @cust_location = qsearch('cust_location', { 'custnum' => $opt{custnum} }); + + my %return = ( + 'error' => '', + 'locations' => [ map $_->hashref, @cust_location ], + ); + + return \%return; +} + +#Advertising sources? + + 1;