package FS::API;
use strict;
+use Date::Parse;
use FS::Conf;
use FS::Record qw( qsearch qsearchs );
use FS::cust_main;
use FS::cust_credit;
use FS::cust_refund;
use FS::cust_pkg;
+use FS::cust_contact;
=head1 NAME
=head1 SYNOPSIS
- use FS::API;
+ use Frontier::Client;
+ use Data::Dumper;
+
+ my $url = new URI 'http://localhost:8008/'; #or if accessing remotely, secure
+ # the traffic
+
+ my $xmlrpc = new Frontier::Client url=>$url;
+
+ my $result = $xmlrpc->call( 'FS.API.customer_info',
+ 'secret' => 'sharingiscaring',
+ 'custnum' => 181318,
+ );
+
+ print Dumper($result);
=head1 DESCRIPTION
Used for determining FCC 477 reporting
+=item ship_address1
+
+=item ship_address2
+
+=item ship_city
+
+=item ship_county
+
+=item ship_state
+
+=item ship_zip
+
+=item ship_country
+
+Optional shipping address fields. If sending an optional shipping address,
+ship_address1, ship_city, ship_state and ship_zip are required.
+
=item daytime
Daytime phone number
#same for refnum like signup_server-default_refnum
$opt{refnum} ||= FS::Conf->new->config('signup_server-default_refnum');
- $class->API_insert( %opt );
+ FS::cust_main->API_insert( %opt );
}
=item update_customer
Returns general customer information. Takes a list of keys and values as
parameters with the following keys: custnum, secret
+Example:
+
+ use Frontier::Client;
+ use Data::Dumper;
+
+ my $url = new URI 'http://localhost:8008/'; #or if accessing remotely, secure
+ # the traffic
+
+ my $xmlrpc = new Frontier::Client url=>$url;
+
+ my $result = $xmlrpc->call( 'FS.API.customer_info',
+ 'secret' => 'sharingiscaring',
+ 'custnum' => 181318,
+ );
+
+ print Dumper($result);
+
+Returns the following fields:
+
+=over 4
+
+=item error
+
+Empty, or error message (in which case, none of the other fields will be populated)
+
+=item display_custnum
+
+Optional customer number display override - if present, use this for all UI instead of the real database custnum
+
+=item name
+
+Simple string for customer identification (from first, last, company)
+
+=item balance
+
+=item status
+
+=item statuscolor
+
+=item first
+
+=item last
+
+=item company
+
+=item daytime
+
+=item night
+
+=item mobile
+
+=item fax
+
+=item agentnum
+
+Agent (Company)
+
+=item salesnum
+
+Sales person
+
+=item refnum
+
+Advertising channel
+
+=item classnum
+
+Customer class
+
+=item usernum
+
+Employee (initial customer insert)
+
+=item referral_custnum
+
+Referring customer
+
+=item address1
+
+=item address2
+
+=item city
+
+=item county
+
+=item state
+
+=item zip
+
+=item country
+
+=item ship_address1
+
+=item ship_address2
+
+=item ship_city
+
+=item ship_county
+
+=item ship_state
+
+=item ship_zip
+
+=item ship_country
+
+=item invoicing_list
+
+Comma-separated list of email addresses
+
+=item postal_invoicing
+
+0 or 1
+
+=back
+
=cut
sub customer_info {
$cust_main->API_getinfo;
}
+=item customer_list_svcs OPTION => VALUE, ...
+
+Returns customer service information. Takes a list of keys and values as
+parameters with the following keys: custnum, secret
+
+Example:
+
+ use Frontier::Client;
+ use Data::Dumper;
+
+ my $url = new URI 'http://localhost:8008/'; #or if accessing remotely, secure
+ # the traffic
+
+ my $xmlrpc = new Frontier::Client url=>$url;
+
+ my $result = $xmlrpc->call( 'FS.API.customer_list_svcs',
+ 'secret' => 'sharingiscaring',
+ 'custnum' => 181318,
+ );
+
+ print Dumper($result);
+
+ foreach my $cust_svc ( @{ $result->{'cust_svc'} } ) {
+ #print $cust_svc->{mac_addr}."\n" if exists $cust_svc->{mac_addr};
+ print $cust_svc->{circuit_id}."\n" if exists $cust_svc->{circuit_id};
+ }
+
+=cut
+
+sub customer_list_svcs {
+ my( $class, %opt ) = @_;
+ return _shared_secret_error() unless _check_shared_secret($opt{secret});
+
+ my $cust_main = qsearchs('cust_main', { 'custnum' => $opt{custnum} })
+ or return { 'error' => 'Unknown custnum' };
+
+ #$cust_main->API_list_svcs;
+
+ #false laziness w/ClientAPI/list_svcs
+
+ my @cust_svc = ();
+ #my @cust_pkg_usage = ();
+ #foreach my $cust_pkg ( $p->{'ncancelled'}
+ # ? $cust_main->ncancelled_pkgs
+ # : $cust_main->unsuspended_pkgs ) {
+ foreach my $cust_pkg ( $cust_main->all_pkgs ) {
+ #next if $pkgnum && $cust_pkg->pkgnum != $pkgnum;
+ push @cust_svc, @{[ $cust_pkg->cust_svc ]}; #@{[ ]} to force array context
+ #push @cust_pkg_usage, $cust_pkg->cust_pkg_usage;
+ }
+
+ return {
+ 'cust_svc' => [ map $_->API_getinfo, @cust_svc ],
+ };
+
+}
+
=item location_info
Returns location specific information for the customer. Takes a list of keys
return \%return;
}
+=item list_customer_packages OPTION => VALUE, ...
+
+Lists all customer packages.
+
+=over
+
+=item secret
+
+API Secret
+
+=item custnum
+
+Customer Number
+
+=back
+
+Example:
+
+ my $result = FS::API->list_packages(
+ 'secret' => 'sharingiscaring',
+ 'custnum' => custnum,
+ );
+
+ if ( $result->{'error'} ) {
+ die $result->{'error'};
+ } else {
+ # list packages returns an array of hashes for packages ordered by custnum and pkgnum.
+ print Dumper($result->{'pkgs'});
+ }
+
+=cut
+
+sub list_customer_packages {
+ my( $class, %opt ) = @_;
+ return _shared_secret_error() unless _check_shared_secret($opt{secret});
+
+ my $sql_query = FS::cust_pkg->search({ 'custnum' => $opt{custnum}, });
+
+ $sql_query->{order_by} = 'ORDER BY custnum, pkgnum';
+
+ my @packages = qsearch($sql_query)
+ or return { 'error' => 'No packages' };
+
+ my $return = {
+ 'packages' => [ map $_->hashref, @packages ],
+ };
+
+ $return;
+}
+
+=item package_status OPTION => VALUE, ...
+
+Get package status.
+
+=over
+
+=item secret
+
+API Secret
+
+=item pkgnum
+
+Package Number
+
+=back
+
+Example:
+
+ my $result = FS::API->package_status(
+ 'secret' => 'sharingiscaring',
+ 'pkgnum' => pkgnum,
+ );
+
+ if ( $result->{'error'} ) {
+ die $result->{'error'};
+ } else {
+ # package status returns a hash with the status for a package.
+ print Dumper($result->{'status'});
+ }
+
+=cut
+
+sub package_status {
+ my( $class, %opt ) = @_;
+ return _shared_secret_error() unless _check_shared_secret($opt{secret});
+
+ my $cust_pkg = qsearchs('cust_pkg', { 'pkgnum' => $opt{pkgnum} } )
+ or return { 'error' => 'No packages' };
+
+ my $return = {
+ 'status' => $cust_pkg->status,
+ };
+
+ $return;
+}
+
+=item order_package OPTION => VALUE, ...
+
+Orders a new customer package. Takes a list of keys and values as paramaters
+with the following keys:
+
+=over 4
+
+=item secret
+
+API Secret
+
+=item custnum
+
+=item pkgpart
+
+=item quantity
+
+=item start_date
+
+=item contract_end
+
+=item address1
+
+=item address2
+
+=item city
+
+=item county
+
+=item state
+
+=item zip
+
+=item country
+
+=item setup_fee
+
+Including this implements per-customer custom pricing for this package, overriding package definition pricing
+
+=item recur_fee
+
+Including this implements per-customer custom pricing for this package, overriding package definition pricing
+
+=item invoice_details
+
+A single string for just one detail line, or an array reference of one or more
+lines of detail
+
+=back
+
+=cut
+
+sub order_package {
+ my( $class, %opt ) = @_;
+
+ my $cust_main = qsearchs('cust_main', { 'custnum' => $opt{custnum} })
+ or return { 'error' => 'Unknown custnum' };
+
+ #some conceptual false laziness w/cust_pkg/Import.pm
+
+ my $cust_pkg = new FS::cust_pkg {
+ 'pkgpart' => $opt{'pkgpart'},
+ 'quantity' => $opt{'quantity'} || 1,
+ };
+
+ #start_date and contract_end
+ foreach my $date_field (qw( start_date contract_end )) {
+ if ( $opt{$date_field} =~ /^(\d+)$/ ) {
+ $cust_pkg->$date_field( $opt{$date_field} );
+ } elsif ( $opt{$date_field} ) {
+ $cust_pkg->$date_field( str2time( $opt{$date_field} ) );
+ }
+ }
+
+ #especially this part for custom pkg price
+ # (false laziness w/cust_pkg/Import.pm)
+ my $s = $opt{'setup_fee'};
+ my $r = $opt{'recur_fee'};
+ my $part_pkg = $cust_pkg->part_pkg;
+ if ( ( length($s) && $s != $part_pkg->option('setup_fee') )
+ or ( length($r) && $r != $part_pkg->option('recur_fee') )
+ )
+ {
+
+ local($FS::part_pkg::skip_pkg_svc_hack) = 1;
+
+ my $custom_part_pkg = $part_pkg->clone;
+ $custom_part_pkg->disabled('Y');
+ my %options = $part_pkg->options;
+ $options{'setup_fee'} = $s if length($s);
+ $options{'recur_fee'} = $r if length($r);
+ my $error = $custom_part_pkg->insert( options=>\%options );
+ return ( 'error' => "error customizing package: $error" ) if $error;
+
+ #not ->pkg_svc, we want to ignore links and clone the actual package def
+ foreach my $pkg_svc ( $part_pkg->_pkg_svc ) {
+ my $c_pkg_svc = new FS::pkg_svc { $pkg_svc->hash };
+ $c_pkg_svc->pkgsvcnum('');
+ $c_pkg_svc->pkgpart( $custom_part_pkg->pkgpart );
+ my $error = $c_pkg_svc->insert;
+ return "error customizing package: $error" if $error;
+ }
+
+ $cust_pkg->pkgpart( $custom_part_pkg->pkgpart );
+
+ }
+
+ my %order_pkg = ( 'cust_pkg' => $cust_pkg );
+
+ my @loc_fields = qw( address1 address2 city county state zip country );
+ if ( grep length($opt{$_}), @loc_fields ) {
+ $order_pkg{'cust_location'} = new FS::cust_location {
+ map { $_ => $opt{$_} } @loc_fields, 'custnum'
+ };
+ }
+
+ $order_pkg{'invoice_details'} = $opt{'invoice_details'}
+ if $opt{'invoice_details'};
+
+ my $error = $cust_main->order_pkg( %order_pkg );
+
+ #if ( $error ) {
+ return { 'error' => $error,
+ #'pkgnum' => '',
+ };
+ #} else {
+ # return { 'error' => '',
+ # #cust_main->order_pkg doesn't actually have a way to return pkgnum
+ # #'pkgnum' => $pkgnum,
+ # };
+ #}
+
+}
+
=item change_package_location
Updates package location. Takes a list of keys and values
-as paramters with the following keys:
+as parameters with the following keys:
pkgnum
}
-#next.. Advertising sources?
+#next.. Delete Advertising sources?
+
+=item list_advertising_sources OPTION => VALUE, ...
+
+Lists all advertising sources.
+
+=over
+
+=item secret
+
+API Secret
+
+=back
+
+Example:
+
+ my $result = FS::API->list_advertising_sources(
+ 'secret' => 'sharingiscaring',
+ );
+
+ if ( $result->{'error'} ) {
+ die $result->{'error'};
+ } else {
+ # list advertising sources returns an array of hashes for sources.
+ print Dumper($result->{'sources'});
+ }
+
+=cut
+
+#list_advertising_sources
+sub list_advertising_sources {
+ my( $class, %opt ) = @_;
+ return _shared_secret_error() unless _check_shared_secret($opt{secret});
+
+ my @sources = qsearch('part_referral', {}, '', "")
+ or return { 'error' => 'No referrals' };
+
+ my $return = {
+ 'sources' => [ map $_->hashref, @sources ],
+ };
+
+ $return;
+}
+
+=item add_advertising_source OPTION => VALUE, ...
+
+Add a new advertising source.
+
+=over
+
+=item secret
+
+API Secret
+
+=item referral
+
+Referral name
+
+=item disabled
+
+Referral disabled, Y for disabled or nothing for enabled
+
+=item agentnum
+
+Agent ID number
+
+=item title
+
+External referral ID
+
+=back
+
+Example:
+
+ my $result = FS::API->add_advertising_source(
+ 'secret' => 'sharingiscaring',
+ 'referral' => 'test referral',
+
+ #optional
+ 'disabled' => 'Y',
+ 'agentnum' => '2', #agent id number
+ 'title' => 'test title',
+ );
+
+ if ( $result->{'error'} ) {
+ die $result->{'error'};
+ } else {
+ # add_advertising_source returns new source upon success.
+ print Dumper($result);
+ }
+
+=cut
+
+#add_advertising_source
+sub add_advertising_source {
+ my( $class, %opt ) = @_;
+ return _shared_secret_error() unless _check_shared_secret($opt{secret});
+
+ use FS::part_referral;
+
+ my $new_source = $opt{source};
+
+ my $source = new FS::part_referral $new_source;
+
+ my $error = $source->insert;
+
+ my $return = {$source->hash};
+ $return = { 'error' => $error, } if $error;
+
+ $return;
+}
+
+=item edit_advertising_source OPTION => VALUE, ...
+
+Edit a advertising source.
+
+=over
+
+=item secret
+
+API Secret
+
+=item refnum
+
+Referral number to edit
+
+=item source
+
+hash of edited source fields.
+
+=over
+
+=item referral
+
+Referral name
+
+=item disabled
+
+Referral disabled, Y for disabled or nothing for enabled
+
+=item agentnum
+
+Agent ID number
+
+=item title
+
+External referral ID
+
+=back
+
+=back
+
+Example:
+
+ my $result = FS::API->edit_advertising_source(
+ 'secret' => 'sharingiscaring',
+ 'refnum' => '4', # referral number to edit
+ 'source' => {
+ #optional
+ 'referral' => 'test referral',
+ 'disabled' => 'Y',
+ 'agentnum' => '2', #agent id number
+ 'title' => 'test title',
+ }
+ );
+
+ if ( $result->{'error'} ) {
+ die $result->{'error'};
+ } else {
+ # edit_advertising_source returns updated source upon success.
+ print Dumper($result);
+ }
+
+=cut
+
+#edit_advertising_source
+sub edit_advertising_source {
+ my( $class, %opt ) = @_;
+ return _shared_secret_error() unless _check_shared_secret($opt{secret});
+
+ use FS::part_referral;
+
+ my $refnum = $opt{refnum};
+ my $source = $opt{source};
+
+ my $old = FS::Record::qsearchs('part_referral', {'refnum' => $refnum,});
+ my $new = new FS::part_referral { $old->hash };
+
+ foreach my $key (keys %$source) {
+ $new->$key($source->{$key});
+ }
+
+ my $error = $new->replace;
+
+ my $return = {$new->hash};
+ $return = { 'error' => $error, } if $error;
+
+ $return;
+}
+
+
+=item email_optout OPTION => VALUE, ...
+
+Each e-mail address, or L<FS::cust_contact> record, has two opt-in flags:
+message_dest: recieve non-invoicing messages, and invoice_dest: recieve
+invoicing messages
+
+Use this API call to remove opt-in flags for an e-mail address
+
+=over 4
+
+=item address
+
+E-Mail address
+
+=item disable_message_dest
+
+Enabled by default:
+Set this parameter as 0 in your API call to leave the message_dest flag as is
+
+=item disable_invoice_dest
+
+Enabled by default:
+Set this parameter as 0 in your API call to leave the invoice_dest flag as is
+
+=back
+
+=cut
+
+sub email_opt_out {
+ my ($class, %opt) = @_;
+
+ return _shared_secret_error()
+ unless _check_shared_secret($opt{secret});
+
+ return {error => 'No e-mail address specified'}
+ unless $opt{address} && $opt{address} =~ /\@/;
+
+ $opt{disable_message_dest} ||= 1;
+ $opt{disable_invoice_dest} ||= 1;
+
+ my $address = FS::Record::dbh->quote($opt{address});
+
+ for my $cust_contact (
+ FS::Record::qsearch({
+ table => 'cust_contact',
+ select => 'cust_contact.*',
+ addl_from => 'LEFT JOIN contact_email USING (contactnum)',
+ extra_sql => "WHERE contact_email.emailaddress = $address",
+ })
+ ) {
+ $cust_contact->set(invoice_dest => '') if $opt{disable_invoice_dest};
+ $cust_contact->set(message_dest => '') if $opt{disable_message_dest};
+
+ my $error = $cust_contact->replace();
+ return {error => $error} if $error;
+ }
+ return;
+}
##
return { 'error' => 'Incorrect shared secret' };
}
+
+=back
+
+=cut
+
1;
projects / freeside.git / blobdiff