X-Git-Url: http://git.freeside.biz/gitweb/?a=blobdiff_plain;f=FS%2FFS%2FAPI.pm;h=99e04774fd3f208ce5aec419c49e7dcad46bf26f;hb=908a4522939c0225ef4e7ba4236dab2eebe9daca;hp=e89616080fb355ac1bb883e8be93aafcd900641d;hpb=0d70ce8995b8bf30ef0e88596af0639be3e8e3b0;p=freeside.git diff --git a/FS/FS/API.pm b/FS/FS/API.pm index e89616080..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( @@ -213,30 +265,169 @@ sub insert_refund_phonenum { #--- -#generally, the more useful data from the cust_main record the better. - - # "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 customer_info +=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 -#some false laziness w/ClientAPI::Myaccount customer_info/customer_info_short +#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? + #$opt{agentnum} ||= $conf->config('signup_server-default_agentnum'); + + #same for refnum like signup_server-default_refnum + $opt{refnum} ||= $conf->config('signup_server-default_refnum'); + + $class->API_insert( %opt ); +} + +=back + +=item customer_info + +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 ) = @_; @@ -247,38 +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, - ); + $cust_main->API_getinfo; +} - $return{$_} = $cust_main->get($_) - foreach @cust_main_editable_fields; +=item location_info - 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; - } +Returns location specific information for the customer. Takes a hash reference as parameter with the following keys: custnum,secret - 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 ); - - 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; @@ -289,7 +463,7 @@ sub location_info { my %return = ( 'error' => '', - 'locations' => [ @cust_location ], + 'locations' => [ map $_->hashref, @cust_location ], ); return \%return; @@ -297,6 +471,5 @@ sub location_info { #Advertising sources? -=back 1;